[tex-live] tlmgr query

[Rowland McDonnell]

Zdenek Wagner,

Thank you *VERY* much for a decent email filled with useful technical
information meant to help me, written in an fashion that is easy to
understand and is a pleasure to read.

I greatly appreciate your efforts.

It just so happens that I'd already worked out quite a lot of what you
wrote, but I can quite understand that it might not have been obvious
that I'd got as far as I had and you have given me some useful new
information for which I am extremely grateful.

What's really a problem for me is understanding the automation - what
exactly happens when you ask tlmgr to do things?  Oh, I can manage my
TeX Live installation manually, using my own slightly strange setup, but
it would be nice to be able to use the automatic update mechanisms for
the TeX Live system as supplied, just so long as I could be sure it
wouldn't break any of my own additions.

That's why my local additions go into a directory that's entirely novel,
requiring:

TEXMFRM = /Users/Shared/texmf.rjmm

TEXMF = {$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,$TEXMFRM,!!$TEXMFSYSCONFIG, 
!!$TEXMFSYSVAR,!!$TEXMFMAIN,!!$TEXMFLOCAL,!!$TEXMFDIST} 

to be added to the texmf.cnf file.

>2009/7/24 Rowland McDonnell <rjmmnet-lists at yahoo.co.uk>:
>>>Some answers ...
>> ...
>>
>> Now, I wish to maintain compatibility with all my old documents.
>>  That means any new TeX system I install must be modified to work
>> appropriately.
>>
>It can be done once for ever quite easily

Every time I have installed MacTeX, I have had to spend a lot of time
over a few weeks working out how to do this, and it's been different
with MacTeX 2006, MacTeX 2007, and MacTeX 2008.

What makes you think there's a `once and for all' solution?  Changes
from year to year so far indicate to me that whatever works with the
current version will not work quite the same with the next one.

I've certainly had to change my setup procedure every time I've
installed MacTeX, and it's always taken non-trivial amounts of work to
learn how.

>> The modifications I need to do are:
>>
>> Unplug Babel
>
>Babel is not hardwired into LaTeX, it's just a package with a lot of
>files. If you do not put \usepackage[languages]{babel} into your
>document, it will not be loaded.

But look at the file latex.ltx.  It loads hyphen.cfg if such a file
exists, yes?

Right.  Then try:

kpsewhich hyphen.cfg

here, that returns:

/usr/local/texlive/2008/texmf-dist/tex/generic/babel/hyphen.cfg

Yes, the standard LaTeX formats load the Babel hyphen.cfg file:

\ProvidesFile{hyphen.cfg}
                [2008/07/06 v3.8l %
      Babel language switching mechanism]

And that means all my documents default to US English hyphenation unless
I load Babel-the-package in each document, each time manually selecting
UK English hyphenation.

If I could find a way of setting Babel up to give me UK English by
default in a fashion that appeared to meet all the requirements
published, then I'd so do.

The only way round the problem of Babel's hyphen.cfg that I've worked
out is to create a version of latex.ltx called rmlatex.ltx which calls
rmhyphen.cfg instead of hyphen.cfg - no other changes.

(rmhyphen.cfg is my hyphen.cfg from my OzTeX installation re-named - it
sets US English as \language=0 and UK English as \language=1 and then
sets \language=1 as the default).

>> Plug in some additional founts
>> Add a local system-wide additional TEXMF tree.
>>
>That's texmf-local. TL (= TeX Live) is installed in a directory named
>/some/path/texlive and it contains separate directory for each year
>and a few directories for each year (texmf, texmf-dist, texmf-var).
>Besides the directories for each year /some/path/texlive contains
>texmf-local which is the system-wide local TEXMF tree.

Yeesss - but that's not always reserved only for locally managed
additions, is it?  That's my worry.

What I've read in the TeX Live guide does not give me any information
about what TeX Live or its tools might do to the contents of that
directory (page 5, section 2.3).

> Its contents
>will not be deleted when you install the next TL release.

Thanks - but my worry is that I cannot be sure that that is how it will
be in future.

My concern on that score is that that part of the directory tree will
not necessarily be free from the ravages of automated maintenance.

With MacTeX 2006 (gwTeX), the texmf-local directory was subjected to the
depredations of the automatic maintenance and installation software
which was sure to break (possibly even delete completely) local
additions placed in that part of the texmf tree.  Hell, it deleted
plenty of other stuff, seemingly at random.

>Now the directory structure. It follows TDS (= TeX Directory
>Structure). You can find a lengthy document about it.

I have done so.  I've even tried to read it.  It's very confusing but in
combination with other information sources, I've got a tiny bit of
useful information out of it with a great deal of effort.

> You can find
>internals on file searching in the documentation of kpathsea.

