[texhax] TeX Live documentation

[Reinhard Kotucha]

Hi Uwe,
first of all, let me clear one thing.  In a previous mail you assumed
that I deliberately misunderstand you.  I can assure you that this is
not true.  Maybe I often misunderstand you, but definitely not
deliberately.

On 2013-03-03 at 22:04:27 +0100, Uwe Lück wrote:

 > Before (on texhax), on "missing" TeX Live Documentation, I focussed
 > on binaries. I did not mention another point, because it is not so
 > clear with the distinction between "using" and "installing" TeX
 > Live, and because I had to recall something. That was last year,
 > integrating a second texmf tree for material outside CTAN.  It was
 > for a server, so it was essentially an administrator's issue.

Adding a new texmf tree is not difficult.  There is an empty texmf.cnf
file in the TeX Live root directory containing a comment:

 % This texmf.cnf file should contain only your personal changes from the
 % original texmf.cnf (for example, as chosen in the installer).
 %
 % That is, if you need to make changes to texmf.cnf, put your custom
 % settings in this file, which is .../texlive/YYYY/texmf.cnf, rather than
 % the distributed file (which is .../texlive/YYYY/texmf/web2c/texmf.cnf).
 % And include *only* your changed values, not a copy of the whole thing!
  
If you read this, you probably still don't know how to proceed.  But
if you look into .../texlive/YYYY/texmf/web2c/texmf.cnf, you'll find a
lot of documentation.  Since your additional tree is something like
TEXMFLOCAL, you can setup your additional tree similarly.

Don't hesitate to look into config files.  It's often amazing how well
they are documented.

But also see my comments below.  Maybe all your efforts had been
unnecessary because what you want to achieve is provided by TeX Live
already (depends on what *exactly* you want to achieve).

 > I think I have found the solution today. The TeX Live manual may 
 > need no improvement here, but it was hard for me, perhaps just 
 > personally because in the beginning (last year), I did not start 
 > with the TeX Live documentation, but with the texhash help and 
 > the TDS specification. So I just spent much time with documentation 
 > that was not very relevant for my problem.

The texhash help message isn't a good starting point indeed. :(

 > A general subject with perhaps-incompleteness of documentation 
 > may be that (especially with complex software) that manuals 
 > sometimes seem to be little helpful for "impatient" users.
 > An alternative may be "user-driven documentation" -- an FAQ; 
 > so structured that the most frequent or urgent questions are 
 > the most easy to find.
 > 
 > There actually is such an FAQ for TeX Live:
 > 
 >     https://wiki.archlinux.org/index.php/TeX_Live_FAQ
 > 
 > for example "I want to use ConTeXt". Until one has something 
 > better, one might point there.

Though the FAQ you mentioned is a good thing in general, it's
problematic to point users of TeX Live from tug.org to documentation
provided by Linux distributors.  This can be extremely confusing.
Linux distributors use a different directory structure.  Even worse is
that they don't provide tlmgr (it would clash with their own package
manager).  The preferred way to maintain TL from tug.org is to use
tlmgr.  Thus, the documentation provided by Linux distributors is not
always optimal and can sometimes be quite confusing.

 > That approach may also be helpful if, as Karl tells me off-list, 
 > TeX Life offers so much that is just too much for the maintainers 
 > to document it completely.

I also fear that people hesitate to read documentation if it's too
detailed.  

Since people hopefully read the TeX Live Guide *before* they install
TeX Live, it's most important that the installation process is
described properly.

Once you have installed TeX Live and are interested in the details of
kpathsea, for example, you can always type

  texdoc kpathsea

on the command line in order to get the complete documentation.  If
the TeX Live Guide would contain the complete kpathsea documentation,
I fear that most people hesitate to read it at all.

 > As to binaries (that I focussed on before), this even seems to hold
 > for engines and formats -- when I compare the TeX Live manual with
 > Arno Trautmann's list of binaries.

As far as etex is concerned, you'll certainly find some hints in the
release history of the TeX Live Guide.

Some years ago there were distinct programs using etex, like pdfetex,
pdfelatex,...  Nowadays all programs except (Knuth's) TeX have etex
compiled in.  Thus, if you run "tex", you get Knuth's TeX with the
original hyphenation patterns for English only and without etex.  No
need to mention that it doesn't produce anything but DVI.

If you run any other program, etex and hyphenation patterns for many
languages are already supported.

 > The user's separate tree may be something very important, thinking
 > of the user's favourite shorthands used for most documents.
 
It's already there.  Try

  kpsewhich --var-value=TEXMFHOME

You can put your all your private files there.  The directory isn't
created by the installer because it's unaware of users.  There is also
TEXMFLOCAL where the administrator can put files supposed to be used
by all users, for instance site-specific document classes, the company
logo, and so on.

Furthermore, neither TEXMFHOME nor TEXMFLOCAL is touched by tlmgr or
the installer.  You can install your files there, upgrade to TL-2013
when it's availabe, and everything works as before.

These things are already there and described in the TeX Live Guide.
If that's all you need,  you certainly didn't have to create your own
texmf tree.

Regards,
  Reinhard

-- 
----------------------------------------------------------------------------
Reinhard Kotucha                                      Phone: +49-511-3373112
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.
----------------------------------------------------------------------------