On Fri, 4 Nov 2005, Allin Cottrell wrote:
Yes, that's worth looking into.
> - 3. Re-organizing the current content, separating between:
> - "technical/user-guide content" (which we would keep in XML, expunging
all extra
> math)
> - "reference" content (which we would convert to LaTeX)
As I understand Jack's suggestion, the idea would be to split the
material into
1) The stuff that's currently in gretl_commands.xml, which is used
to generate the plain text help files and the command reference
chapter of the existing manual. This is basically one section per
gretl command. This would stay in XML.
2) All the rest of the current manual, plus some new things that are
in the pipeline. This would go into TeX.
Given 1) in XML, one could easily produce a chm version of that
subset of the material. Msybe this should be used in place of plain
text on Windows?
I'd like to expand a little on "what happens after the great doc split"
with an example. Suppose somenone feels like writing some comments on
logit/probit/tobit models, which have been in gretl for a long time now
but have very scant documentation. Something in the style of Chapter 12 or
the upcoming discussion on maximum likelihood estimation.
I could do this, but I'm sure many list members could provide excellent
material. Of course, this would have to be written in LaTeX. To integrate
nicely with the rest of the documentation, though, we need to make
available all the tools that make this easy. I imagine that this
somenone could download the LaTeX sources to the manual (ideally not via
CVS, which may be intimidating for some), as a zip or tar.gz file, add
to its contents and send it back to an "editor" who may approve or reject
the changes.
Of course we would have to provide some "instructions to authors", which
explain which macros are defined in the preamble, some style norms and so
on.
Advantages I see:
1) This way, adding to the gretl manual becomes not very different from
submitting a piece to a journal, which is a tried and tested procedure.
Only, marginal changes (even one-liners) would be perfectly acceptable
too.
2) The pool of contributors will probably grow. As I said in an earlier
message, there's many people around who won't or can't contribute code,
but can contribute documentation (hint to Ignacio: how about a nice ARIMA
tutorial? :-)).
3) Some work can be offloaded from Allin's shoulders. Clearly, Allin is
the natural candidate for the "editor" position, but others could do it
too.
What do you say, guys?
Riccardo `Jack' Lucchetti
Dipartimento di Economia
Università Politecnica delle Marche
jack(a)dea.unian.it
http://www.econ.univpm.it/lucchetti