rejig the apparatus for downloading scripts shown in the Guide

doc/gretl.sty.in

@@ -70,23 +70,31 @@
 \newenvironment{textcode}{\par\small\ttfamily}
 {\normalfont\normalsize\par}
 
+%% basic inline code style
 \DefineVerbatimEnvironment%
 {code}{Verbatim}
 {fontsize=\small, xleftmargin=1em}
 
+%% style for the first, or only, piece of hansl code inside
+%% a \script environment
 \DefineVerbatimEnvironment%
 {scode}{Verbatim}
 {frame=lines, framesep=2ex, fontsize=\small,
  formatcom=\color{myteal}, rulecolor=\color{mygray}}
 
+%% style for an incomplete piece of hansl code inside a
+%% a \script environment (without any horizontal rules)
 \DefineVerbatimEnvironment%
 {scodebit}{Verbatim}
 {fontsize=\small, formatcom=\color{myteal}}
 
+%% style for output to accompany hansl code inside a
+%% a \script environment
 \DefineVerbatimEnvironment%
 {outbit}{Verbatim}
 {fontsize=\small, formatcom=\color{myteal}}
 
+%% like scode above, but without the upper separator rule
 \DefineVerbatimEnvironment%
 {scodebot}{Verbatim}
 {frame=bottomline, framesep=2ex, fontsize=\small,
@@ -293,17 +301,21 @@
 \renewcommand{\l@section}{\@dottedtocline{1}{1.5em}{2.8em}}
 \renewcommand{\l@subsection}{\@dottedtocline{2}{4.3em}{3.2em}}
 
-%% for downloadable script examples
-\newcommand{\scriptcaption}[1]{%
-  \def\@scriptname{%
-    example-\ifnum\value{chapter}<10 0\fi\arabic{chapter}.\arabic{script}%
-  }
-  \caption{#1 %
-  \href{http://gretl.sourceforge.net/guidefiles/\@scriptname.inp}%
-  {[Download $\blacktriangledown$]}}%
+%% For downloadable example scripts which appear within \begin{script}
+%% and \end{script}: the first argument serves as the basename of the
+%% associated script file (".inp" will be added), and a \label{} is
+%% automatically constructed out of "ex:" plus this argument. The
+%% second argument is the caption text for the script.
+\newcommand{\scriptinfo}[2]{%
+  \def\@inpname{#1.inp}
+  \caption{#2 %
+  \href{http://gretl.sourceforge.net/guidefiles/\@inpname}%
+  {[Download $\blacktriangledown$]}}
+  \label{ex:#1}
 }
 
-%% for scripts that are incomplete or require special set-up
+%% for scripts that are incomplete or require special set-up --
+%% maybe redundant?
 \newcommand{\fragcaption}[1]{%
   \def\@scriptname{%
     example-\ifnum\value{chapter}<10 0\fi\arabic{chapter}.\arabic{script}%

doc/tex/calendar.tex

@@ -724,8 +724,7 @@ \section{Working with pre-Gregorian dates}
 switches calendar at the right historical point.
 
 \begin{script}[htbp]
-  \scriptcaption{Historical calendar for Britain in 1752}
-  \label{ex:britain-1752}
+  \scriptinfo{britain-1752}{Historical calendar for Britain in 1752}
 \begin{scodebit}
 # 1752 was a short year on the British calendar!
 nulldata 355
@@ -764,36 +763,15 @@ \section{Working with pre-Gregorian dates}
 the first column of the output) are still just index numbers. It may
 be preferable to have historical dates in that role. To achieve this
 we can decompose the \texttt{hcal} series into year, month and day,
-then use the special \texttt{genr markers} apparatus (see
-chapter~\ref{chap:datafiles}). Suitable code along with partial output
-is shown in Listing~\ref{ex:britain-1752a}.
-
-\begin{script}[htbp]
-  \scriptcaption{Continuation of Britain 1752 example}
-  \label{ex:britain-1752a}
-Additional input:
-\begin{scodebit}
+then use the \texttt{genr markers} apparatus (see
+chapter~\ref{chap:datafiles}). Here's additional code to do this job
+and show the result.
+\begin{code}
 series y, m, d
 isoconv(hcal, &y, &m, &d)
 genr markers = "%04d-%02d-%02d", y, m, d
 print ed jdate gdate hcal -o
-\end{scodebit}
-
-Partial output:
-\begin{outbit}
-                     ed        jdate        gdate         hcal
-
-1752-01-01       639551     17520101     17520112     17520101
-1752-01-02       639552     17520102     17520113     17520102
-...
-1752-09-01       639795     17520901     17520912     17520901
-1752-09-02       639796     17520902     17520913     17520902
-1752-09-14       639797     17520903     17520914     17520914
-1752-09-15       639798     17520904     17520915     17520915
-...
-1752-12-31       639905     17521220     17521231     17521231
-\end{outbit}
-\end{script}
+\end{code}
 
 \subsection{Year numbering}
 \label{sec:cal-yearnum}
@@ -808,8 +786,7 @@ \subsection{Year numbering}
 Listing~\ref{ex:britain-1751}.
 
 \begin{script}[htbp]
-  \scriptcaption{Historical calendar for England in 1751}
-  \label{ex:britain-1751}
+  \scriptinfo{britain-1751}{Historical calendar for England in 1751}
 Input:
 \begin{scodebit}
 nulldata 365 # a common year

doc/tex/cheatsheet.tex

@@ -810,9 +810,9 @@ \subsection{Interaction dummies}
 
 \emph{Solution:} As of version 1.9.12, gretl provides the
 \verb|^| operator to make this operation easy. See section
-\ref{sec:transform-lists} for details (especially example script
-\ref{ex:interact_list}). But back in my day, we used loops to do that!
-Here's how:
+\ref{sec:transform-lists} for details (especially
+Listing~\ref{ex:interaction-lists}). But back in my day,
+we used loops to do that! Here's how:
 
 \begin{code}
 list X = x1 x2 x3

doc/tex/complex_matrices.tex

@@ -246,11 +246,11 @@ \subsection{Mathematical}
 (complex argument), \cmd{conj} (complex conjugate), \cmd{Re}
 (real part) and \cmd{Im} (imaginary part). Note that
 $\mbox{carg}(z) = \mbox{atan2}(y,x)$ for $z=x +
-y\,i$. Listing~\ref{cmplx-modes} illustrates usage of \cmd{cmod}
+y\,i$. Listing~\ref{ex:complex-modes} illustrates usage of \cmd{cmod}
 and \cmd{carg}.
 
 \begin{script}[htbp]
-  \scriptcaption{Variant representations of complex numbers. We picked 8
+  \scriptinfo{complex-modes}{Variant representations of complex numbers. We picked 8
     points on the unit circle in the complex plane, so their modulus
     is constant and equal to 1. The \texttt{Polar} matrix below shows
     that the complex argument is expressed in radians; multiplying by
@@ -259,8 +259,7 @@ \subsection{Mathematical}
     from the polar form in either of the two ways mentioned at the
     start of the chapter: $z = |z|\,(\cos \theta + i\,\sin \theta)$ or
     $z = |z|\,e^{i\theta}$.}
-  \label{cmplx-modes}
-\begin{scodebit}
+\begin{scode}
 # complex values in a + b*i form
 scalar rp5 = sqrt(0.5)
 matrix A = {1, rp5, 0, -rp5, -1, -rp5,  0,  rp5}'
@@ -279,8 +278,7 @@ \subsection{Mathematical}
 matrix Z2 = zmod .* exp(complex(0, theta))
 matrix chk = Z ~ Z1 ~ Z2
 print chk
-\end{scodebit}
-
+\end{scode}
 
   Printing of \texttt{Polar} and \texttt{chk}
 \begin{outbit}
@@ -331,14 +329,13 @@ \section{File input/output}
 
 At present binary mode transfer of complex matrices is supported for
 \textsf{octave}, \textsf{python} and \textsf{julia}.
-Listing~\ref{cmplx-io} shows some examples: we export a complex matrix
+Listing~\ref{ex:complex-io} shows some examples: we export a complex matrix
 to each of these programs in turn; calculate its inverse in the
 foreign program; then verify that the result as imported back into
 gretl is the same as that calculated in gretl.
 
 \begin{script}[htbp]
-  \scriptcaption{Exporting and importing complex matrices}
-  \label{cmplx-io}
+  \scriptinfo{complex-io}{Exporting and importing complex matrices}
 \begin{scode}
 set seed 34756
 matrix C = complex(mnormal(3,3), mnormal(3,3))

doc/tex/datatypes.tex

@@ -378,7 +378,7 @@ \subsection{Series and lists as bundle members}
   (though it can always be extracted as a row vector).
 \end{itemize}
 
-The points made above are illustrated in Listing~\ref{bunlimits}.  In
+The points made above are illustrated in Listing~\ref{ex:bundle-limits}.  In
 ``Case 1'' we open a little dataset with just 14 cross-sectional
 observations and put a series into a bundle. We then open a
 time-series dataset with 64 observations, while preserving the bundle,
@@ -415,8 +415,7 @@ \subsection{Series and lists as bundle members}
 chapter~\ref{chap:matrices} for more on this.
 
 \begin{script}[htbp]
-  \scriptcaption{Series and lists in bundles}
-  \label{bunlimits}
+  \scriptinfo{bundle-limits}{Series and lists in bundles}
 \begin{scode}
 # Case 1: store and retrieve series, OK?
 open data4-1

doc/tex/df.tex

@@ -365,15 +365,14 @@ \subsection{VARs}
 VAR output.
 
 A fuller example of usage of the \dollar{xtxinv} accessor is given in
-Listing~\ref{GCtest}: this shows how one can replicate the $F$-tests
+Listing~\ref{ex:causality-test}: this shows how one can replicate the $F$-tests
 for Granger causality that are displayed by default by the \cmd{var}
 command, with the refinement that, depending on the setting of the
 \verb|USE_F| flag, these tests can be done using a small sample
 correction as in gretl's output or in asymptotic ($\chi^2$) form.
 
 \begin{script}[htbp]
-  \scriptcaption{Computing statistics to test for Granger causality}
-  \label{GCtest}
+  \scriptinfo{causality-test}{Computing statistics to test for Granger causality}
 \begin{scode}
 open denmark.gdt
 list LST = LRM LRY IBO IDE

doc/tex/dpanel.tex

@@ -793,14 +793,13 @@ \section{Cross-country growth example}
 refer to values five years prior to $t$, as in \cite{Bond2001}).
 
 The gretl script to do this job is shown in
-Listing~\ref{script:cel}. Note that the final transformed versions of
+Listing~\ref{ex:cel}. Note that the final transformed versions of
 the variables (logs, with time-means subtracted) are named \texttt{ly}
 ($y_{it}$), \texttt{linv} ($s_{it}$) and \texttt{lngd}
 ($n_{it} + g + \delta$).
 
 \begin{script}[htbp]
-  \scriptcaption{GDP growth example}
-  \label{script:cel}
+  \scriptinfo{cel}{GDP growth example}
 \begin{scode}
 open CEL.gdt
 
@@ -1044,12 +1043,11 @@ \section{Post-estimation available statistics}
 and \texttt{wgtmat} (which may be quite large matrices) are not saved
 in the \dollar{model} bundle by default; that requires use of the
 \option{keep-extra} option with the \cmd{dpanel}
-command. Listing~\ref{ex:dpanel-rep} illustrates use of these matrices
+command. Listing~\ref{ex:dpanel} illustrates use of these matrices
 to replicate via hansl commands the calculation of the GMM estimator.
 
 \begin{script}[p]
-  \scriptcaption{replication of built-in command via hansl commands}
-  \label{ex:dpanel-rep}
+  \scriptinfo{dpanel}{replication of built-in command via hansl commands}
 \begin{scode}
 set verbose off
 open abdata.gdt

doc/tex/extract.mk.in

@@ -1,12 +1,11 @@
 topsrc = @top_srcdir@
-auxdir = @abs_builddir@
 CC = @CC@
 
 texdir = $(topsrc)/doc/tex
 vpath %.c = $(texdir)
 
 scripts: extract_scripts
-	./extract_scripts $(texdir) $(auxdir)
+	./extract_scripts $(texdir)
 
 extract_scripts: extract_scripts.c
 	$(CC) -W -o $@ $<