On Thu, 3 Nov 2005, Allin Cottrell wrote:
Hello all,
I'm thinking once again about something that occupies me from time
to time, namely the best source format in which to store the gretl
manual.
At present, gretl help is available in three formats:
1) Plain text (called up by the context help buttons in gretl
dialogs, for example).
2) PDF: the whole gretl manual is available as a PDF file.
3) Platform-specific help files. The gretl manual is also available
as a Windows "chm" (Compiled Html) file, and as HTML or XML for
viewing on the gnome desktop.
I'm wondering, how many people use format 3 (Windows or gnome help)?
If the answer turns out to be, hardly any, that might make a
difference to my thinking on the best base format for the manual
(currently XML).
Thanks for any observations on this.
Allin Cottrell
This brings back a thought Allin and I shared in a private message a few
weeks ago. My personal opinion is that, certainly in the long run but
perhaps even now, it's best to split the documentation in two, roughly
corresponding to a "reference manual" and a "user manual", like eg TSP
has
always had.
Documentation can be used in very diverse ways: maybe you're sitting in
front of the screen and you can't remember what the syntax for "coint2"
is. In that case, you don't want all the theory on the Johansen test, you
just want something like a man page. Note: (1) you don't need to be shown
an inordinate amount of math; (2) few people can write this kind of doc
(hardly anyone apart from Allin), because in most cases the writer needs
to know exactly what's going on under gretl's hood. This needs to be part
of the online help.
Or maybe, on the contrary, you spot this command, say "bkfilt", that does
something you don't know anything about: then, you want a nicely formatted
text, possibly with lots of maths in, references and so on. Put otherwise,
you want something that resembles academic communication. This would be
nice to have as part of the help system, but not mandatory IMO. A properly
formatted pdf document (possibly with hyperlinks) is what you want. You
can print it if you want and read it like a book, or you can browse
through it on your screen. This kind of doc can be written by a much
larger pool of people: you don't need to be familiar with gretl's source
code. You just need to know what gretl can do and what can't do, plus some
decent knowledge about statistics/econometrics.
For these reasons, my proposal is: xml for the first kind, LaTeX for the
second kind.
Riccardo `Jack' Lucchetti
Dipartimento di Economia
Università Politecnica delle Marche
jack(a)dea.unian.it
http://www.econ.univpm.it/lucchetti