Yes, I can.  I don't understand much of that either.  You see, I'm not a
Unix hacker, I'm not a programmer, I just don't think in the ways
required to understand that sort of thing.

The problems in understanding that I suffer from are however very easy
to deal with.  I just need a few vital snippets of information to fill
in a few gaps and then I *CAN* use such documentation perfectly well.

I just need a wee bit of help at the start, that's all.   Once upon a
time, I used to be able to get such help easily.  It's harder now - but
you're helping terrifically, for which I thank you.

> However,
>heving spent a few minutes lookikg into texmf-dist and playing with
>kpsewhich you will be able to pout your files to texmf-local even
>without reading the documentation.

Thanks - and I did that years ago, except that I noticed texmf-local was
not a safe place for local additions because it was managed by
i-installer (this was gwTeX in MacTeX 2006) so I found out by asking how
to add a local texmf tree separate to all the standard ones.

> I do not say that you should not
>read it, I am just describing the fast and easy way.

I've read the documentation as best I can.  I don't fully understand the
documentation because it's so poor.  For the documentation to be any
use, I need information that I cannot get from the documentation.

Because of that problem, I found out how to add my own parallel `local
texmf tree' by asking people; I got told to do something like this:

---------------------------------------------------------------------
find / -name "texmf.cnf" to track down texmf.cnf instances.

Edit a copy of /usr/local/texlive/2008/texmf.cnf. 

Add the following—do not put return characters in it (nor spaces, prob- 
ably): 

TEXMFRM = /Users/Shared/texmf.rjmm 
TEXMF = {$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,$TEXMFRM,!!$TEXMFSYSCONFIG, 
!!$TEXMFSYSVAR,!!$TEXMFMAIN,!!$TEXMFLOCAL,!!$TEXMFDIST} 

The main texmf.cnf file lives at /usr/local/texlive/2008/texmf/ 
web2c/. Do not modify it. 
---------------------------------------------------------------------

and, using a `monkey see, monkey do' approach, copied what looked to be
the TDS structure by hand, threw files in what looked to be the right
places, and found that it seemed to work okay.

But I do not fully understand what I've done and I still don't fully
understand the documentation.

>Assume you want to install a font family, you have tfm and pfb files.
>First try that you know how to use kpsewhich. 

You have kindly replied to me in an attempt to help - thank you.  The
following brief section text is explanation about `what it's like for me
with respect to this aspect of the technical facts under consideration'.
The intention is to help you understand where I'm coming from so that
your future explanations for me (should you be so kind as to provide
any) might be less effort for you and more use for me.  Actually, I've
done something similar several times from this point on.  Please
understand that I am trying to explain what things are like for me so
that, should you be interested in trying to help me in future, you will
be in a position to provide information of more use with less effort.

So:

I don't know how to use kpsewhich /properly/.  I've read the man page.
I've got it printed out and I refer to it in times of despair.  Not a
lot of help.

What I've got is a list of incantations that have been suggested by
others.  As and when I've been able to work out why those incantations
work as required, I've been able to learn a bit more from the
documentation which is very useful indeed.

But if need a new incantation, I know I don't know enough to be able to
come up with it myself.  I can see that one must select a suitable
option to specify to kpsewhich which file I'm after, but it's tricky
working out which one.

And I've printed out the kpathsea library and I've tried to read that
too - quite often, actually.  It's helped quite a lot, but only insofar
as it's enabled me to work out how incantations i've been given do what
they're supposed to do.

>If everything is OK, the
>following commands should find Computer Modern:
>
>kpsewhich cmr10.tfm
>kpsewhich cmr10.pfb

Uhuh - that easy, eh?  ;-)  Thank you - I've just documented that as
another incantation I could use.  Sometimes I wonder why the commands
are so apparently complicated...

>Now look into TL directories.

Done that, some time ago.

> You find texmf-dist/fonts with some
>subdirectories. Look into their structure and model the structure in
>texmf-local.

Except that the /local/ directories near the bottom are surely redundant
in the texmf-local tree?  texmf-local is already populated with 'em -
all the directories are empty.

> Kpathsea is configured so that it looks into
>subdirectories so that the exact name of the subdirectory with your
>files does not matter, it just needs to be in the right place.

Do you mean that kpathsea searches recursively inside the appropriate
high-level directory for the file type concerned, regardless of any
subdirectories below that?

I /think/ that's what you're trying to get across and it accords with my
observations.

(`It just needs to be in the right place' is not very helpful.  Of
course it needs to be in the right place!  But what *IS* the right
place, exactly? - not clear from what you wrote at all.  Thing is, I'd
already worked that one out myself so I think I know what you mean and
I'm pretty sure that what you meant is what I found works after
examining the TDS I got dumped on my HDD by the MacTeX installer, IIRC)

