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

[Matthew Swift]

Ulrik, thanks for your careful reply.

>>>>> "Ulrik" == Ulrik Vieth <vieth@thphy.uni-duesseldorf.de> writes:

      > 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.

Why do they need to be "read" as opposed to downloaded?  In this case,
there's no way to predict what file formats are interesting, so they
should all be provided.

Why do they need to be read "directly"?  A significant and increasing
fraction of all documentation is not plain ASCII text.  Many people
now, and most people in the near future, will be using intelligent
browsers to browse the texmf/doc tree.  When the browser can't handle
the file format, it will launch another browser, based on filename or
magic string in the file.   

The fact that texinfo --> HTML conversion generates a large number of
HTML files is unfortunate, but I don't think the TDS should bend to
it, since there better ways around the problem, I think.  Intelligent
browsers can decide to hide ("filter") or ignore certain files.
Alternatively, would subdirectories be acceptable here, such that the
file "texmf/doc/metafont/metafont-tutorial.html" would be the top node
for files living in the directory
"texmf/doc/metafont/metafont-tutorial".  You've already got this level
of subdir in the TDS, e.g., texmf/doc/latex/base.  The same could be
possibly be done for Info top nodes, assuming the change is
cofigurable in the Info browser.  This would keep the
texmf/doc/<category> top level as terse as possible.

A number of intelligent browsers exist now.  For example, I use GNU
Emacs dired-mode.  Or sometimes Netscape.  The one launches the other
when needed.  For dired, I've hacked `dired-guess-shell-alist-user';
in Netscape, you configure e.g., metamail on Unix; NeXTStep has an
intelligent "open" command and a file manager/browser which recognizes
extensions; Mac browsers distinguish file types with the file's
resource fork; Windows 3.11 lets you associate extensions with apps;
etc.  And there is one browswer, more or less intelligent, available
on all platforms to run the right viewer on a given file -- the user
himself.

       > 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.

I agree with Phil Taylor.  Yes, you CAN lump all HTML and Info files
together, but there seems to be no advantage to doing so, since we
have established that properly maintained "dir" and "index.html" files
permit Info and HTML browsers to use the relevant files wherever they
are.  Given that it doesn't matter to users of those browsers where
the files are, I suggest the files be organized by categories
according to content, for the sakes of all other browsers, which are
thereby enabled to include ALL documentation in their scope.  A tool
that only gives me access to a subset of what's available (e.g., an
Info reader) is not a tool for that critical and difficult first stage
of research that I think the TDS is in a position to facilitate,
namely, the stage of finding out what material is available to help
solve your problem.

    Ulrik> I once started to write some INDEX.html files
    Ulrik> to navigate through the whole texmf/ tree, not just
    Ulrik> texmf/doc/, but I didn't get very far with that.

Your efforts were trying to achieve the same goal for HTML-only
browsing that I am suggesting would be achieved for a wide variety of
browsing schemes by sorting ALL documentation by topic and none by
file format, namely, the goal of having ALL documentation available
via a single user interface.

Writing an HTML guide to the whole tree would be wonderful and useful
not only because it would facilitate browsing of non-documentation,
but also because it can confer MORE context and structure on the
documentation than can the TDS.  But the TDS can and should, I think,
provide as much context and structure as possible on the
documentation, independent of file format, so that the greatest aid is
given to the greatest number of interfaces.

Outside the doc/ tree in texmf/, file format is, for the most part,
integral with describing the file's purpose and content.  Among
documentation files, on the other hand, file format is largely
irrelevant to the user and almost entirely irrelevant on the practical
level of enabling good user interfaces.