A concern regarding texmf/doc/{html,info}

[Ulrik Vieth]

Matthew Swift:

> Hello folks.  The TDS draft shows that great care went into it, 
[...]

> Now, I'm guessing there is a temptation to treat the html and info
> formats specially because it makes things easier for the programs
> which read those formats.  But does it?

I think it was me who proposed the html/ directory back in March this
year.  What I had in mind was that you can convert Texinfo sources
into HTML just as well as into Info or DVI format.  The only difference 
is that for a medium-sized manual the same source typically results 
in one and only one DVI file, one or a few Info files, or a whole lot
of HTML files (when using -split_node), making it necessary to employ
a separate subdirectory for every manual to avoid getting lost among
hundreds of files.

This was the idea when I proposed a separate top-level html/ directory
for those manuals by anlogy with info/, which used to be a top-level
directory at that time.  As a result of the following discussion which
I can't remember in detail, it was decided to move the info/ and html/
directories below texmf/doc/.  Personally, I didn't really like this 
decision, but I accepted it.

In the most recent draft this decision was relaxed somewhat so that
implementors may choose to install the contents of the texmf/doc/info/
directory outside the texmf/ tree, e.g. in the usual /usr/local/info.
Unfortunately, since WWW is so new, there don't seem to be established
standards for a corresponding organization of HTML files yet.

At my site, we have administrative accounts "tex" and "gnu", which 
are organized very much alike.  Info files go into /opt/{tex,gnu}/info 
and formatted manuals in DVI or PS format into /opt/{tex,gnu}/doc, 
where /opt/tex/doc is just a symbolic link to /opt/tex/texmf/doc.  
For HTML documentation we have resorted to using the home directories
/home/{tex,gnu}/public_html/info, with links in /opt/{tex,gnu}/html 
for ease of installation.  Another link in /home/tex/public_html/doc 
points to /opt/tex/texmf/doc/ providing access to all kinds of 
documentation no matter what format.  

Keeping an index.html file in the texmf/doc/ directory allows you 
to organize the documentation without any constraints imposed by 
the acutal directory structure.  With relative hyperlinks it doesn't
matter whether HTML files are kept in a separate subtree from the
other files.  A user can find all the find throgh the WWW front-end
and doesn't have to care about where they come from. Another user 
looking at the actual directory tree, won't be irritated by dozens
or hundreds of Info or HTML files he can't read directly.  

Back in March, Phil Taylor argued that he didn't see the conceptual
difference between invoking a DVI or PostScript viewer or a HTML
browser or Info reader on a certain.  However, I think the main
difference is that HTML and Info provide their own navigational 
front ends (using index.html or dir files) whereas for the other 
formats the directory structure _is_ the only navigational aid.
This is why we can lump all HTML or Info files into one directory
whereas we have to care more about a well-organized hierarchical
structure for other files, in order to make it easy to find the 
relevant information.

So much for my personal opinion on organizing HTML documentation.  
Other members of the TDS group might disagree. 

Cheers, 
Ulrik Vieth.

P.S.  In case you're interested, you might want to try this:

  http://www.thphy.uni-duesseldorf.de/~{tex,gnu}/

Unfortunately, the index.html for texmf/doc/ is very rudimentary.  
I once started to write some INDEX.html files to navigate through 
the hole texmf/ tree, not just texmf/doc/, but I didn't get very 
far with that.  Apart from that, what I've written needs updating
and/or rewriting by now, so I might want to start over completely.

P.P.S.  Some other TeX information which is not documentation
for packages in the texmf tree can also be found below:

  http://www.thphy.uni-duesseldorf.de/~vieth/subjects/tex/