[tex-live] documentation

Reinhard Kotucha reinhard.kotucha at web.de
Mon Nov 7 23:01:15 CET 2005


>>>>> "Heiko" == Heiko Oberdiek <oberdiek at uni-freiburg.de> writes:

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

Hi Heiko,
sorry for the late response and thanks for your suggestions.

If we talk about a scheme for a doc tree, let's forget how texdoc and
texdoctk work today.  I think that they can easily be adapted.

You mentioned different languages.  We have indeed documentation in a
lot of languages already, so it would be nice to have a standardized
scheme to find a document describing a particular package in a
particular language.  For instance, if we have

TDS:doc/en/...
TDS:doc/de/...
TDS:doc/fr/...

programs can evaluate the locale settings ($LC_ALL or $LC_LANG) first
and if they do not find something appropriate, default to English.
If English documentation doesn't exist, search for whatever fits best
(documentation for german.sty exists only in German, AFAIK).

Your proposal <package_dir>/<any_file> is also reasonable, especially
if there is texdoc-index.{html,pdf} file (or simply index.{html,pdf}).

Another point is that there are sometimes two versions of a file, one
for screen preview and one for printing.  Hans Hagen has files
<file>-s.pdf and <file>-p.pdf.  I don't think that we want to have
separate directories for these files, but I think that there should be
some conventions.  I provided lshort-vi.pdf and lshort-print-vi.pdf
but I'm not very happy with it because it doesn't comply with any
standard.  I think that Hans made the first step.  Note that texdoctk
has a [view] and a [print] button already, and it would be nice to
view the file in color and print it in b/w.

IMO we need some guidelines describing how to arrange documentation.  

When I provided lshort-vi and amsldoc-vi I really missed such
guidelines.

Regards,
  Reinhard

-- 
----------------------------------------------------------------------------
Reinhard Kotucha			              Phone: +49-511-4592165
Marschnerstr. 25
D-30167 Hannover	                      mailto:reinhard.kotucha at web.de
----------------------------------------------------------------------------
Microsoft isn't the answer. Microsoft is the question, and the answer is NO.
----------------------------------------------------------------------------




More information about the tex-live mailing list