> < ^ Date: Wed, 06 Jul 1994 17:24:00 +0100 (MET)
> < ^ From: Martin Schoenert <martin.schoenert@math.rwth-aachen.de >
< ^ Subject: Re: Adding Online Documentation (2)
Allan Adler writes in his e-mail message of 1994/07/04

I have applied the suggestions of Martin Sch"onert for adding online
documentation. They work. ON the other hand, there are a few drawbacks:
(1) One has to recompile the entire manual, which is time consuming.

You can use the line '\includeonly{<chapter>,...}' at the top of
'manual.tex' to tell LaTeX which chapters to process. For the other
chapters only the '.aux' files are read. This is quite a bit faster.
The line numbers in the table of contents and the index wont be correct,
but that doesn't bother the online help at all.

Allan Adler continues

(2) One has to use Latex, whereas I would prefer to use Plain TeX

This is very easy to fix. Write a Plain TeX to LaTeX converter. This
will even be usefull for other tasks, not only for the GAP online help.
But seriously. In the manual (at least in those parts that can be read
in the online help), we use so few formatting commands (even lists are
forbidden), that it doesn't make a big difference whether we use LaTeX
or Plain TeX.

Allan Adler continues

(3) The formatting of the manual is itself unfamiliar. For example,
one has sections and chapters, but it is not clear how to create
subsections, subsubsections, etc. With more understanding of the
formatting, one could make one's own modifications to the code.
WIthout it, there are just chapters and sections.

What is unfamiliar about chapters and sections? There is no *technical*
reason to allow only chapters and sections, and no subsections or
subsubsections. However, I think that two levels are enough in online
documentation. I often get lost in TeXinfo documentation (e.g., the on
for Emacs), because I don't know how far away from the top I am, whether
I want to go to the next node or up and then to the next, etc.

Allan Adler continues

(4) One really should not hack the manual.

Well, if you want GAP to automatically find your documentation you have
to change some file. As it happens this file is 'manual.tex'. And I
really don't see that adding a few lines to this file can be called

Allan Adler continues

It seems that there are various ways to solve these problems. One would
be to make additional options available to the online help command
such as to look in other places for TeX files, to accept Plain TeX,

Yes, there are lots of nice things one could add to the online help.
I'll do them all in our copious free time ;-)


-- .- .-. - .. -.  .-.. --- ...- . ...  .- -. -. .. -.- .-
Martin Sch"onert,   Martin.Schoenert@Math.RWTH-Aachen.DE,   +49 241 804551
Lehrstuhl D f"ur Mathematik, Templergraben 64, RWTH, 52056 Aachen, Germany

> < [top]