[tex-live] documentation

[George White]

Quoting Karl Berry <karl at freefriends.org>:

>     IMO we need some guidelines describing how to arrange documentation.  

Certainly.  This is a necessary first step towards a packaging system that
requires less effort from maintainers and works for users.    Two examples that
merit study are Debian and the R-project.  Something along the lines of the
Debian Policy Manual:

 <URL: http://www.debian.org/doc/devel-manuals#policy> 

could provide a rationale and give details (e.g., TDS) in appendices.   

R-project packages are distributed in binary .zip archives for Win32 and source
.tar.gz for unix/linux.  Documentation source uses a format (Rd) that can be
converted to tex, html, or text. 

So, guidelines for documentation will be more useful if presented in the larger
package management context -- the vision of effective package managment will
encourage authors to follow the guildlines and there will be a rationale that
makes it easier to understand and follow the spirit of the guidelines.  With the
examples of Debian and R I think it is possible to write guidelines that will
work without actually
having all the tools in place.

> There seems to be two areas -- (1) giving recommendations to package
> authors about what to provide, what to name it, and tips on creating it,
> if available, and (2) recommendations to distributors on how to organize
> doc across many packages.

There are some larger issues that cause confusion:

1) For many users, TeX is integrated with their editor.  This creates several
problems:  a)users don't know about command-line tools, there is a disconnect
between the installed version of TeX and the documentation the user actually
reads, and b) the editor is confused with the tex distro ("I need tex on my
linux machine but have to install wine so I can run WinEdt").  Since few
editors provide online TeX manuals, users are left with the printed material
they find in the library and whatever usenet postings google can find.  You
have a people trying to use TL while reading from the original LaTeX book and a
dog-eared copy of  the local
guide from the site where they learned to use TeX.  The guidelines should
suggest that editors which allow the user to run TeX also provide access to the
associated documentation.

2) Users have difficulty describing the tex system they are actually using when
requesting help from package authors/maintainers.  My experience suggests that
the average user is actually using some mixture of 2 or more tex distros,
although the increase in ViSTA (Viruses, Spyware, Trojans & Addware) does mean
that many Win XP systems have a short time between reinstalls.  Many users have
collections of macro packages that they keep either in the directory with their
documents or in a user texmf tree, but they fail to install the accompanying
documentation, so the documention they can read if they know how to find it
doesn't match the packages they are actually using.  
 
3) Differences in package management approaches.  On Win32 and *n*x sites where
sys. admin's responsibilities are limited to security and  backups,  packages
are installed by and for individual users.  Users coming from a Win32
background aren't familiar with the notion of packages that are shared across
many users, and expect to find a simple mechanism to install updates from the
net.

> For the latter, there is a difference between documentation packages
> (like lshort), and documentation of packages (e.g., grfguide).  For
> example, for TL I don't see any purpose in having en/de/etc. levels in
> texmf-dist or texmf, but texmf-doc, perhaps the current full names
> should be changed to the abbreviations.

I prefer a scheme that keeps all the translations together so a user can easily
decide which language to read if their first choice isn't available, so:

  package/user.man-en.pdf --> User Manual for Package
  package/user.man-fr.pdf   --> Manuel d'Utilisation du Package

(If the names are standardized, document viewers can provide translations)

The guidelines also need to recommend using tools that result in searchable 
pdf's so google and other indexing tools can make sense of them.  Package
documents are often used as templates by users, so they should be reviewed to
ensure they are good examples for a user to follow (including publishers' 
instructions to authors).

-- 
George N. White III
Head of St. Margarets Bay, Nova Scotia