> You
>need not have to create lots of branches in texmf-local.

Indeed not - but rather too many seem to be supplied by default.  E.g.,

/usr/local/texlive/texmf-local/fonts/tfm/local/

That `local' subdir on the end is surplus to requirements - isn't it?

> Suppose you
>wish to install two font families, SomeFontFamily and
>AnotherFontFamily. You create directories
>texmf-local/fonts/tfm/somefontfamily for tfm files of SomeFontFamily
>and texmf-local/fonts/Type1/somefontfamily for pfb files, similarly
>for AnotherFontFamily.

[You know, you've written really quite a good example of how to do a
common job.  It just so happens that I already knew how to do it, but
your example and description are genuinely very good - much shorter than
I would usually manage, and very usefully informative.

I think what TeX Live needs, in part, is an introductory document for
those wishing to manage TeX Live, with explanations of: how it all works
in general overview terms, pointers to the heavy documentation, and then
instructions with examples on how to do various common jobs.

Such a document does not exist at the moment.  You've just written
something that could be a useful part of it.

Any thoughts at this point?]

- back to responding directly to what you wrote above:

That makes filing fairly easy.  But you could put the pfb files into
texmf-local/fonts/Type1/ (no subdirs), or (as I have done in one real
case):

/Users/Shared/texmf.rjmm/fonts/Type1/Joanna/

with corresponding tfms here:

/Users/Shared/texmf.rjmm/fonts/tfm/adobe/mjo/

one big map file for all locally added founts:

/Users/Shared/texmf.rjmm/fonts/map/local_extras.map

And the fd files here (with all the other fds for Monotype founts):

/Users/Shared/texmf.rjmm/tex/latex/ac other fd/Monotype/

I never said my filing system was very sensible. ;-)

It has two virtues: it works with MacTeX, and I can work with it.

(I've got an Adobe fount called Monotype Joanna; I'm not sure why I've
got that mad filing scheme.  Monotype Joanna was and possibly still is a
popular fount for paperback books because it's got a fairly narrow
average letter width, allowing more words than you normally get in a
given line width.  It was used in a lot of children's books - Puffins -
that I read when I was young and I like it.)

> Next you create somefontfamily.map and
>anotherfontfamily.map. You probably have them. If not, read the
>documentation of dvips, the syntax is described here.

Indeed it is - and I learnt the syntax and wrote the files.  Some of the
supplied documentation is indeed fit for purpose.

> You can also
>look into some exixting map. Take a simple one, eg dvng.map (kpsewhich
>dvng.map should find it). Put it in the right directory (again, model
>it after texmf-dist). 

Yep.

>Now run mktexlsr. Afterwards kpsewhich should be
>able to find your files. Finally it is necessary to inform dvips,
>dvipdfm, pdftex etc that the font families are available. You do it by
>
>updmap-sys --enable Map=somefontfamily.map

I have so far found it most convenient to put all my locally created map
file entries into a single large map file.  That way, I've only got one
line to add to `whatever it has to be added to', and only one map file
to keep track of.  I think that is the best way of doing it if you're
maintaining things manually; if you're using automated tools, that sort
of approach is probably madness.

>If your fonts are both Type1 and bitmap, you will use MixedMap instead 
>of Map.

Ah!  One confusion cleared up.  I had been wondering about that point -
although I'd not asked about it since I'd not tried to find out myself.
But surely no-one uses bitmapped founts?  Well, not unless they've got
<http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=ransom>.

I assume you mean Metafont founts, which are vector founts rasterized
into bitmaps for printing just as Adobe Type 1 founts are - except that
Metafont way is to rasterize on the host computer, not inside the
printer.

>Instaling LaTeX packages is even simpler. The standard packages reside
>under texmf-dist/tex/latex. You just create similar directories under
>texmf-local, put the files there, run mktexlsr and that's it.

<grin>  One advantage of the way I've got things set up is that I don't
even have to do that.   It's slower to run TeX, for sure - but I'm not
expecting to run hundreds of batch TeX jobs per second or anything and,
well, why not free myself from a bit of fiddle?

I remember running TeX on an 8MHz 68000 powered Macintosh and 4MB RAM;
now I've got one with four 64 bit CPU cores running at 2.5GHz and 6.5GB
RAM which I still don't quite believe.  TeX works quite quickly enough
even with my custom slow-down add-on.

>Notice that you do not need tlmgr at all for your additions.

Oh yes, I can add things manually without much trouble at all, and it's
what I've been doing up until now.

> The steps
>are that simple so that you can do everything just by hand. It is not
>necessary to know what a collection is.

Indeed - but it *IS* necessary to understand such language if you want
to make use of tlmgr, because one cannot understand what tlmgr does
without understanding that sort of language.

>TL even contains a few my packages.

