--- pkgbook.tex.me	2015-08-05 09:13:52.081096009 -0400
+++ pkgbook.tex	2015-08-05 09:13:59.711095962 -0400
@@ -1,5 +1,5 @@
 \documentclass[oneside]{book}
-\usepackage{url,verbatim,fancyvrb}
+\usepackage{doc,url,verbatim,fancyvrb}
 \usepackage{pifont}
 \usepackage[latin1]{inputenc}
 \usepackage[pdftex]{graphicx}
@@ -713,26 +713,25 @@
 \chapter{For package authors}
 \label{chap:authors}
 
-As we said in section~\ref{sec:pkgform}, a ``simple'' function package
-is an XML file with extension \texttt{gfn}, which contains four
-separate items:
+Recall from section~\ref{sec:pkgform} that the core elements 
+of a gretl function package are as follows:
 \begin{enumerate}
 \item One or more hansl functions;
 \item the package metadata (author, version and so on);
 \item some documentation (at least a few lines of text); and
 \item an example script.
 \end{enumerate}
-These are the four vital elements of a function package, which are all
-contained in the \texttt{gfn} file. Then, optionally, you can ship
-additional material with your package, such as PDF documentation, a
-richer assortment of sample script, and so forth. In this case, you
-will want to wrap these into a zipfile, together with the package file
-proper.
-[FIXME too repetitive of first chapter?]
-
-This chapter explains how to build a gretl function packages using
-either command-line methods (section~\ref{sec:cli-build}) or gretl's
-graphical interface. 
+These elements are all contained in a \texttt{gfn} XML file.
+Optionally, you can ship additional material with your package (PDF
+documentation, a richer assortment of sample scripts, and so forth),
+in which case all the components including the \textsf{gfn} must be
+wrapped in a zip file.
+
+In this chapter, we will go through the creation and maintenance of
+these basic ingredients, plus the process of baking them together into
+a working function package. There are two ways to achieve this result:
+by using either command-line methods (section~\ref{sec:cli-build}) or
+by taking advantage of gretl's graphical interface.
 
 A word of advice: ``In the beginning was the command line'' (Neal
 Stephenson), so we'll start with CLI methods for building a
@@ -741,9 +740,9 @@
 skipping forward.  The command-line approach is likely to pay off if
 you ever decide to tackle an ambitious function-package project. This
 is going to be somewhat Unix-centric, so Linux and OS X users should
-find themselves at home. If your preferred operating is Windows, a few
-tips on the necessary software tools are given in a short appendix to
-this chapter.
+find themselves at home. If your preferred operating system is
+Windows, a few tips on the necessary software tools are given in a
+short appendix to this chapter.
 
 % (\ref{sec:gui-build}). Section~\ref{sec:common-req} covers some common
 % requirements that are important regardless of how the package is
@@ -752,12 +751,12 @@
 \section{Building a package via the command line}
 \label{sec:cli-build}
 
-Here, we assume you have a decent familiarity with the shell (often
-called the ``terminal'') and its basic commands. So we assume you know
-how to perform simple operating-system tasks, such as copying/deleting
-files, listing the contents of a directory and so on via the
-appropriate shell commands (\cmd{cp}, \cmd{rm}, \cmd{ls}, \cmd{cd},
-etc.).
+Here we assume you are somewhat familiar with the shell---that is,
+the command processor which awaits your input when you open a terminal
+window. So we assume you know how to perform simple operating-system
+tasks such as copying/deleting files, listing the contents of a
+directory and so on via the appropriate shell commands (\cmd{cp},
+\cmd{rm}, \cmd{ls}, \cmd{cd}, and so on).
 
 First of all, we strongly recommend that when starting work on a
 package you create a specific directory to hold the makings of the
@@ -787,13 +786,12 @@
   call this \texttt{mypkg\_help.txt}.
 \end{enumerate}
 
