[tldoc] new section on texmf trees

[Karl Berry]

Sorry to report that there were irresistible suggestions to add new text
to the TL documentation on the assorted texmf variables and trees.  Diff
below, sources and output at the usual places:
http://tug.org/texlive/devsrc/Master/texmf-doc/source/english/texlive-en/
http://tug.org/texlive/devsrc/Master/texmf-doc/doc/english/texlive-en/

Thanks to Daniel for drafting the changes.  The new section comes from
the teTeX documentation (considerably rewritten).

Still shooting to have all doc translations in by October 31 at the very
latest (sooner would be better -- should I pretend the deadline is
October 24? :).  Anything not in by then may have to go on the web
instead of being on the CD.

Thanks,
Karl

==== //depot/Master/texmf-doc/source/english/texlive-en/live.tex#27 - /home/karl/src/Master/texmf-doc/source/english/texlive-en/live.tex ====
@@ -223,8 +223,6 @@
   \renewcommand{\arraystretch}{1.3}  % open up interrow spacing
 \begin{tabular}{>{\ttfamily}lp{.78\hsize}}
 bin        & The \TeX{} system programs, arranged by platform. \\
-MacOSX     & Supporting software for \MacOSX (see
-  section~\ref{sec:mac-install}, \p.\pageref{sec:mac-install}). \\
 source     & The source of all programs, including the main \Webc{}
   \TeX{} and \MF{} distributions. These are stored in a
   \cmdname{bzip2}-compressed tar archive. \\
@@ -232,11 +230,14 @@
   \emph{not} installed automatically.  This includes
   assorted editors and \TeX\ shells. \\
 texmf      & Tree for the programs, along with their support files and
-  documentation.  Does not include \TeX\ formats and packages. \\
-texmf-dist & The main tree of formats and packages. \\
+  documentation.  Does not include \TeX\ formats and packages.
+  (\texttt{TEXMFMAIN} in the next section.) \\
+texmf-dist & The main tree of formats and packages.
+  (\texttt{TEXMFDIST} in the next section.) \\
 texmf-doc  & Tree for self-contained pure documentation, arranged by
   language.  \\ 
-texmf-var  & Tree for files automatically generated and stored. \\
+texmf-var  & Tree for files automatically generated and stored.
+  (\texttt{TEXMFSYSVAR} in the next section.) \\
 xemtex     & Tree for supporting programs used only in Windows.
   These programs generally come pre-installed on Unix systems, or are
   at least easy to compile. \\
@@ -259,6 +260,45 @@
 top-level file \OnCD{doc.html} may also be helpful.
 
 
+\subsection{Overview of the predefined texmf trees}
+\label{sec:texmftrees}
+
+This section lists all predefined variables specifying texmf trees used
+by the system, and their intended purpose. The command \texttt{texconfig
+conf} shows you the values of these variables, so that you can easily
+find out how they map to directory names in your installation.
+
+\begin{ttdescription}
+\item [TEXMFMAIN] The tree which holds vital parts of the system 
+  such as helper scripts (e.g., \verb+web2c/mktexdir+), pool files and
+  other support files.
+\item [TEXMFDIST] The tree which holds the main set of macro packages,
+  fonts, etc., as originally distributed. 
+\item [TEXMFLOCAL] The tree which administrators can use for system-wide
+  installation of additional or updated macros, fonts, etc.
+\item [TEXMFHOME] The tree which users can use for their own individual
+  installations of additional or updated macros, fonts, etc.
+  The expansion of this variable depends on \verb+$HOME+ by default, % $
+  which dynamically adjusts for each user to an individual
+  directory. 
+\item [TEXMFCONFIG] The tree used by te\TeX's utilities
+  \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
+  configuration data.  Under \verb+$HOME+ by default. %$
+\item [TEXMFSYSCONFIG] The tree used by te\TeX's utilities
+  \verb+texconfig-sys+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to
+  store modified configuration data.
+\item [TEXMFVAR] The tree used by \verb+texconfig+, \verb+updmap+ and
+  \verb+fmtutil+ to store (cached) runtime data such as format files and
+  generated map files.  Under \verb+$HOME+ by default. %$
+\item [TEXMFSYSVAR] The tree used by \verb+texconfig-sys+,
+  \verb+updmap-sys+ and \verb+fmtutil-sys+ to store (cached) runtime
+  data such as format files and generated map files.
+\end{ttdescription}
+
+For more discussion of \texttt{texconfig} and related utilities, please
+see section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}.
+
+
 \subsection{Extensions to \protect\TeX}
 \label{sec:tex-extensions}
 
@@ -658,10 +698,12 @@
 local packages or configuration settings.
 
 \item [TEXMFSYSVAR] This tree is where \cmdname{texconfig-sys} puts
-files that \emph{are} version-specific; see section~\ref{sec:texconfig},
-\p.\pageref{sec:texconfig}.  The default value is
+files that \emph{are} version-specific.  The default value is
 \dirname{TEXDIR/texmf-var}, and there's generally no reason to change
-it.
+it.  There is also \envname{TEXMFSYSCONFIG}, which is where
+\cmdname{texconfig} looks for modified configuration data.  See
+section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig} for more
+information.
 
 \end{ttdescription}
 
@@ -936,7 +978,21 @@
 changed, to work under \dirname{$HOME/.texlive2005}.  To alter system
 directories, use \cmdname{updmap-sys} and \cmdname{fmtutil-sys}.
 
+In particular, for multi-user systems, you will probably want to
+pregenerate the standard formats with \texttt{fmtutil-sys --missing}.
+Otherwise, each user will end up with their own formats.
 
+Also, if you have a personally-modified copy of \filename{fmtutil.cnf}
+or \filename{updmap.cfg}, instead of using the ones generated by
+installation, they must be installed in the tree referenced by the
+variable \envname{TEXMFSYSCONFIG}.
+
+The variables specifying the directories altered by these commands are
+listed in section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
+You can see the actual directories by running \texttt{texconfig conf},
+and you can change them by editing \filename{texmf.cnf}.
+
+
 \subsection{Testing the installation}
 \label{sec:test-install}
 
@@ -3028,6 +3084,17 @@
       user-specific files, under \dirname{$HOME/.texlive2005}.  
       See section~\ref{sec:texconfig}, \p.\pageref{sec:texconfig}.
 
+\item Corresponding new variables \envname{TEXMFCONFIG} and
+      \envname{TEXMFSYSCONFIG} to specify the trees where configuration
+      files (user or system, respectively) are found.  Thus, you may
+      need to move personal versions of \filename{fmtutil.cnf} and
+      \filename{updmap.cfg} to these places; another option is to 
+      redefine \envname{TEXMFCONFIG} or \envname{TEXMFSYSCONFIG} in
+      \filename{texmf.cnf}. In any case the real location of these files
+      and the values of \envname{TEXMFCONFIG} and \envname{TEXMFSYSCONFIG}
+      must agree.  
+      See section~\ref{sec:texmftrees}, \p.\pageref{sec:texmftrees}.
+
 \item Last year, we kept \verb|\pdfoutput| and other primitives undefined
       for DVI output, even though the \cmdname{pdfetex} program was
       being used.  This year, as promised, we undid that compatibility