\documentclass{article}
\usepackage{smallhds}
\usepackage{url}
\usepackage[body={6.0in,8.5in},top=1in,left=1.25in,nohead]{geometry}

\begin{document}

\title{Notes on the Gretl manual}
\author{Allin Cottrell\thanks{email: \texttt{cottrell@wfu.edu}}}
\date{Last updated January, 2007}

\maketitle

\setcounter{tocdepth}{1}
\tableofcontents

\section{Introduction}

This note describes the structure of the \textsf{gretl} manual and
gives information that may be useful to translators.

The gretl manual is divided into two main components, the
\textit{Gretl Command Reference} and the \textit{Gretl User's Guide}.
Translators may decide to work on one or both of these components.

The \textit{Command Reference} gives a complete listing of
\textsf{gretl} commands, with a short account of the function of each
command and any arguments and options.  The \textit{User's Guide} is
more discursive: it elaborates on the options available in the GUI
program, expands on the use of some of the more complex commands, and
provides various technical appendices.

Both the \textit{Command Reference} and the \textit{User's Guide} are
produced in PDF format.  In addition, the source material for the
\textit{Command Reference} is used to create the plain text files that
compose the ``online'' help available within \textsf{gretl}.  The
source files for the \textit{Command Reference} are in XML format and
the source files for the \textit{User's Guide} are in \LaTeX.

\section{Getting the manual files}
\label{getit}

The way to get current copies of the manual files is via CVS; see
either 
%
\begin{center}
\url{http://gretl.cvs.sourceforge.net/gretl/gretl/}
\end{center}
%
or 
%
\begin{center}
\url{http://sourceforge.net/cvs/?group_id=36234}
\end{center}

If you would like to have translator access to \textsf{gretl} CVS,
pleas let me know; that can easily be arranged. 

\section{Files for translation}

\subsection{Command reference files}

Table~\ref{cmd-files} gives a listing of the source files for the
English version of the \textit{Gretl Command Reference}.  The paths
are relative to the \texttt{doc} directory of the \textsf{gretl}
source tree in CVS.  On the right we show the corresponding paths for
translated versions of these files, using Italian as an example.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{ll}
\url{chapters/cmdref.xml} & \url{chapters_it/cmdref.xml} \\
\url{chapters/optarg.xml} & \url{chapters_it/optarg.xml} \\
\url{commands/gretl_commands.xml} & \url{commands/gretl_commands_it.xml}
\end{tabular}
\end{center}
\caption{Command reference source files}
\label{cmd-files}
\end{table}

The first two files (in the \texttt{chapters} directory) are in
DocBook XML format; the third file is in a custom XML format
for ease of conversion to plain text and \TeX.

\subsection{User's guide files}

Table~\ref{guide-files} lists the current \TeX\ source files for the
\textit{Gretl User's Guide}, again showing the English files on the
left and the Italian equivalent on the right.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{ll}
\multicolumn{1}{c}{\textit{English}} & 
\multicolumn{1}{c}{\textit{Italian}} \\[6pt]
\multicolumn{2}{l}{``driver'' files} \\
\url{tex/gretl-guide.tex} & \url{tex_it/gretl-guide-es.tex} \\
\url{tex/gretl-ref.tex} & \url{tex_it/gretl-ref-es.tex} \\[6pt]
\multicolumn{2}{l}{chapter files} \\
\url{tex/appendices.tex} & \url{tex_it/appendices.tex} \\
\url{tex/cli.tex} & \url{tex_it/cli.tex} \\
\url{tex/criteria.tex} & \url{tex_it/criteria.tex} \\
\url{tex/datafiles.tex} & \url{tex_it/datafiles.tex} \\
\url{tex/discrete.tex} & \url{tex_it/discrete.tex} \\
\url{tex/functions.tex} & \url{tex_it/functions.tex} \\
\url{tex/genr.tex} & \url{tex_it/genr.tex} \\
\url{tex/graphs.tex} & \url{tex_it/graphs.tex} \\
\url{tex/gretltex.tex} & \url{tex_it/gretltex.tex} \\
\url{tex/introduction.tex} & \url{tex_it/introduction.tex} \\
\url{tex/looping.tex} & \url{tex_it/looping.tex} \\
\url{tex/matrices.tex} & \url{tex_it/matrices.tex} \\
\url{tex/mle.tex} & \url{tex_it/mle.tex} \\
\url{tex/modes.tex} & \url{tex_it/modes.tex} \\
\url{tex/nls.tex} & \url{tex_it/nls.tex} \\
\url{tex/panel.tex} & \url{tex_it/panel.tex} \\
\url{tex/persistent.tex} & \url{tex_it/persistent.tex} \\
\url{tex/probit.tex} & \url{tex_it/probit.tex} \\
\url{tex/sampling.tex} & \url{tex_it/sampling.tex} \\
\url{tex/starting.tex} & \url{tex_it/starting.tex} \\
\url{tex/timeseries.tex} & \url{tex_it/timeseries.tex} \\
\url{tex/trouble.tex} & \url{tex_it/trouble.tex} \\[6pt]
\multicolumn{2}{l}{bibliography file} \\
\url{tex/biblio.tex} & \url{tex_it/biblio.tex} \\
\end{tabular}
\end{center}
\caption{User's guide \TeX\ source files}
\label{guide-files}
\end{table}

A small amount of translation is called for in the ``driver'' files
(titles and license, primarily).  The main work of translation is in
the ``chapter files.''  The bibliography (\texttt{biblio.tex}) may not
need translation at all.

\section{Screenshot graphics}

The \textit{User's Guide} contains various ``screenshots'' of
\textsf{gretl} windows.  If these are to be shown in the language of
the translation, the appropriate graphic files (in \textsf{PNG}
format) should be placed in a top-level sub-directory of the
\textsf{gretl} documentation tree named \texttt{figures\_xx} (e.g.\ 
\texttt{figures\_it} or \texttt{figures\_it}).  The Italian and
Spanish translations already have such files in place.

You may wish to alter the scaling of graphics in the translated
manuals.  As you'll see if you look at the \TeX\ sources, I have
scaled almost all the ``screenshot'' graphics to 50 percent of
``natural'' size.  If you think the result is too small, feel free to
adjust the scaling.


\section{Automatically generated files}

In the course of building the gretl manual, various files are
generated automatically.  I point this out here to try to avoid
misunderstanding: I don't want anyone to spend time translating a
file that will be automatically over-written whenever the manual is
built!  The main files in this category are
%
\url{chapters_xx/cmdlist.xml}
\url{chapters_xx/cmdtopics.xml}
%
and
%
\url{tex_xx/refbody.tex},
%
where \texttt{xx} is a placeholder for a two-letter language code
such as \texttt{es} or \texttt{it}.  

The first of these, \url{chapters_xx/cmdlist.xml}, is a file in
DocBook XML format that is generated automatically via XSL
transformation, using the file \url{commands/gretl_commands_xx.xml} as
a basis.  

The second is a further derivative of
\url{commands/gretl_commands_xx.xml}, this time converted into \TeX\ 
for the purpose of building the \textit{Gretl Command Reference} in
PDF.

\section{Handling of script/code fragments}

At various points in the manuals there are snippets or fragments of
\textsf{gretl} script, enclosed in some sort of verbatim environment.
One point to note about these snippets is that they should be given an
overall indent of zero on the \TeX\ source files; that is, they should
be placed against the left margin (though it's OK to give some of the
material a \textit{relative} indent---for example, code within
\texttt{loop} and \texttt{end loop}).  The overall indent of such
material is controlled by a style file.

\section{Current status of translations}

At present there are two translations of the \textsf{gretl} manual,
into Italian and Spanish.  The Italian translation is up to date with
the English version---which is not yet fully up to date with
\textsf{gretl} itself.

The Spanish version is now a little dated and lacks several of the
chapters in the current English and Italian versions.  

\section{Making the PDF files}

To see what your translation looks like, you may wish to build the PDF
files for the \textit{Command Reference} and/or the \textit{User's
  Guide}.

Probably the best way to do this is to go into the \texttt{tex\_xx}
sub-directory corresponding to your language and do the following
(I'll illustrate with Italian here).  To build the \textit{User's
  Guide},

\begin{verbatim}
make gretl-guide-it.pdf
\end{verbatim}

This should be reasonably straightforward.  You will need a working
\TeX\ installation including \textsf{pdflatex}.  But you'll hit a
problem if you don't have the \textsf{Lucida} fonts---in that case you
can edit the driver file (e.g.\ \texttt{gretl-guide-it.tex}) and
comment out the line
%
\begin{verbatim}
\usepackage{lucidabr}
\end{verbatim}
%
Then you should get the PDF file using the \TeX\ Computer Modern
fonts.

As for the \textit{Command Reference}, this is a little more
complicated since some XSL transformations of the sources are needed.
You'll probably need to build the program \textsf{xsltrans} in the
\texttt{commands} sub-directory, from C source, and you'll also need
to have the program \textsf{xsltproc} (supplied with the
\textsf{libxml2} distribution) in your path.

To build \textsf{xsltrans}, starting from the top level of the
\textsf{gretl} documentation tree, do

\begin{verbatim}
cd commands
make -f cmdref.mk xsltrans
\end{verbatim}

Then go into your \texttt{tex\_xx} directory (e.g.\ \texttt{tex\_it})
and do:

\begin{verbatim}
make refbody.tex
make gretl-ref-it.pdf
\end{verbatim}

Please let me know if you have problems building the PDF.

\section{Reference builds of the manual files}

For reference, I have made available PDF files built from the current
sources in English (US letter paper and A4), Italian and Spanish.
Please see

\begin{center}
\url{http://ricardo.ecn.wfu.edu/pub/gretl/manual/} 
\end{center}

\end{document}

