[NTG-pdftex] Re: [tex-live] documentation
oberdiek at uni-freiburg.de
Fri Oct 28 00:58:09 CEST 2005
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, ...
> 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:
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.
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.)
Then texdoc also looks for this database.
* Or texdoc shows the directory and let the user decide, which file\
Heiko <oberdiek at uni-freiburg.de>
More information about the ntg-pdftex