\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, 2008} \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 \textsf{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 ``online'' help that is available within \textsf{gretl}. The source files for the \textit{Command Reference} are (mostly) 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{tex/gretl-ref.tex} & \url{tex_it/gretl-ref-it.tex} \\ \url{tex/cmdref.tex} & \url{tex_it/cmdref.tex} \\ \url{tex/funcref.tex} & \url{tex_it/funcref.tex} \\ \url{tex/optarg.tex} & \url{tex_it/optarg.tex} \\[4pt] \url{commands/gretl_commands.xml} & \url{commands/gretl_commands_it.xml} \\ \url{commands/genr_funcs.xml} & \url{commands/genr_funcs_it.xml} \end{tabular} \end{center} \caption{Command reference source files} \label{cmd-files} \end{table} The two files in the \texttt{commands} directory are in XML format; all the others are in \TeX. Translators do not need to have knowledge of either of these formats, just the common sense not to try to translate terms that are (fairly obviously) part of the mark-up apparatus. \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'' file} \\ \url{tex/gretl-guide.tex} & \url{tex_it/gretl-guide-it.tex} \\[6pt] \multicolumn{2}{l}{chapter files} \\ \url{tex/appendices.tex} & \url{tex_it/appendices.tex} \\ \url{tex/cheatsheet.tex} & \url{tex_it/cheatsheet.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/gmm.tex} & \url{tex_it/gmm.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/robust_vcv.tex} & \url{tex_it/robust_vcv.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} \\ \url{tex/vecm.tex} & \url{tex_it/vecm.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\_es}). 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 \begin{center} \begin{tabular}{l} \url{tex_xx/refbody.tex}\\ \url{tex_xx/cmdtopics.tex}\\ \url{tex_xx/funcbody.tex}\\ \end{tabular} \end{center} \noindent where \texttt{xx} is a placeholder for a two-letter language code such as \texttt{es} or \texttt{it}. These files are generated via XSL transformations, using the files \url{commands/gretl_commands_xx.xml} and \url{commands/genr_funcs_xx.xml}, as well as the \textsf{gretl} C sources, as a basis. \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 in 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 have a checkout of the \textsf{gretl} CVS sources, configured using the flag \verb|--enable-build-doc|. In that case you can go into your \texttt{tex\_xx} directory (e.g.\ \texttt{tex\_it}) and do: % \begin{verbatim} make gretl-ref-xx.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}