It even contains some of mine ;-)  The only one that I'm not terminally
embarrassed by is sectsty.

> I have just packed the files to
>zip's and uploaded them to CTAN. The TL developers put them somewhere,
>I do not even know in which collection they appear.

I don't even know what `collection' means with respect to TeX Live.
I've asked for the meaning, and `collection of packages' is the only
answer I've had.  Well, I don't know what a `package' is in that sense,
and why put packages together into groups called `collections'?  What is
the purpose?  <shrug>  I'm clueless.  I'm told I could learn if I used
tlmgr but I don't see how that is possible without learning how to use
it first - and I do think I'd break my TeX installation if I just
fiddled randomly with tlmgr.

<shrug>  So I am short of information.  My questions on tlmgr have
generally received answers which seemed rather more intended to insult
me than help me.

What I do generally at this point is give up and accept that the care
and maintenance of TeX Live is meant to be restricted to hackers - if
you're not clever enough in the special hacker sense to understand the
lousy documentation, tough.

> I only know the
>they work if TL is installed. Thus you can see that detailed knowledge
>s not necessary even for package developers.

<puzzled>  Of course not - all you need to know is where to stick your
code so that TeX can see it, and `the current directory' usually works,
doesn't it?

I became a LaTeX package developer back in the days of LaTeX 2.09 when
one wrote style files, not packages.  For most of the time I've written
packages I've had not the faintest idea about anything to do with the
wonderful world of TeX Live.

But if you want to make manual local additions and also use the
automated management tools - well, then I think it is necessary to have
a better understanding than what I have at the moment.

Okay, I've got a way to add things locally by hand and it works.  But I
can see it's ugly.  And I dare not try updating the TeX Live
installation itself at all.  I replace it with a new one every year or
two and in between, the installation is not changed except with my local
additions.

But since there *is* a system of updating TeX Live with the latest
goodies as they're released, I thought it might be a good idea to learn
about it - if only so that I could perhaps stop using my odd parallel
texmf tree, which I've never been very happy with.

The process of installing each new version of MacTeX and getting it
working has so far not taken less than about (at a guess) 40-80 hours
work on my part.  It does not get much easier with each new version
except where my notes from the previous version are still relevant.

So far, I've installed MacTeX 2006, 2007, and 2008.  In each case, the
job was a nightmare from hell and involved suffering an awful lot of
very upsetting personal comments when I tried to find out technical
information about what I needed to do.

>> That last part might not be necessary any more, but there was no
>> such thing under teTeX and I do not relish the thought of trying to
>> find out if there is such a thing supplied with TeXLive's current
>> standard setup).
>>
>texmf-local was introduced in teTeX many many years ago. In fact it
>was there long time before I started to use teTeX.

Yes, but texmf-local has been managed by automated management software
before now - at least it has with the first version of MacTeX I
installed, and that was the first time I'd actually come across TeX Live
(CMacTeX does use a texmf structure, but it's arranged specially for
CMacTeX and properly documented).

What I want to know - as my final aim for all these questions, I suppose
- is what tlmgr does and what guarantees there are about the security of
the texmf-local part of the TDS with respect to tlmgr, anything else,
and future developments.

I've had a MacTeX automated management tool delete data before now -
data that I wanted to keep, ta.  Yes yes all the stuff was available in
copies elsewhere, but that's not the point, is it?  You don't want a bit
of software breaking something you've got working on your computer, do
you?

>> It was very easy to do with OzTeX because OzTeX was properly 
>> documented
>
>TeX Live _is_ documented, all you need is to read the manuals.

But the manuals are very poor in my opinion; I have found it impossible
to learn much from any of them.

- except in the few cases when I've found someone willing to give me the
small help I need to get me over the initial hurdles.

See `Failure notice' for a plain explanation.

> I know
>C, Perl, Bash and other languages well enough so that I could read
>sources of the tools in TL but I have never done it, I have just read
>the manuals.

Yes, and they make sense to you because you know C, Perl, Bash, and
other languages (which means you have certain expectations and
understandings that I do not) and because you're a hacker, you've got
the right sort of mind to work with the sort of documentation that's
supplied.

We mere mortals, on the other hand, are left baffled initially, unless
we can get a bit of help from one of the gods such as yourself.

> When I started to use teTeX, I was accustomed to emTeX
>runing under OS/2. I discovered the fast and easy way as described
>above and adapted my environment to emTeX within half an hour or so.

When I first installed MacTeX, it was some months before I got it
working.  My first attempt to get the help I needed to set it up to work
attracted so much hostility that I just withdrew and gave up on MacTeX
entirely.

I stuck with an old version of OzTeX for a very long time because it was
impossible to figure out how to set up MacTeX on my own and there was
no-one willing to give me the information I was missing.

I have since read of other people who have had similar experiences.

