I am going to violate one of my principles, namely ``never underestimate
your users'', but I still think that a few explanations are in order to
help those who have never heard of HTML or 'texi2html' before.

A lot of people are currently interested in documents on Networks. Such
documents should be easily available to everyone, it should be easy to
reference one document from within another, and should be possibly
contain pictures, movies, and sound.

The most popular system is the World Wide Web (WWW). It originated at
Cern, and is likely to become the most important consumer of Internet
bandwidth in the near future. The most popular browser (computer program
that allows you to read documents in the WWW, follow their links to other
documents, and display embedded pictures, movies, and sound) for the WWW
is called Mosaic and available for UNIX, MS-DOS, and Macs from NCSA-UIUC.

The most important format for WWW is called HTML, which is short for
Hyper Text Markup Language. Hyper Text refers to the fact that such
documents can contain links to other documents. Markup Language refers
to the format in which such links and other formatting information are
represented in the source of such documents.

Another Markup Language is TeX. However, TeX is not Hyper Text, because
it doesn't allow you to create links to other documents that a program
could automatically follow.

The links in an HTML documents are given in a format that is called
Universal Resource Locator (URL). An example of a URL is in Steve's
e-mail message. 'http://www-theory.cs.st-and.ac.uk/~sal/GAP'. This
means that the document is on the computer 'www-theory.cs.st-and.ac.uk',
it is in Steve's WWW home directory '~sal', is called 'GAP', and can be
retrived using the Hyper Text Transfer Protocol (http).

HTML is just one format for textual information that can be browsed.
Here ``browsed'' basically means that there is no predefined path through
the document. Instead a reader can choose different routes depending on
what information he or she seeks.

Another example is TeXinfo, which is the format used by the GNU project.
In this case the browser is the EMACS editor. Pictures and sound are not
supported in this format, but the basic browsing is fairly convenient.
The TeXinfo format is also interesting for another reason. It is
possible to take a TeXinfo document and run it through TeX to produce a
hardcopy version of the document. For this to work the entire
TeXinfo document is structured in a book like fashion, with chapters,
sections, subsections, subsubsections, etc.

A sidenote. So TeXinfo documents are basically a tree with a few extra
references. General HTML documents can be arbitrary graphs, but it is
recommended that they also have a basically tree like structure. I don't
find this surprising. Would you rather visit a museum with a long
corridor and rooms that branch of from this corridor, or a museum that is
a complex maze where you are never certain whether you visited all rooms?

Another system similar to TeXinfo is the format in which the GAP manual
is written. It contains references in form of (see "<section>"). You
can browse that document using the GAP help functionality. Not very
fancy, but it works (actually I prefer it over EMACS info mode, but that
is cleary a matter of personal taste). One advantage of our format is
that the source can be directly be used by the browser, no further
preprocessing is needed.

As soon as there are several formats with the same purpose, it makes
sense to think about conversions between them. One such converted is
'texi2html' (pronounced TeXinfo too HTML), which converts between the
TeXinfo to HTML. Another is the one Steve Fisk write, betwenn GAP's
manual format and TeXinfo.

This finally takes us back to the basic topic of this discussion. It
would be nice if everybody could read the GAP manual using his or her
favorite browser, be it the GAP help function, the EMACS info mode,
Mosaic, the OS/2 help system, or the Windows help system (and yes, I
agree, Mosaic is much more sexy than the GAP help function).

For this to work the GAP manual must be converted to the format supported
by those browsers. That is, we need a GAP -> HTML converter, a GAP ->
TeXinfo converter, etc.

This is of course where the work begins. We have to think about how the
mapping is supposed to work. E.g., to what is <something> mapped by the
GAP -> TeXinfo translation. It may be even necessary to think about
needed changes to the GAP format, so that the mappings are possible (but
I hope no big change is necessary).

The concrete topic that I asked about is the question how the GAP manual
should be split in the GAP -> HTML translation. In HTML a document is a
single item that you see at once. There can be links between documents
or more generally from one document to a certain (labelled) position in
another document.

There are three possibilities. First the entire manual could be one
document, and there could be one (large) document with a label for each
section. Second there could be one document for each chapter of the
manual and for each section within a document there could be a label.
And third there could be one document for each (of the 1317) sections.

There s a pragmatic argument that speaks against the first approach.
Everyone would have to load the entire manual (all 4 MBytest) into his or
her browser, even if he or she wants only to read a single section.

The problem with the third approach is that one needs a lot of clicks to
go somewhere. It is much easier to read an entire chapter by scrolling
than to jump back and forth using links.

The problem with the second solution is that at least Mosaic's handling
of documents with labels seems unnatural to me.

Anyhow, I would appreciate your comments and suggestions what you would
like to see in a HTML document of the GAP manual.

Martin.

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

PS. In case the first paragraphs got you wondering. Yes I also got a
principle ``never overestimate your users''. This is why I try to make
installation, etc. as foolproof as possible.