-Note: the four files listed above are all text files that you can view
-and modify by using any editor of your choice. Moreover, there is a
-one-to-one correspondence between any of them and the four basic
-constituents of a \texttt{gfn} file. Therefore, once you have these
-four files ready, building the package is a simple matter of
-translating their contents to XML and putting everything together into
-the package file.
+The four files listed above are all UTF-8 text files that you can view
+and modify using any text editor of your choice. Each text file
+corresponds to one of the four basic constituents of a \texttt{gfn}
+file. Therefore, once you have these four files ready, building the
+package is simply a matter of transcribing their contents into XML and
+putting everything together into the package file.
 
 You will need to create such files in the current directory (or maybe
 copy or move them from elsewhere if you've already made a start). It's
@@ -852,6 +850,11 @@
 include mypkg.inp
 makepkg mypkg.gfn
 \end{code}
+You can further abbreviate the above by using the ``short'' syntax for
+options, as in 
+\begin{code}
+gretlcli -m mypkg.inp
+\end{code}
 
 We've said this package offers a single public function,
 \texttt{myfunc}: that's the only function that will be made directly
@@ -867,6 +870,98 @@
   file. When using \texttt{makepkg} you should always start with a
   clean workspace and load only the relevant functions.}
 
+\subsection{Adding extra material}
+
+Suppose now that you want to distribute it together with
+some extra material (say, a data file). As explained earlier (again,
+see section~\ref{sec:pkgform}), you will have to create a suitably
+organized zip file.
+
+In order to do so, the first thing is updating the \texttt{spec} file
+to that effect: therefore, you'll want to add a line like
+\begin{code}
+data-files = somedata.gdt
+\end{code}
+to it. We assume that the \texttt{somedata.gdt} file exists and is in
+the \texttt{mypkg} directory. One possibility is creating the zip file
+``by hand'':
+\begin{code}
+cd ..
+zip mypkg/mypkg.zip mypkg/ mypkg/mypkg.gfn mypkg/somedata.gdt  
+\end{code}
+
+Alternatively, you can have gretl take care of everything for you, by
+by using the \cmd{makepkg} command: you can start \app{gretlcli} and
+issue the following command:
+%
+\begin{code}
+makepkg mypkg.zip
+\end{code}
+%
+When the argument to \cmd{makepkg} is a filename with the \textsf{zip}
+extension, gretl will do one of two things:
+\begin{itemize}
+\item If a matching \textsf{gfn} file is found, this will be used the
+  as the basis for the zipfile, with other components pulled in as
+  needed.
+\item Failing that, if a matching \textsf{spec} file is found (plus
+  the other files that it references), gretl will first build the
+  \textsf{gfn}, then build the zipfile wrapper.
+\end{itemize}
+
+An even neater way to do this is to ``pipe'' the above comand into
+\app{gretlcli} directly form the command line, as in
+\begin{code}
+echo "makepkg mypkg.zip" | gretlcli -q -b
+\end{code}
+
+\subsection{Uploading your package}
+
+This relies on the \app{curl} program, which is standard kit on
+platforms other than MS Windows.\footnote{For a Windows version of
+  \textsf{curl} see \url{http://curl.haxx.se/download.html}. But if
+  you decide to endow your Windows box with a few Unixy tools using
+  the approach described in Appendix A, \app{curl} is just one of the
+  many goodies you get nearly automatically.}
+Example~\ref{ex:curl-upload} shows two shell scripts, the first
+suitable for uploading a stand-alone gfn package and the second for
+uploading a zip package. The first three lines of each would, of
+course, have to be filled out appropriately for your case.
+
+\begin{script}[htbp]
+  \centering
+  \caption{Shell scripts for uploading packages}
+  \label{ex:curl-upload}
+\begin{scode}
+# (1) simple gfn file variant
+user=your_gretl_login
+password=your_gretl_password
+pkg=/path/to/your_package.gfn
+
+savename=`basename $pkg`
+curl -F login="${user}" -F pass="${password}" \
+-F "pkg=@${pkg};filename=${savename};type=text/plain;charset=utf-8" \
+http://ricardo.ecn.wfu.edu/gretl/cgi-bin/gretldata.cgi
+
+
+# (2) zip file variant
+user=your_gretl_login
+password=your_gretl_password
+pkg=/path/to/your_package.zip
+
+bytes=`stat $pkg --printf="%s"`
+savename=`basename $pkg`
+echo "Uploading $pkg ($bytes bytes) as $savename ..."
+
+curl -F login="${user}" -F pass="${password}" -F datasize="${bytes}" \
+-F "pkg=@${pkg};filename=${savename};type=application/x-zip-compressed" \
+http://ricardo.ecn.wfu.edu/gretl/cgi-bin/gretldata.cgi
+\end{scode}
+\end{script}
+%$
+
+
+
 \subsection{Using a Makefile}
 
 If you're working on a platform that supports the \app{make} utility,
@@ -874,6 +969,21 @@
 makefile, but especially if your project is large, it can definitely
 make your life easier.
 
+The \app{make} utility is a program that gives you a consistent
+interface for performing complex tasks. Its usefulness is particularly
+evident when there is some dependency structure between the tasks you
+want to perform. For example, when building a large software project,
+there is a series of operations that must be performed in a certain
+order (compiling, linking, installing); or, as another example, when
+you have a large \LaTeX{} document you have to compile it first, then
+run \BibTeX{}, then compile it again, etcetera.  The \app{make}
+utility is excellent at automating such tasks.
+
+The \app{make} utility needs a file, normally called
+\texttt{Makefile}, which is basically a sequence of rules which tell
+\app{make} ``what to do when''.\footnote{A complete tutorial on
+  \app{make} can be found at \url{http://www.gnu.org/software/make/manual/make.html}.}
+
 Example~\ref{ex:make1} shows a very simple instance, though it does
 illustrate a small refinement.
 
@@ -886,27 +996,44 @@
 $(PKG).gfn: $(PKG).inp $(PKG).spec $(PKG)_help.txt $(PKG)_sample.inp
 	gretlcli --makepkg $(PKG).inp
 
-install: $(PKG)_install.inp $(PKG).gfn
-        gretlcli --batch $<
+install: $(PKG).gfn
+	echo "install $(PKG).gfn --local" | gretlcli -q > /dev/null
 
+zip: $(PKG).gfn
+	echo "makepkg $(PKG).zip" | gretlcli -q > /dev/null
 clean: 
 	rm -f $(PKG).gfn
 \end{code}
+
+% USED TO BE:
+% install: $(PKG)_install.inp $(PKG).gfn
+%         gretlcli --batch $<
 \end{script}
 %$
 
+Warning: if you just copy and paste the example above into a text
+file, chances are it will not work. The \app{make} program can be
+quite fussy about the structure of the Makefile, particularly about
+the use of tabs vs spaces. Consult the \app{make} documentation for
+more details.
+
 Running ``\texttt{make}'' in your project directory will rebuild
 \texttt{mypkg.gfn} if and only any of the source files have changed
 since the \textsf{gfn} was last produced; running ``\texttt{make
   clean}'' will delete the \textsf{gfn}. Here's the refinement:
 running ``\texttt{make install}'' will install the package (after
-rebuilding it, if required), provided the additional file
-\texttt{mypkg\_install.inp} is present. Its content should just be a
-one-liner:
-%
-\begin{code}
-install mypkg.gfn --local
-\end{code}
+rebuilding it, if required).% , provided the additional file
+% \texttt{mypkg\_install.inp} is present. Its content should just be a
+% one-liner:
+% %
+% \begin{code}
+% install mypkg.gfn --local
+% \end{code}
+
+If you run \verb|make zip|, instead, the Makefile will first check
+that the \textsf{gfn} file exists; if it does, it will invoke
+\app{gretlcli} in such a way that the zip file will be generated with
+all the necessary extra files.
 
 [FIXME go over a proper example]
 
@@ -1624,96 +1751,31 @@
 
 If you don't already have a login to the gretl package server, you
 need to begin by creating one (please note, this is not the same thing
-as a sourceforge login). The URL will be given to you by gretl if you
-go to upload a package via the GUI, but for reference it's
-\url{http://gretl.ecn.wfu.edu/cgi-bin/apply/}.
-
-With a login in hand, you can upload a package via the GUI package
-editor: under the \textsf{Save...} menu you'll find an \textsf{Upload
-  to server} option. Alternatively you can use the \app{curl} program:
-this is standard kit on platforms other than MS Windows, but also
-available for Windows via
-\url{http://curl.haxx.se/download.html}. Below is an example shell
-script for uploading a plain \textsf{gfn} file. Of course you'd have
-to fill out the first three lines appropriately.
-
-\begin{code}
-user=your_gretl_login
-password=your_gretl_password
-pkg=/path/to/your_package.gfn
-
-savename=`basename $pkg`
-curl -F login="${user}" -F pass="${password}" \
--F "pkg=@${pkg};filename=${savename};type=text/plain;charset=utf-8" \
-http://ricardo.ecn.wfu.edu/gretl/cgi-bin/gretldata.cgi
-\end{code}
-%$
-
-Uploading a zip package via the GUI is no different from uploading a
-plain \textsf{gfn}: gretl handles the details, producing a zipfile in
-the background. But if you're using the command line the process is a
-bit different. You need to create the zipfile first, then use a
-modified version of the \textsf{curl} upload script shown above.
-
-One way of building the zipfile is to use the \cmd{makepkg}
-command in the gretl console or in \app{gretlcli}, as in
-%
-\begin{code}
-makepkg mypkg.zip
-\end{code}
-%
-When the argument to \cmd{makepkg} is a filename with the \textsf{zip}
-extension, gretl will do one of two things:
-\begin{itemize}
-\item If a matching \textsf{gfn} file is found, this will be used the
-  as the basis for the zipfile, with other components pulled in as
-  needed.
-\item Failing that, if a matching \textsf{spec} file is found (plus
-  the other files that it references), gretl will first build the
-  \textsf{gfn}, then build the zipfile wrapper.
-\end{itemize}
-
-Alternatively you can use the command-line \app{zip} program to do the
-job by hand, as in
-%
-\begin{code}
-zip -r mypkg.zip mypkg
-\end{code}
-%
-where we assume that \texttt{mypkg} is a subdirectory of the current
-working directory containing everything that's needed for the package,
-laid out as described in chapter~\ref{chap:zipfile}. 
-
-For the modified \app{curl} invocation that is needed to upload a
-zipfile, see Example~\ref{ex:curl-zip}.
-
-\begin{script}[htbp]
-  \centering
-  \caption{Shell script for uploading zipfile}
-  \label{ex:curl-zip}
-\begin{scode}
-user=your_gretl_login
-password=your_gretl_password
-pkg=/path/to/your_package.zip
-
-bytes=`stat $pkg --printf="%s"`
-savename=`basename $pkg`
-echo "Uploading $pkg ($bytes bytes) as $savename ..."
+as a sourceforge login).\footnote{The URL will be given to you by
+  gretl if you go to upload a package via the GUI, but for reference
+  it's \url{http://gretl.ecn.wfu.edu/cgi-bin/apply/}.}
+
+With a login in hand, there are two ways of uploading a package using
+gretl. There's also a way of doing this indendently of gretl, via
+the shell, though this may not be convenient on MS Windows.
+
+\textit{First gretl method}: open your package's \textsf{gfn} file in
+the GUI package editor (you can get there via the package browser, or
+via the main-window menu item ``Tools, Function pachages, Edit
+package'').  On clicking the \textsf{Save...} button you'll find an
+item titled \textsf{Upload to server}. This will ask for your login
+information then perform the upload. If your package specification is
+such that a zip package is needed, gretl will take care of building an
+up-to-date zip file and uploading that.
 
-curl -F login="${user}" -F pass="${password}" -F datasize="${bytes}" \
--F "pkg=@${pkg};filename=${savename};type=application/x-zip-compressed" \
-http://ricardo.ecn.wfu.edu/gretl/cgi-bin/gretldata.cgi
-\end{scode}
-\end{script}
-%$
-
-Even if you build your package via the command line, gretl can help
-with the uploading, if you prefer: in the main window, go to ``Tools,
+\textit{Second gretl method}: In the main gretl window, go to ``Tools,
 Function packages, Upload package'' and choose the package to
 upload. The file selection dialog will offer a choice of looking for
-\textsf{gfn} or \textsf{zip} files. Please note: if your package is
-supposed to contain PDF documentation or additional files, you must
-build the zip file and upload that, not the plain \textsf{gfn}.
+\textsf{gfn} or \textsf{zip} files. Please note: in this case, as
+opposed to the first, if your package is supposed to contain PDF
+documentation or additional files, you must build the zip file
+yourself and select that for upload, not the plain \textsf{gfn} file.
+[FIXME: automate this?]
 
 \subsection{Staging}
 
@@ -1748,19 +1810,40 @@
 \section*{Appendix A - The CLI for Windows users}
 \addcontentsline{toc}{section}{Appendix A - The CLI for Windows users}
 
+If you would like to use the CLI approach on a Windows computer, you
+must make a preliminary choice: you can either
 \begin{itemize}
-\item Choice of shell: native (CMD.EXE) or some bash flavor. Pros of
-  native: no need to install anything but commands may be a bit different
-  (mkdir $\to$ md).
-\item With older gretl versions, you may have to fiddle with the PATH
-  environment variable (advice: upgrade)
-\item CygWin may be a nice idea: you get bash plus all sorts of extra
-  goodies, including \cmd{make}.
+\item Stick to the Windows way of doing things, or
+\item install a few programs which mimic a Unix enviromnent.
 \end{itemize}
-
-Using \cmd{gretlcli} under bash is a very nice way of exploiting
-certain gretl features (output redirection, environment variables etc)
-and may be quite useful in it own right.
+In the first case, you will be probably using CMD.EXE as your shell,
+and we assume you are able to translate the Unix shell commands we
+used in section \ref{sec:cli-build} to their Windows equivalent (eg
+\cmd{cp} becomes \cmd{copy}, \cmd{ls} becomes \cmd{dir} and so on).
+
+Alternatively, there are several tools which give you a working
+Unix-like enviroment under Windows, among which:
+\begin{description}
+\item[CygWin] (\url{https://www.cygwin.com/}): this is a massive
+  project, whose aim is providing a complete Unix-like environment for
+  Windows. It contains everything you need for building gretl packages
+  via the CLI and much, much more. Very up-to-date, actively developed
+  and updated.
+\item[MSYS] (\url{http://www.mingw.org/wiki/MSYS}): this is a minimal
+  but consistent set of tools that will get the job done. The only
+  tool that we mentioned in section \ref{sec:cli-build}, which is not
+  provided by MSYS is \app{curl}, that you can install separately.
+\end{description}
+
+In all cases, you will want to have \cmd{gretlcli} on your
+\texttt{PATH}: this may require some fiddling. However, recent
+versions of the gretl installer will sort things out for you
+automatically, so if you have trouble with this our advice is to
+upgrade gretl to a newer version, which is probably a good idea anyway.
+
+Finally: using \cmd{gretlcli} under bash is a very nice way of
+exploiting certain gretl features (output redirection, environment
+variables etc) and may be quite useful in it own right.
 
 \chapter{Package specification details}
 \label{chap:specfile}
