\documentclass[11pt]{article}
\usepackage[body={6.5in,9in},top=1in,left=1in,nohead]{geometry}
\usepackage[pdftex]{color}
\usepackage[urlcolor=blue]{hyperref}
\usepackage{myguide}
\usepackage[T1]{fontenc}
\usepackage{lucidabr}

\hypersetup{pdftitle={README for Gretl on OS X},
  pdfsubject={gretl},
  pdfauthor={Allin Cottrell},
  pdfkeywords={},
  pdfpagemode={None},
  colorlinks=true
}

\begin{document}

\begin{center}
{\color{gold} \titlefont gretl} \\[1ex]
version 1.9.11 for Mac OS X \\[2ex]

\textit{GNU Regression, Econometrics and Time-series Library\\
  This is free software under the GNU General Public License.}

\end{center}

This package was tested on Mac OS X 10.6.8 (Snow Leopard) and
is also known to work on OS X 10.7 (Lion) and 10.8 (Mountain Lion).
Hopefully it will work on later releases of OS X but it will probably
not work on releases earlier than 10.4.

\section{Prerequisites}
\label{sec:os}

To run \textsf{gretl} you will need Apple's version of the \textbf{X11
  window system}. This was automatically installed with OS X 10.6 and
10.7, but if you're using Mountain Lion you need to download XQuartz
from \texttt{macosforge}

\url{http://xquartz.macosforge.org/landing/}

and install it yourself. (In OS X versions prior to 10.6, Apple's X11 was 
available as an optional install from the distribution DVD.)

\textsf{Gretl} also requires the \textbf{GTK+ Framework}, which can be
found at the following location:

\url{http://sourceforge.net/projects/gretl/files/osx/GTK+.framework.dmg/download}

To install GTK+, open the disk image and drag the
\texttt{GTK+.framework} folder onto the \texttt{Frameworks}
folder. You may get an error message if another version of the GTK
framework is already installed. In that case you can do, at the
command prompt in a terminal window:

\verb|sudo rm -rf /Library/Frameworks/GTK+.framework|

or, if you want to preserve the existing version in case you need to
restore it later,
\begin{verbatim}
sudo mv /Library/Frameworks/GTK+.framework \
  /Library/Frameworks/GTK+.framework.old
\end{verbatim}

Then try the drag again. Once you're done you can eject the
disk image and delete the \texttt{.dmg} file.

\section{Installating the program}
\label{sec:install}

\textsf{Gretl} is distributed as a gzipped disk-image
(\texttt{.dmg.gz}).  Double-click to unzip it first.  Once you have a
\texttt{.dmg} file, double-click to mount the image, and open the
image in the Finder. (This may all happen automatically when you
double-click the \texttt{.dmg.gz} file.) Then drag \textsf{Gretl} to
somewhere suitable on your system (preferably your
\textsf{Applications} folder).  Once that is done, you can eject the
disk image and delete the \texttt{.dmg} and \texttt{.dmg.gz} files.

If you already have an older version of \textsf{Gretl} installed, the
update via dragging may fail. In that case you should open the
\textsf{Applications} folder in the Finder, delete the \textsf{Gretl}
item, then try the drag again.

To run gretl, double-click on the gretl program icon.  You can drag
this icon onto the dock if you want a quick launcher.

\section{Trouble-shooting}

If double-clicking on the gretl icon doesn't work for you, try
starting X11, opening an xterm, navigating into the \textsf{bin}
folder inside \textsf{Gretl.app}, and executing 
\textsf{gretl} manually.  That is, do something like:

\begin{verbatim}
cd /Applications/Gretl.app/Contents/Resources/bin
./gretl
\end{verbatim}

Hopefully this will give you an informative error message.

If you are updating from a previous installation of gretl, it
is possible that your recorded user preferences may be out of
sync with current gretl.  The fix for that is to delete
your old preferences file.  In an xterm window, do:

\begin{verbatim}
rm -f ~/.gretl2rc
\end{verbatim}

\section{An oddity on Mountain Lion}

It appears that in some cases dragging \textsf{Gretl} from the disk
image to the \textsf{Applications} folder does not work correctly:
certain shared library files may get truncated to zero bytes. If that
happens it may be necessary to copy the files manually. To do this,
open the Mac Terminal application, and at the command line type

\begin{verbatim}
sudo rm -rf /Applications/Gretl.app
\end{verbatim}

then

\begin{verbatim}
cp -r /Volumes/gretl/Gretl.app /Applications
\end{verbatim}

or if you get ``permission denied,'' do it as the administrator:

\begin{verbatim}
sudo cp -r /Volumes/gretl/Gretl.app /Applications
\end{verbatim}

\section{Documentation}
\label{sec:doc}

When you start gretl, please consult the program's Help menu for
documentation in various formats.

\vspace{.25in}

\raggedright
Allin Cottrell \\
Wake Forest University \\
\texttt{cottrell@wfu.edu} \\
November, 2012

\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
