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