I am not, as some have suggested, a uniquely useless individual.

> I
>did read the documentation later because I want to do things that
>normal users do not need. If you follow my advice, you will be able to
>do all you need after an hour or so

But your well meant and very well written advice does not cover the
operation of tlmgr.  What it covers - and does so well - is manually
adding extra bits to TeX Live, but I worked out how to do that some
years ago, with a bit of help from a mailing list.

(I mean it about `well written' - you cover what needed covering, it's
all precise, to the point, and lacking in waffle.  If I didn't already
understand the stuff you'd explained, the things you did tell me about
would have got me sorted out beautifully.  For sure it could be written
in higher quality language for formal presentation if you wanted to, but
it's good stuff.  And I'm not saying that to suck up to you - I'm
letting you know you're good at that job, you've done it well, and I
think that anyone who is good at that sort of thing ought to be told)

> and you will be able to help other
>users since tomorrow.

Some years ago, I worked out how to do what you have very kindly
explained to me in your email - it took a few weeks of occasional work.
I still do not feel competent to offer anyone advice on how to set up
MacTeX or any other sort of TeX Live installation.

I have been trying to learn enough about TeX Live to manage it sensibly
for quite some time - over the past couple of years.  I've failed to do
so and I would not be happy giving anyone *ANY* advice on how to set up
their TeX Live system.

So I'm afraid you're wrong in what you suggest.

What I find frustrating is that most of the time I ask for specific
technical information, I get lectures about reading the manual.  I have
tried reading the manuals and because of the manuals, I have to ask
questions.

When I point out, in response to instructions to read the manuals, that
the manuals are not very good and I can't learn from them, I still do
not get told the few times of technical information I request - what I
get then is personal abuse.  You've seen it here, I expect - thankfully,
you're a lot more civilised than some folk here.

But that's how it goes and that's why I'm still pretty much clueless
about the workings of TeX Live.

I'm afraid that while your very good and very clear advice does permit
me to set up local modifications, it's the automation that I'd like to
learn about and I'm no closer to finding out about that than I was.

I've got local additions set up and working.  I will not follow your
advice unless I can learn more about TeX Live, specifically with respect
to what happens to things that I put in the defined TEXLOCAL part of the
standard installation.

That is because I am concerned that something will end up being badly
broken due to past experience when things *have* ended up badly broken.
Unless I understand `how TeX Live works' well enough to be sure I'm
safe, I'm sticking with what I've got because while I'm sure it's ugly,
it also works.

>> (and didn't come with Babel anyway).  I worked it all out myself from
>> the supplied documentation without needing any help from anyone.
>> Indeed, I used to give help to other OzTeX users and did so much of 
>> that
>> on the OzTeX-info mailing list that I got an official `thanks' from
>> OzTeX's author.  So please do not sneer at me for being ignorant of 
>> TeX
>> as you have done below - I'm far from it.
>> ...
>>
>> Unfortunately, the documentation, while significantly better than in 
>> the
>> past, fails to do what it needs to do.
>>
>I started to use TeX in 1991. It was just after Velvet revolution,

(ah - so you're Czech?  Or Slovak.  Argh.  The map of Europe used to
have fewer countries on it....

Completely irrelvant, but: I used to own a Czechslovakian motorcycle (a
125cc CZ - economical motorcycles are good for poor students); and I
/suspect/ I was conceived in Yugoslavia (is that a question you'd want
to ask your parents?  Nor me).  Neither nation exists any more, which is
weird.  I once visited East Germany.  Good riddance to bad rubbish in
/that/ case...)

> the
>Iron Curtain no longer existed but the market was not established. It
>took me 2 years before I managed to buy the TeXbook.

!!!!!  Blimey.

> Internet was not
>available, I had just csearn 

Aha!  That's CS for Czechoslovakia and EARN for European Academic
Research Network.  Coo.  I'd never heard of either - we had/have
<http://en.wikipedia.org/wiki/JANET> in the UK, which I assume had links
to EARN (JANET currently links to <http://en.wikipedia.org/wiki/GEANT>).

>access over 56kb/s modem, 

The first modem I used was 1200 baud - and that was a fast one.  The
slow ones were 300 baud.

>simtel was the
>most important source.

Uhuh.

> My first TeX distribution came on 5 1/4"
>disquettes.

(Diskettes is the English version of that French word ;-) )

> Yet I was always able to find documentation for the whole
>system.

I could always find the documentation I needed when I used OzTeX and
CMacTeX on my Macs in the past; and emTeX on MS-DOS before then.  I
didn't need any help with them - well, aside from a few minor iffy bits
with CMacTeX which turned out (more or less) to have been bugs IIRC.
Aside from that, I DID set up and use all three on my own without
trouble and with only the supplied documentation for help.

I only started to have significant trouble when Macs turned into Unix
machines and we got a full Unix-style TeX distribution.

Documentation for TeX Live is nearly all written by and for heavy duty
hackers with a good understanding of the conventions of the system.  For
someone like myself coming to it all cold, the documentation is very
obscure.

I've seen this a lot - the `hacker type' can dive in and work with that
stuff; while people like can't.

Contrariwise, I've noticed that I'm a lot more use than the `hacker
type' /in general/ when it comes to deal with certain real world things
- *YOU* sort out the computer, and *I* shall set up the experimental rig
on the bench, sort of thing.

N.B.: I wrote `in general' as an important get-out clause.

There are clearly different optimizations going on inside different
people's heads.  I've grown up with a mind developed to work *that* way,
and I've always found it impossible to work with `hacker' type manuals.
Well, I say `always', since I first met that sort of thing when I was
about, oh, 15 years old, at a guess.  I'm past 40 now.

There always used to be plenty of computer documentation that I could
work with - most of it from UK firms was excellent, back in the old
days.  That from US firms was less so and please let's try to forget all
about old-style Japanese technical manuals (famously poor English).

<shrug>  But since the idea of providing a proper manual was dropped by
most computer firms and software suppliers back in the 1990s, I've been
stuck mostly with old software because a lot of the new stuff, I just
can't learn how to use.  Intuit it from the GUI, they tell me.  That
doesn't work with anything but simple single-purpose applications the
use of which I already understand.

It's not all bad - Apple has address the problem in some cases by
producing excellent tutorials for some of its software, for example.  We
might not have a manual, but a comprehensive tutorial plus reference
information via on-line help does me very nicely, thanks.

> It is just necessary to read them. They now contain quite a
>lot of pages because the nowaday's tools did not exist in 1991 but
>everything _is_ documented.

It might well be, but most of the documentation unfortunately does not
currently make sense to me.  I can't use it /at the moment/ - I need a
little help getting started.  There are always problems with undefined
terms and all sort of little hiccups that I *CANNOT* get round without
having someone tell me the answer.  And believe me, I've tried.

>I subscribed TeX some discussion groups in the beginning of 1992.
>First I asked questions but after a week I was able to answer someone
>else's questions. TeX is really that simple.

Tell you what, why don't you download OzTeX and find a Mac to install it
on?  Once you've done that, look at `Thanks' in the `Help' menu.

Third line from the bottom, you'll see some familiar names.  Mine is one
of them.  I had no idea I'd done anything to deserve thanks, so I
emailed the author and asked him why.  Andrew Treverrow told me it was
because I'd been so helpful answering questions on the oztex-info
mailing list.

But I've been using MacTeX since 2006 and I do not feel competent to
answer questions about the underlying TeX Live installation.

>>> Anyone having
>>>ever prepared a TeX system
>>
>> Such as myself.  No, not the heavy duty stuff, but I've put together
>> custom TeX distributions based on OzTeX for my own purposes.  And I
>> could do that because OzTeX was properly documented.
>>
>> (I even once installed emTeX in a non-standard part of the directory
>> tree and that took all flippin' weekend, that did.  The next time I
>> installed emTeX, it came with instructions which included `Install
>> it only in the default location, you'll be glad you did so' and I
>> thought `Damned right!')
>>
>emTeX's documentation was primarily written for Information
>Presentation Facility and then extracted into plain text files for use
>in DOS.

I don't know what the significance of that might be, but I found emTeX's
documentation perfectly clear and easy to work with.

Hmm:

<http://en.wikipedia.org/wiki/Information_Presentation_Facility>

so that's what information presentation facility was.

> The device drivers and even mf386 worked better in OS/2
>because the system has multiprocessing and multithread support (unlike
>DOS).

Doesn't mean you get better results, merely a better functioning
computer while you get the results.  For a single user PC being used as
tool to create written material via a text editor and TeX, the
improvements you get by having a proper OS instead of MS-DOS don't
really matter.

> Anyway, for different reasons I never had emTeX on drive C so
>that I had to modify environment variables. My first emTeX
>installation under DOS started to work after 2 hours or so. I did not
>know anyone who could help me, I have just read the documentation that
>came with emTeX.

*TWO HOURS*!!!! <stunned>  Like I say, it took me all weekend to get it
all sorted out, and it wasn't like I wasn't already familiar with TeX.
MInd you, I do mean `all fully sorted out', not merely `starting to
work'.  Maybe that's the difference?

But aside from that: there was a situation where I say I found the
documentation perfectly clear and easy to work with, and it took me all
weekend to do a job that you seem to have managed in two hours.  And
that was when I thought everything was going okay - slowly, admittedly,
but I never ran into any trouble aside from a frequent lack of hot tea
(damn!  Drunk it again!) which is always easy to fix with a trip to the
kitchen.

>>> knows that this is a huge amount of work,
>>>and that a few hours here and there is far from being enough to
>>>understand even the surface.
>>
>> Thank you for your further illuminating comments.
>>
>> I do not need to understand the full details.  I just need to
>> understand enough to maintain my TeX system intelligently.  I expect
>> that a few weeks of working hard at the job will be enough - if I
>> can find someone willing to explain to me the undefined terms that I
>> do not understand.
>>
>Less than 2 hours _must_ be enough to make everything running for a
>person who knows nothing about TL internals

In which case, I must not be a person.

I did get things set up.

It took me an *AWFUL* lot more than two hours.  Two hours isn't even
long enough to end up finding all the needed documentation, let alone
read it.  I don't see how you imagine anyone would be able set up MacTeX
in anything less than a full day's work, at least the first time and
assuming a good working knowledge of general TeX systems.

It took a *LOT* more than a full day's work when I set up MacTeX 2006,
not quite as long but still more than a full day's work when I set up
MacTeX 2007, and MacTeX 2008 was no easier than MacTeX 2007.

I don't think I've got things running smoothly at all - I've just got
MacTeX 2008 set up as badly as MacTeX 2007, which means I'm only really
confident it'll work okay for those jobs I've used it for already.

> and just needs to put
>his/her own files to texmf-local.

In a fashion consistent with the required directory structure and
consistent with not being broken by the action of some program - and of
course the modifications are ignored until mktexlsr is executed.

So it's not quite as simple as you make out.  Not to mention the fact
that it's not at all obvious that it's sensible to put things in
texmf-local even when you've discovered the existence of that tree.

For example, the `overview of TeX Live' in the TeX Live guide states:

------------------------------------------------------------------
TEXMFLOCAL The tree which administrators can use for system-wide
installation of additional or updated macros, fonts, etc.
------------------------------------------------------------------

which is enough to get me to think `Okay, that's *probably* the place
for the local additions I want to add, but I need to check how it fits
in with things, especially all this automation I'm reading about'.

And that process of checking is awkward to say the least since there's
no obvious pointer in the TeX Live guide to further information on that
subject.  But I've got the wit to think `Okay, let's find the TDS
documentation, that's bound to help'.

So one reads...:

------------------------------------------------------------------
2.3 Local additions

The TDS cannot specify precisely when a package is or is not a “local
addition”. Each site must determine this according to its own
conventions. At the two extremes, one site might wish to consider
“nonlocal” all files not acquired as part of the installed TEX
distribution; another site might consider “local” only those files that
were actually developed at the local site and not distributed elsewhere.

We recognize two common methods for local additions to a distributed
texmf tree. Both have their place; in fact, some sites employ both
simultaneously:

1. A completely separate tree which is a TDS structure itself; for
example, /usr/local/ umbtex at the University of Massachusetts at
Boston. This is another example of the multiple texmf hierarchies
mentioned in the previous section.

2. A directory named ‘ local’ at any appropriate level, for example, in
the format , package , and supplier  directories discussed in the
following sections. The TDS reserves the directory name local for this
purpose.

We recommend using local for site-adapted configuration files, such as
language.dat for the Babel package or graphics.cfg for the graphics
package. Unmodified configuration files from a package should remain in
the package directory. The intent is to separate locally modified or
created files from distribution files, to ease installing new releases.

------------------------------------------------------------------

And that doesn't me help at all, does it?  In fact, it makes it plain
that if I'm to find out about the specific TEXMFLOCAL defined tree with
TeX Live, I need documentation on this subject specific to TeX Live but
that does not appear to exist.

> Afeter a few weeks you will become a
>wizard.

I've had TeX Live on my Macs since MacTeX 2007.  I am still mostly
baffled by its setup and management.

I can assure you that a few weeks after I've set MacTeX up, I've
forgotten almost all that I had learnt.  I set it up with sweat and
empiricism (i.e., I don't understand it but it works) without much
understanding and then I leave it alone because I dare not fiddle with
it for fear of breaking it.

I can make local additions - so if I've written something I want to use,
or if there's somethig someone else has written that I want to use, I
can add it without bother.  But I do that by hand the old-fashioned way
I've been using since the 1980s using (in this case) my own home-grown
parallel additions directory quite separate to anything that TeX Live
was set up to use.

>> ...
>> I fail to understand the connection you are making between MS Word
>> and a TeX installation.
>>
>This is (I hope) to demonstrate that you started to go the wrong
>directions.

But I wasn't.  If what you say is true, then my question was badly
misinterpreted in that particular case.

> You want answers that are useless fr beginners.

Useless for a newcomer to TeX, perhaps; but not useless for someone
experienced in looking after a TeX installation and in using TeX who's
trying to learn how to set up and use a TeX system.

> You can
>spend months with tlmgr but it won't help you to maintain your own
>installation.

`My own installation' is `MacTeX 2008 as I've put on this Mac, all of
it.'

Now then, apparently tlmgr is the tool to use if you want to keep your
TeX Live installation up to date.  But you know what?  I don't know what
`up to date' means!  What, exactly, is the `current version of TeX Live'
that tlmgr updates one to?  How does one control the process?  Start up
tlmgr -gui and it's obvious - that's all the documentation tells me
about it aside from the tlmgr man page, which doesn't much help me
either.

>>> but with TeX you have at least the chance to
>>>understand the internals, if you want to know them.
>>
>> You have that chance with MS Word too.  All you have to do is
>> decompile the code and work at it.  It just takes reading and a
>> serious nvestment
>
>And you violate the license.

Maybe, maybe not.  In any case, I am talking about what one might do,
not what one may do.

(I'm using the words `may' and `might' quite precisely).

In English law, one may place restrictions on a good for sale which
restrictions apply after purchase, but such restrictions must be agreed
to as a contract between buyer and seller before the sale occurs so I
suspect that a lot of these software licences cannot possibly have any
legal standing at all in England and Wales (and probably the rest of the
UK, but we have three different legal systems and I'm not a lawyer).

>> of time - nothing more nor less than what you say is needed to
>> understand TeXLive.
>>
>> In both cases, the vast majority of people are completely incapable
>> of figuring anything out that way.
>>
>> In the case of TeX, it's *VERY* hard for a newcomer to understand the
>> details without an existing expert to talk to to explain the written
>> documentation and to guide them through the written sources.  The
>> available documentation mostly seems designed only for those who
>> understand it already.
>>
>No!

But yes, it does seem like that to me - really it does.

> As I wrote above, I just got disquettes from a colleague of mine.
>I have never heard of TeX ago. I have never seen any (La)TeX file.
>There was nobody to help me. Within 2 hours emTeX was installed and I
>created my first simple LaTeX document. 

You are an unusual person, then.

I knew how TeX operated and I had experience of using LaTeX and writing
style files (this was the LaTeX 2.09 days).  I also had experience
fiddling around with MS-DOS.  It took me all weekend to get emTeX
installed (due to me insisting on installing it in a non-standard
location for the sake of tidiness, like the bloody fool that I am).

And I knew a reasonable amount about how TeX worked and so on.

>The documentation always
>existed and it was written so well that a person with absolutely zero
>knowledge could start.

That was indeed the case with emTeX - emTeX was very well documented,
quite unlike TeX Live.

> But we still repeat the same: locate the
>manuals and read them.

But the manuals that come with TeX Live are dreadful.  They cannot be
used at all by most people.

Mac users mostly seem to use TeX Live as a black box - run the MacTeX
installer, accept that it's done something beyond understanding, and
then use TeXShop to prepare LaTeX input files and accept the fact that
you can't do anything about the underlying TeX system.

I'm not happy with that approach.

The documentation that came emTeX was *excellent*.  The documentation
that comes with OzTeX is excellent.  The same applies to CMacTeX.

I have installed and managed all three - one on MS-DOS, and two on Macs.

I've had no trouble at all learning how to do so or in doing what I
wanted with any of those TeX systems.

Then I installed MacTeX and instantly ran into trouble due to the rotten
documentation.

Three TeX systems on two different OSes - no trouble.  Then I find the
fourth TeX system I meet baffles me.

And I say it's the documentation that's the problem.

> Find the parts you must read immediatelly, set
>up your installation and read the rest later. You should train
>yourself to read the manuals that way, it will help you not only with
>TeX.

The problem with the TeX Live documentation is that very little of it
can be read without having to refer to dozens of other information
sources. It's so hard to get any use out of the Tex Live documentation
that I take the line that anything I want to know about, I have to write
my own documentation for.

I'm getting there slowly - re-reading some of the documentation that
left me totally baffled in the past now results in me understanding
quite a lot.  Slowly, slowly, one small step at a time, I'm piecing
together the structural information I need.

I do a job of finding out what I want by reading what I can find that
makes sense and asking people.  If I then do find out what I want, I
make a note here in my own pile of documentation on TeX Live.

Most of the time, I fail to find out what I want to know, so I have a
poor understanding of TeX Live and very little documentation of my own.

<shrug>  So it goes.  One problem is that when I ask for information, I
often get told to RTFM.  But you see I've already tried that and it's
not helped which is why I'm asking someone to tell me something!

Anyway, that's enough drivel from me.  You've been very kind and very
helpful and I appreciate the fact that you put the time in to try and
illuminate my darkness.  I'll get there one day, I expect.

Cheers!
Rowland.