additional texmf tree for all users (was Re: [OS X TeX] Beginner help with TeXshop/MacTex needed)

Bruno Voisin bvoisin at
Sun Aug 27 17:47:33 EDT 2006

Le 27 août 06 à 19:00, Rowland McDonnell a écrit :

>> Again, I believe that this works. However I have not the slightest
>> idea what i-installer will do with this directory when you will  
>> use it
>> to update distribution. In this sense use texmf.local is much safer
> This is why I am trying to find some proper documentation to explain
> things properly, so that I can be nearly sure what will happen in the
> future.

After cooling down a bit: I can understand your frustration to some  
extent. I come myself from years of practice of Textures (1991-2000),  
then OzTeX (1993-2000), before moving on to OS X and TeXShop/gwTeX.

Textures and OzTeX were (and still are) human-size systems. OzTeX, in  
particular, was put together by one individual (Andrew Trevorrow) and  
came with a manual (ozuser.dvi) which was a pleasure to read: all the  
necessary information was put together in a manual that you could  
print and study on the train, the tram, the bus (that's how I usually  
learn to use new software); it was exposed very pedagogically, nicely  

Coming from Textures, and being hence largely secluded from the rest  
of the TeX world, the OzTeX manual was a pleasure to discover: that's  
how I learnt about PK fonts, TFM and VF files, configuration files,  
encodings, MetaFont, format compilation, and so forth. Being familiar  
with this carefully arranged information was an immense help when  
moving later to TeXShop/gwTeX.

However, the teTeX and TeXLive systems are all but human-size: they  
are a gathering (hundreds of megabytes, compared with the 47  
megabytes or so of OzTeX 5) of stuff written by many people over the  
world. The good side is that you have a system that is more or less  
standard across all platforms (Mac OS, Windows, the various brands of  
Linux, Solaris, etc.). You don't have to worry about what's included,  
in case you collaborate/interact with other TeX users: you can be  
more or less sure that they will have the same components (LaTeX  
packages, hyphenation files, etc.) you're using, and you can be more  
or less sure that you will have the same components they're using.

The bad side is that all these pieces are not so coordinated as they  
are in OzTeX or Textures. In particular, there is no central  
documentation as in OzTeX. Instead, there are various fragmentary  
documentation files, written by different people, using different  
approaches, in different formats (commented source files, or ASCII  
README files, or formatted DVI or PDf files), and placed at different  
locations inside the texmf tree.

That's why we cannot point you to the documentation you're asking  
for: because there isn't any. All there is are the files we mentioned  
to you. That's all we have to offer. You should browse the doc  
folders inside the various texmf trees (texmf, texmf.tetex,  
texmf.gwtex, texmf.local), and see whether you find something there  
that meet your needs. For example, /usr/local/teTeX/share/texmf/doc/ 
tetex/TETEXDOC.pdf is the documentation of teTeX and explains the  
file organization and the workings of teTeX. Gerben Wierda made it a  
bit easier to browse this documentation, by creating a symbolic link  
(akin to an alias) /Library/teTeX to /usr/local/teTeX, so that teTeX  
can be accessed directly from the Finder, without having to use "cd"  
in the Terminal or Go to Folder (Cmd-Shift-G) in the Finder.

Actually the way of providing and accessing documentation in the Unix  
(and hence also OS X) TeX world is a bit different:

- You can use a command-line utility "texdoc" in Terminal. It will  
use a database /usr/local/teTeX/share/texmf.tetex/texdoctk/ 
texdoctk.dat to locate and display the documentation associated with  
any specific TeX module. For example, you could try typing in Terminal:

	texdoc teTeX

and it will (I think) open TETEXDOC.pdf in Preview. Same with "texdoc  
fontinst": it should open /usr/local/teTeX/share/texmf.tetex/doc/ 
fontinst/manual/fontinst.dvi in your DVI viewer of choice (probably  
TeXShop by default). (Sorry, I can't try it right now, as I'm in the  
middle of an Archive & Install of my OS X setup, and I've not yet  
reinstalled TeX.)

There is also a GUI to texdoc, called texdoctk. It requires the  
additional installation of Tk, and if I remember correctly it  
requires X11 as well.

- Emphasis is also put nowadays on online documentation, and  
particularly on FAQs. The searchable FAQ archive at <http://> is often of great help. See the  
list of resources in the section "Where to find help and  
documentation" of <>.

Personally I regret this evolution: I would prefer an all-in-one  
manual, discussing all the aspects of a TeX distro, all arranged  
logically and pedagogically, all written by a single individual or by  
a coordinated group of people, a printed document that could be  
studied even away from a computer or from the internet; something  
akin to the OzTeX manual. Alas, such a thing seem to be definitely a  
thing of the past.

So, to summarize, I think there's no other documentation, on how to  
set an alternative texmf tree, than the files we've already pointed  
you to.

Bruno Voisin------------------------- Info --------------------------
Mac-TeX Website:
          & FAQ:
List Archive:

More information about the MacOSX-TeX mailing list