3:33 a.m.
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
7:19 a.m.
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
3:29 p.m.
> 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).
I think here the people who uses Gretl in windows does not use much the chm
manual. We have also some linux users all of them using kde instead of gnome.
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.
I agree with Jack on this. Really if I remember the way I learnt about Gretl,
when I knew her, firstly I took a look at the menus and then I printed the pdf
manual. Since this time, I almost exclusively use the help at the GUI "help"
item.
Before I knew Gretl (and R) I used to work in RATS. The RATS manuals (version
5) are also set up in two volumes, firstly the "User's guide" including a
detailed information of the main commands and procedures with the necessary
formulas, and then the "Reference manual", listing in alphabetical order all
the commands with their parameters, etc. May be that
As a translator of Gretl, I thought I should translate the help files
(accesible through the "help" menu item) and the manual, so I did it.
The first time I translated the "help" files, they were almost completely
ASCII text, so this was easy to do. The manual was in XML,
I must say that I didn't know anything about XML, but I could translate de
manual without much problem (with the help of Allin, of course). Now the XML
code generates the help files and the manual, so it is much more complicated.
I don't know whether the translator's life will be better if we have the two
manuals separated, as I suposse we will want to maintain the possibility of
printing a (well formatted) command reference also, so we need the XML
format. But I think it will be easier for us to have a "User's guide" in
Latex, so we can treat separately at least this part of the documentation, and
probaly we have this part more updated.
--
Ignacio Díaz-Emparanza
Dpto. de Economía Aplicada III (Econometría y Estadística)
UPV-EHU
http://www.bl.ehu.es/~etpdihei/
9:04 a.m.
On Thu, Nov 03, 2005 at 10:33:58PM -0500, Allin Cottrell wrote:
Hello all,
...
I'm wondering, how many people use format 3 (Windows or gnome help)?
I guess, er... Windows users and Gnome users :-)
Seriously, it's difficult to estimate the numbers, Sourceforge downloads page
shows that downloads of the windows versions are roughly double the other
versions', but we should take into account pre-packaged versions not distributed
through sourceforge... (quite an interesting econometric issue, estimating the
number of users of free software, I wonder if someone on the list ever thought
about that)... and in any case, the number of downloads doesn't say much about
the use of different sources of documentation...
Putting feet back on the ground, I agree with Jack's remarks, but we should take
into account the risk of duplicating work, maintaining two different source
formats for documentation (es. latex and xml).
Allin, what particular aspect of the current documentation system leaves you
unsatisfied? I'd be glad to help you explore improvements and/or alternatives.
Cri
--
GPG/PGP Key-Id 0x943A5F0E - http://www.linux.it/~cri/cri.asc
Free software, free society - http://www.fsfeurope.org
10:44 a.m.
On Fri, 4 Nov 2005, Cristian Rigamonti wrote:
Putting feet back on the ground, I agree with Jack's remarks, but
we should take
into account the risk of duplicating work, maintaining two different source
formats for documentation (es. latex and xml).
Sorry Cri, I don't understand what you mean here, or possibly I wasn't
quite clear. My idea was that there should be very little overlap between
the two documents. Technical documentation should be written in xml, since
it will be typically accessed through some kind of help system: the
majority of our users run gretl under Windows, I suppose (at least, all my
students do), so ease of export to chm is top priority. Chapter 14 of the
current manual is a perfect example. It's nice to be able to read a
printout, but I guess its contents are read 99% of the times on screen.
The more textbook-like document I have in mind can't be written in anything
but LaTeX. An example of what I'd like to see here is what currently is
chapter 12 (the 2 pages on the Johansen test). This doesn't need to be
part of the help system. (Although, I should add, many people find Eviews'
help system quite useful. Basically, the Eviews manual is a hardcopy of
the help files. These contain formulas, references and everything you
expect to find in an econometrics textbook.) And translation from LaTeX to
html is very solid technology anyway, in case you need that.
Moreover, the split would help translations, IMO. Actually, I'd assign
higher priority to translation of the GUI elements and the technical
documentation. If "part 2" doesn't get translated, well, I can live with
that. If other people find it difficult to replicate the splendid job
you're doing with Italian because of time constraints, they can settle for
the essentials.
Riccardo `Jack' Lucchetti
Dipartimento di Economia
Università Politecnica delle Marche
jack(a)dea.unian.it
http://www.econ.univpm.it/lucchetti
11:27 a.m.
On Fri, Nov 04, 2005 at 11:44:11AM +0100, jack wrote:
My idea was that there should be very little overlap between the two
documents.
That's what I meant: the "one code base" approach is useful if there is
substantial overlap between parts (such as the current command reference and
online help files), otherwise, splitting is fine.
It's just a matter of deciding the best format (Docbook/XML for "part 1"
and
LaTeX for "part 2" seem reasonable to me) and plan the transition (there are
some solutions for docbook/XML to LaTeX conversion...)
Cri
--
GPG/PGP Key-Id 0x943A5F0E - http://www.linux.it/~cri/cri.asc
Free software, free society - http://www.fsfeurope.org
2:25 p.m.
On Fri, 4 Nov 2005, Cristian Rigamonti wrote:
On Thu, Nov 03, 2005 at 10:33:58PM -0500, Allin Cottrell wrote:
>
> I'm wondering, how many people use format 3 (Windows or gnome help)?
I guess, er... Windows users and Gnome users :-)
Seriously, it's difficult to estimate the numbers, Sourceforge
downloads page shows that downloads of the windows versions are
roughly double the other versions...
Yup, I'm aware that most people who use gretl do so on Windows.
What I'm not sure of is how much use they make of the chm help file,
given that they also have the options of plain text for online help
and PDF fr a browseable manual. (I'm afraid the chm file is
currently not as useful as it might be since I haven't figured out
how to enable full-text search yet, but that's another story.)
Putting feet back on the ground, I agree with Jack's remarks, but
we should take into account the risk of duplicating work,
maintaining two different source formats for documentation (es.
latex and xml).
I think that point is taken. For material that has to be made
available in multiple final formats, XML remains the best solution.
Allin, what particular aspect of the current documentation system
leaves you unsatisfied? I'd be glad to help you explore
improvements and/or alternatives.
My concern is primarily with math-intensive sections of the manual.
The current setup of XML with embedded TeX math "works", but it is
ugly, kludgy and cumbersome to edit. You have done a very brave job
with the Italian translation, Cri, but one consideration is that
most people contemplating translation of the manual would likely be
scared off by the ghastly XML source.
Since the math-intensive material is not going into the plain text
help files anyway, the question arises whether we'd be better off
storing that material as TeX source. This would surely be the case
if we used the source only to produce PDF, but it's less clear-cut
if we're also producing HTML for Windows. As Jack says, there are
decent conversion paths from TeX to HTML, but it is very convenient
to be able to use Docbook XSLT to make HTML in the required format
for chm (as we currently do).
Allin.
7:50 p.m.
On Fri, Nov 04, 2005 at 09:25:38AM -0500, Allin Cottrell wrote:
Since the math-intensive material is not going into the plain text
help files anyway, the question arises whether we'd be better off
storing that material as TeX source. This would surely be the case
if we used the source only to produce PDF, but it's less clear-cut
if we're also producing HTML for Windows. As Jack says, there are
decent conversion paths from TeX to HTML, but it is very convenient
to be able to use Docbook XSLT to make HTML in the required format
for chm (as we currently do).
Ok, I've got the point.
Some issues we should consider:
- 1. DocBook to LaTeX conversion: there are some tools (via Perl or via XSLT),
maybe they're sub-optimal, but that's a one-shot issue we can work out.
- 2. chm files generation: if that's problematic we can drop that format and point
users to pdf, html, txt-help documentation
- 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)
It seems to me that 1. and 2. are not much problematic, while 3. can be a tough
job...
(BTW I think translation issues are not that relevant for the choice, I don't
see much difference between translating XML or LaTeX sources: in both cases, just
stay away from the tags/commands :-)
Cri
--
GPG/PGP Key-Id 0x943A5F0E - http://www.linux.it/~cri/cri.asc
Free software, free society - http://www.fsfeurope.org
8 p.m.
On Fri, 4 Nov 2005, Cristian Rigamonti wrote:
Some issues we should consider:
- 1. DocBook to LaTeX conversion: there are some tools (via Perl or via XSLT),
maybe they're sub-optimal, but that's a one-shot issue we can
work out.
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?
Allin.
9:11 a.m.
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
4:45 p.m.
> 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.
I like the idea, and I agree completely with Jack's thoughts.
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? :-)).
!! Well, I may try it, but give me some time ...
--
Ignacio Díaz-Emparanza
Dpto. de Economía Aplicada III (Econometría y Estadística)
UPV-EHU
http://www.bl.ehu.es/~etpdihei/
4:11 a.m.
New subject: Splitting the manual
In gretl CVS, I've now split the manual into two chunks. One, which
I'm calling the Gretl Command Reference, includes the Command
Reference chapter and also the "Options and arguments" chapter.
The remaining chapters of the full manual have gone into what I'm
calling the Gretl Users' Guide.
I'm now working on an xsl stylesheet to convert the XML files
containing the Users' Guide chapters into reasonably clean,
human-editable tex. This is progressing quite well, though I still
have to tackle tables. For the present, we can compile both parts
as PDF using the XML sources and jadetex, albeit with some breakage
of cross-references.
Cri, I hope you don't mind my making some small changes to some of
the Italian XML files. This was just because, with the split, some
of the old cross-references are no longer valid, and I wanted to
test the compilation of both the Italian and the English versions.
I agree with Jack's observations on the manual, and would be very
glad to receive contributions/patches for the Users' Guide.
Allin Cottrell
3:46 p.m.
New subject: Splitting the manual
On Mon, Nov 07, 2005 at 11:11:54PM -0500, Allin Cottrell wrote:
I'm now working on an xsl stylesheet to convert the XML files
containing the Users' Guide chapters into reasonably clean,
human-editable tex. This is progressing quite well, though I still
have to tackle tables. For the present, we can compile both parts
as PDF using the XML sources and jadetex, albeit with some breakage
of cross-references.
Be sure to check out the existing (semi)automated tools for
DocBook XML -> LaTeX conversion (I don't have the names handy, but you can
easily find them on google).
Cri, I hope you don't mind my making some small changes to some
of
the Italian XML files.
No problem, let me know if I can be of any help.
Cri
--
GPG/PGP Key-Id 0x943A5F0E - http://www.linux.it/~cri/cri.asc
6738
days inactive
6742
days old
12 comments
4 participants
participants (4)
-
Allin Cottrell -
Cristian Rigamonti -
Ignacio Díaz-Emparanza -
jack