[tex-live] documentation of TeX Live

[jfbu]

Hi Reinhard


Le 11 mai 2015 à 23:43, Reinhard Kotucha <reinhard.kotucha at googlemail.com> a écrit :

> 
> Hi Jean-François,
> it's true that the installer is described more elaborately than other
> things in The TeX Live Guide because this is the only document people
> read before they install TL.  Once TeX Live is installed, more
> documentation is available via texdoc, man, info, and <progname> --help.
> 
> I think that The TeX Live Guide shouldn't try to explain everything
> in detail but tell people how to get further information.

> On 2015-05-11 at 16:29:03 +0200, jfbu wrote:
> 
>> - if possible, include some more details on the (mostly font related)
>> area where Mac OS X differs from GNU/Linux,
> 
> I'm on Linux and thus don't know whether relevant points regarding OS
> X are missing.

I suppose the non-use of fontconfig in Mac OS X is the main point,
thus the information given by Herb about the simplest, no hassle
way, to let XeTeX work with the TexLive distributed OpenType fonts
would be the thing to add.

There might be some other issues related to which versions
of ghostscript or Image magick convert to have or not, but
if people go the MacTeX way all will have been pre-resolved for them,
perhaps a pointer to some document on MacTeX site, if it exists.

There was an issue which arose with Yosemite about moving
things out of /usr/local before any major system upgrade and move
them back in. This was very well documented by Herbert Schulz 
and Richard Koch on
http://tug.org/mactex/yosemite.html
just inserting the link in the TeX Live Guide would help

In this context, I personally recommend people do a once and for all
sudo chown -R user /usr/local/texlive, and also for the texmf-local
this solves a lot of hassles.



> Windows definitely needs extra documentation due to significant
> differences.  Not only the system is completely different but there
> are replacements for some programs which are ubiquitous on Unix
> systems but not available on Windows, etc.

Yes, I should not have expressed myself in a whining 
" I see much about Windows, less about Mac OS, and myself I am 
on Mac OS, thus I complain" mode

> 
>> - detail tlmgr use as comprehensively as has been done for the 
>> installation process itself
> 
> As I said before, the installation process has to be explained in detail
> because at this stage no other documentation is available.  Instead of
> mentioning some of tlmgr's features, I'm convinced that users benefit
> more when pointed to the complete documentation (tlmgr --help;
> texdoc tlmgr; man tlmgr).


Looking again, it might be only a matter of adding one example
with the tlmgr info (now that it has incorporated earlier
"search" and "list" facilities)

> 
>> - move a large portion of the Web2C/kpathsea documentation to a
>> separate documentation for "system administrators and developers"
> 
> Full documentation can be accessed easily as PDF when TL is installed
> (texdoc web2c; texdoc kpathsea).  And The TeX Live Guide contains
> links to the HTML docs @tug.org already.
> 
> Do you ask for duplication because The TeX Live Guide is translated to
> other languages?  I don't know whether developers really need these
> translations.  Computers speak English.  If documentation is needed in
> other languages though, it makes more sense to me to translate the
> original texinfo sources instead, not only excerpts.

I wasn't meaning duplication, but excision from the TeX Live
Guide of some portions of the kpathsea/web2c.

Naturally, mentioning the executables bundled with web2c
as is currently done at the start of 7 A user’s guide to Web2C 
is indispensable.

But the somewhat detailed description of the syntax for texmf.cnf
files which comes afterwards might be a bit overwhelming 
for a user who just completed the installation (and thus had the 
customization done via the install-tl, and not in need at that
point to go into fiddling with the whole thing), and also a bit
overwhelming (to me) is the developed example of debugging a failed
compilation  7.2.4 Debugging actions.

I understand the difficulties with multi-lingual documentation.

It makes it hard to remove pieces, the whole thing has a natural
tendency to become incremental.

About incremental: the History section appears to me extremely
important and useful, for people who have gained some familiarity
with the system after one or two years of use.

> If we want that people read the document at all, it shouldn't be too
> big.  Ideally it explains what users have to know before TL is
> installed and how to get additional information later.  But links to
> stuff @tug.org are ok.
> 
> IMO texdoc could be metioned more often in the document.  I fear that
> still many users aren't aware of it.  This is a real pity.


there could possibly be a common section "Main tools for everyday
installation management"

tlmgr: updating an installation, exploring available things within
the installation, ...

kpsewhich: explain that files in <workingrepertory> have priority on files
in TEXMFHOME which have priority on files in TEXMFLOCAL which have
priority in TEXMFMAIN/DIST, a bit about TDS, how to use then kpsewhich
to check which foo.sty etc ... is actually used.

texdoc: insist on the quasi mandatory option -l or --list, because often
nowadays important info is in README's or other files which typically
are given less priority than foo.pdf. I often find that people do
not include in the main foo.pdf the changes from previous releases,
and that the README or some other file is the fastest path to that
information. If one gets into the habit of doing tlmgr update --all, 
one wants to see what changed when a package got updated.

mktexlsr and updmap-sys, mainly for adding fonts to texmf-local.

Regards

Jean-François