Documentation

Most packages come with some form of documentation. To make it easier for users to find this documentation, the TDS specifies that documentation shall be stored in a structure that parallels to some extent the fonts and macros directories.

There was much discussion about where documentation files should reside. One option was to place them in the same directory as the source files for the packages, but we felt it was important that users be able to find documentation in one place, not mixed in with the source files; most users have no interest in sources. Therefore, the TWG felt that a separate, but parallel, structure for documentation would (1) keep the documentation together and (2) make it as straightforward as possible for users to find the particular documentation they were after.

The TDS specifies that documentation files shall be organized as follows:

texmf/doc/category/...

category

identifies the general topic of documentation that resides below it:

In the case of TeX formats, this will be the name of the format: latex, plain, amstex, etc. Within the category tree, the directory base is reserved for base documentation distributed by the format's authors.

Other categories include utility names, for example: bibtex, makeindx.

The following categories are reserved:

help

is reserved for meta-information, such as FAQ's, David Jones' macro index, etc.

general

is reserved for stand-alone documents not part of any package: Michael Doob's A Gentle Introduction to TeX, Joachim Schrod's Components of TeX, etc.

man

is reserved for manual pages (Unix-style documentation).

info

is reserved for processed Texinfo documents.

html

is reserved for HTML documents.

The documentation directories may contain TeX sources, DVI files, PostScript files, text files, or whatever form of documentation will best explain the package.

A skeleton of the TDS directory tree under texmf/doc:

  help/           meta-information
  . ctan/         info about CTAN sites, TeX-index, etc.
  . faq/          FAQs of comp.text.tex, etc.
  general/	  across programs, generalities
  . texcomp/      Components of TeX
  . errata/       errata, errata[1-8]
  <format>/       name of a format (latex example follows)
  . base/         for the base format
  . misc/         for single-file package documentation
  . <package>/    for package (amslatex, etc.)
  latex/
  . base/         ltnews*, *guide, etc.
  . graphics/     grfguide
  generic/	  for non-format specific TeX packages
  . german/       germdoc
  . babel/      
  <program>/      TeX applications, by name (examples follow)
  tex/            texbook.tex, gentle, etc.
  metafont/       mfbook.tex, metafont-for-beginners, etc.
  metapost/       mpman, manfig, etc.
  ams/
  . amsfonts/     amsfonts.faq, amfndoc
  . amstex/       amsguide, joyerr
  . amslatex/     amslatex.faq, amsldoc
  web/            webman, cwebman
  fontname/       Filenames for TeX fonts
  fonts/
  . oldgerm/      corkpapr
  . malvern/
  man/            Unix-style manual pages
  html/           HTML files
  info/           GNU Info files, made from Texinfo sources