[tex-live] documentation

[Heiko Oberdiek]

On Thu, Oct 27, 2005 at 03:00:15PM -0300, George White wrote:

> Quoting Heiko Oberdiek <oberdiek at uni-freiburg.de>:
> 
> > On Thu, Oct 27, 2005 at 07:00:54AM -0300, George White wrote:
> > 
> > > Quoting Reinhard Kotucha <reinhard.kotucha at web.de>:
> > > 
> > > > >>>>> "Karl" == Karl Berry <karl at freefriends.org> writes:
> > > > 
> > > >   > Well, if you can make a patch for the texdoc .dat file, I can
> > > >   > install it :).
> > > > 
> > > > I fear that, unlike texdoctk, texdoc simply uses ls-R as a database.  
> > > > 
> > > > Thomas recently mentioned that one can define aliases, but I think
> > > > that it is best if the authors provide fixes.
> > > 
> > > It may be best, but is it practical?  Will aliases help when you have
> > > dozens of manual.pdf files?  
> > > 
> > > I suspect it is much easier to make changes in texdoc to support 
> > > "package/manual".  On systems that support symlinks one could process
> > > the doc tree to make package/manual.pdf -> package/package.pdf.
> > 
> > And how you want to solve the problem of several documentation
> > files? One symlink can point to just *one* file.
> 
> Hopefully the others will at least be be mentioned in manual.pdf,

Perhaps somewhere, in many cases not:
* Different language versions:
  manual-en.pdf, manual-de.pdf, ...
  The normal expectation is then, that the users that open
  manual-en.pdf see the English version, readers of manual-de.pdf
  the German version, ... It would be a surprise, if theses manual
  versions start with a list of links to the different language
  versions. And which language should be choosen for this part?
* Separate source code documentation and user manual,
  articles, slides, ...

> but 
> this emphasizes the point that, for many packages, the directory in the
> doc tree is the real connection to the package and may contain multiple files
> with generic names like manual.pdf that may indicated the type of content but
> tell you nothing about the package.

But you still have the directory!

The current texdoc behaviour is not appropriate for
documentation that consist of several files:
  TDS:doc/.../package/package.pdf % for manual
  TDS:doc/.../package/package.pdf % for source code doc
  -> you are running out of names
  -> it is not clear, what the type of content is
  -> redundant naming, you could strip the directory "package" level

A more naturally naming convention is:
  TDS:doc/.../package/manual.pdf
  TDS:doc/.../package/source.pdf

Possible ways to solve the texdoc problem:
* The package author offers a document for texdoc with standardized
  name (e.g. texdoc-index.[pdf,html,...] that
  contains explanations and links to the package's documentation.

    TDS:doc/.../packageA/texdoc-index.pdf
    TDS:doc/.../packageA/manual.pdf
    TDS:doc/.../packageA/source.pdf
    TDS:doc/.../packageB/texdoc-index.html
    TDS:doc/.../packageB/manual.html
    TDS:doc/.../packageB/README

  Then texdoc also looks for this document (texdoc-index.*).

* Or a separate data base is maintained with package overviews.
  (e.g. source in XML. PDF and HTML are automatically generated.)

     source/packageA.xml
     source/packageB.xml
     pdf/packageA.pdf
     pdf/pacakgeB.pdf
     html/packageA.html
     html/packageB.html

     Then texdoc also looks for this database.

* Or texdoc shows the directory and let the user decide, which file\
  he wants.

* ...

Yours sincerely
  Heiko <oberdiek at uni-freiburg.de>