"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2020e/doc/notes.tex" (2 Oct 2015, 9514 Bytes) of package /linux/misc/gretl-2020e.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \documentclass{article}
    2 \usepackage{smallhds}
    3 \usepackage{url}
    4 \usepackage[body={6.0in,8.5in},top=1in,left=1.25in,nohead]{geometry}
    5 
    6 \begin{document}
    7 
    8 \title{Notes on the Gretl manual}
    9 \author{Allin Cottrell\thanks{email: \texttt{cottrell@wfu.edu}}}
   10 \date{Last updated January, 2008}
   11 
   12 \maketitle
   13 
   14 \setcounter{tocdepth}{1}
   15 \tableofcontents
   16 
   17 \section{Introduction}
   18 
   19 This note describes the structure of the \textsf{gretl} manual and
   20 gives information that may be useful to translators.
   21 
   22 The \textsf{gretl} manual is divided into two main components, the
   23 \textit{Gretl Command Reference} and the \textit{Gretl User's Guide}.
   24 Translators may decide to work on one or both of these components.
   25 
   26 The \textit{Command Reference} gives a complete listing of
   27 \textsf{gretl} commands, with a short account of the function of each
   28 command and any arguments and options.  The \textit{User's Guide} is
   29 more discursive: it elaborates on the options available in the GUI
   30 program, expands on the use of some of the more complex commands, and
   31 provides various technical appendices.
   32 
   33 Both the \textit{Command Reference} and the \textit{User's Guide} are
   34 produced in PDF format.  In addition, the source material for the
   35 \textit{Command Reference} is used to create the ``online'' help that
   36 is available within \textsf{gretl}.  The source files for the
   37 \textit{Command Reference} are (mostly) in XML format and the source
   38 files for the \textit{User's Guide} are in \LaTeX.
   39 
   40 \section{Getting the manual files}
   41 \label{getit}
   42 
   43 The way to get current copies of the manual files is via CVS; see
   44 either 
   45 %
   46 \begin{center}
   47 \url{http://gretl.cvs.sourceforge.net/gretl/gretl/}
   48 \end{center}
   49 %
   50 or 
   51 %
   52 \begin{center}
   53 \url{http://sourceforge.net/cvs/?group_id=36234}
   54 \end{center}
   55 
   56 If you would like to have translator access to \textsf{gretl} CVS,
   57 pleas let me know; that can easily be arranged. 
   58 
   59 \section{Files for translation}
   60 
   61 \subsection{Command reference files}
   62 
   63 Table~\ref{cmd-files} gives a listing of the source files for the
   64 English version of the \textit{Gretl Command Reference}.  The paths
   65 are relative to the \texttt{doc} directory of the \textsf{gretl}
   66 source tree in CVS.  On the right we show the corresponding paths for
   67 translated versions of these files, using Italian as an example.
   68 
   69 \begin{table}[htbp]
   70 \begin{center}
   71 \begin{tabular}{ll}
   72 \url{tex/gretl-ref.tex}  & \url{tex_it/gretl-ref-it.tex} \\
   73 \url{tex/cmdref.tex}     & \url{tex_it/cmdref.tex} \\
   74 \url{tex/funcref.tex}    & \url{tex_it/funcref.tex} \\
   75 \url{tex/optarg.tex}     & \url{tex_it/optarg.tex} \\[4pt]
   76 \url{commands/gretl_commands.xml} & \url{commands/gretl_commands_it.xml} \\
   77 \url{commands/genr_funcs.xml} & \url{commands/genr_funcs_it.xml}
   78 \end{tabular}
   79 \end{center}
   80 \caption{Command reference source files}
   81 \label{cmd-files}
   82 \end{table}
   83 
   84 The two files in the \texttt{commands} directory are in XML format;
   85 all the others are in \TeX.  Translators do not need to have knowledge
   86 of either of these formats, just the common sense not to try to
   87 translate terms that are (fairly obviously) part of the mark-up
   88 apparatus.
   89 
   90 \subsection{User's guide files}
   91 
   92 Table~\ref{guide-files} lists the current \TeX\ source files for the
   93 \textit{Gretl User's Guide}, again showing the English files on the
   94 left and the Italian equivalent on the right.
   95 
   96 \begin{table}[htbp]
   97 \begin{center}
   98 \begin{tabular}{ll}
   99 \multicolumn{1}{c}{\textit{English}} & 
  100 \multicolumn{1}{c}{\textit{Italian}} \\[6pt]
  101 \multicolumn{2}{l}{``driver'' file} \\
  102 \url{tex/gretl-guide.tex} & \url{tex_it/gretl-guide-it.tex} \\[6pt]
  103 \multicolumn{2}{l}{chapter files} \\
  104 \url{tex/appendices.tex} & \url{tex_it/appendices.tex} \\
  105 \url{tex/cheatsheet.tex} & \url{tex_it/cheatsheet.tex} \\
  106 \url{tex/cli.tex} & \url{tex_it/cli.tex} \\
  107 \url{tex/criteria.tex} & \url{tex_it/criteria.tex} \\
  108 \url{tex/datafiles.tex} & \url{tex_it/datafiles.tex} \\
  109 \url{tex/discrete.tex} & \url{tex_it/discrete.tex} \\
  110 \url{tex/functions.tex} & \url{tex_it/functions.tex} \\
  111 \url{tex/genr.tex} & \url{tex_it/genr.tex} \\
  112 \url{tex/gmm.tex} & \url{tex_it/gmm.tex} \\
  113 \url{tex/graphs.tex} & \url{tex_it/graphs.tex} \\
  114 \url{tex/gretltex.tex} & \url{tex_it/gretltex.tex} \\
  115 \url{tex/introduction.tex} & \url{tex_it/introduction.tex} \\
  116 \url{tex/looping.tex} & \url{tex_it/looping.tex} \\
  117 \url{tex/matrices.tex} & \url{tex_it/matrices.tex} \\
  118 \url{tex/mle.tex} & \url{tex_it/mle.tex} \\
  119 \url{tex/modes.tex} & \url{tex_it/modes.tex} \\
  120 \url{tex/nls.tex} & \url{tex_it/nls.tex} \\
  121 \url{tex/panel.tex} & \url{tex_it/panel.tex} \\
  122 \url{tex/persistent.tex} & \url{tex_it/persistent.tex} \\
  123 \url{tex/probit.tex} & \url{tex_it/probit.tex} \\
  124 \url{tex/robust_vcv.tex} & \url{tex_it/robust_vcv.tex} \\
  125 \url{tex/sampling.tex} & \url{tex_it/sampling.tex} \\
  126 \url{tex/starting.tex} & \url{tex_it/starting.tex} \\
  127 \url{tex/timeseries.tex} & \url{tex_it/timeseries.tex} \\
  128 \url{tex/trouble.tex} & \url{tex_it/trouble.tex} \\
  129 \url{tex/vecm.tex} & \url{tex_it/vecm.tex} \\ [6pt]
  130 \multicolumn{2}{l}{bibliography file} \\
  131 \url{tex/biblio.tex} & \url{tex_it/biblio.tex} \\
  132 \end{tabular}
  133 \end{center}
  134 \caption{User's guide \TeX\ source files}
  135 \label{guide-files}
  136 \end{table}
  137 
  138 A small amount of translation is called for in the ``driver'' files
  139 (titles and license, primarily).  The main work of translation is in
  140 the ``chapter files.''  The bibliography (\texttt{biblio.tex}) may not
  141 need translation at all.
  142 
  143 \section{Screenshot graphics}
  144 
  145 The \textit{User's Guide} contains various ``screenshots'' of
  146 \textsf{gretl} windows.  If these are to be shown in the language of
  147 the translation, the appropriate graphic files (in \textsf{PNG}
  148 format) should be placed in a top-level sub-directory of the
  149 \textsf{gretl} documentation tree named \texttt{figures\_xx} (e.g.\ 
  150 \texttt{figures\_it} or \texttt{figures\_es}).  The Italian and
  151 Spanish translations already have such files in place.
  152 
  153 You may wish to alter the scaling of graphics in the translated
  154 manuals.  As you'll see if you look at the \TeX\ sources, I have
  155 scaled almost all the ``screenshot'' graphics to 50 percent of
  156 ``natural'' size.  If you think the result is too small, feel free to
  157 adjust the scaling.
  158 
  159 
  160 \section{Automatically generated files}
  161 
  162 In the course of building the gretl manual, various files are
  163 generated automatically.  I point this out here to try to avoid
  164 misunderstanding: I don't want anyone to spend time translating a
  165 file that will be automatically over-written whenever the manual is
  166 built!  The main files in this category are
  167 
  168 \begin{center}
  169 \begin{tabular}{l}
  170 \url{tex_xx/refbody.tex}\\
  171 \url{tex_xx/cmdtopics.tex}\\
  172 \url{tex_xx/funcbody.tex}\\
  173 \end{tabular}
  174 \end{center}
  175 
  176 \noindent
  177 where \texttt{xx} is a placeholder for a two-letter language code
  178 such as \texttt{es} or \texttt{it}.  
  179 
  180 These files are generated via XSL transformations, using the files
  181 \url{commands/gretl_commands_xx.xml} and
  182 \url{commands/genr_funcs_xx.xml}, as well as the \textsf{gretl} C
  183 sources, as a basis.
  184 
  185 
  186 \section{Handling of script/code fragments}
  187 
  188 At various points in the manuals there are snippets or fragments of
  189 \textsf{gretl} script, enclosed in some sort of verbatim environment.
  190 One point to note about these snippets is that they should be given an
  191 overall indent of zero in the \TeX\ source files; that is, they should
  192 be placed against the left margin (though it's OK to give some of the
  193 material a \textit{relative} indent---for example, code within
  194 \texttt{loop} and \texttt{end loop}).  The overall indent of such
  195 material is controlled by a style file.
  196 
  197 \section{Current status of translations}
  198 
  199 At present there are two translations of the \textsf{gretl} manual,
  200 into Italian and Spanish.  The Italian translation is up to date with
  201 the English version---which is not yet fully up to date with
  202 \textsf{gretl} itself.
  203 
  204 The Spanish version is now a little dated and lacks several of the
  205 chapters in the current English and Italian versions.  
  206 
  207 \section{Making the PDF files}
  208 
  209 To see what your translation looks like, you may wish to build the PDF
  210 files for the \textit{Command Reference} and/or the \textit{User's
  211   Guide}.
  212 
  213 Probably the best way to do this is to go into the \texttt{tex\_xx}
  214 sub-directory corresponding to your language and do the following
  215 (I'll illustrate with Italian here).  To build the \textit{User's
  216   Guide},
  217 
  218 \begin{verbatim}
  219 make gretl-guide-it.pdf
  220 \end{verbatim}
  221 
  222 This should be reasonably straightforward.  You will need a working
  223 \TeX\ installation including \textsf{pdflatex}.  But you'll hit a
  224 problem if you don't have the \textsf{Lucida} fonts---in that case you
  225 can edit the driver file (e.g.\ \texttt{gretl-guide-it.tex}) and
  226 comment out the line
  227 %
  228 \begin{verbatim}
  229 \usepackage{lucidabr}
  230 \end{verbatim}
  231 %
  232 Then you should get the PDF file using the \TeX\ Computer Modern
  233 fonts.
  234 
  235 As for the \textit{Command Reference}, this is a little more
  236 complicated since some XSL transformations of the sources are needed.
  237 You'll probably need to have a checkout of the \textsf{gretl} CVS
  238 sources, configured using the flag \verb|--enable-build-doc|.  In that
  239 case you can go into your \texttt{tex\_xx} directory (e.g.\
  240 \texttt{tex\_it}) and do:
  241 %
  242 \begin{verbatim}
  243 make gretl-ref-xx.pdf
  244 \end{verbatim}
  245 %
  246 Please let me know if you have problems building the PDF.
  247 
  248 \section{Reference builds of the manual files}
  249 
  250 For reference, I have made available PDF files built from the current
  251 sources in English (US letter paper and A4), Italian and Spanish.
  252 Please see
  253 
  254 \begin{center}
  255 \url{http://ricardo.ecn.wfu.edu/pub/gretl/manual/} 
  256 \end{center}
  257 
  258 \end{document}
  259