fix section labels; TEXMFLOCAL description per siep, tldoc mail 21 Jul 2008 21:28:46

git-svn-id: svn://tug.org/texlive/trunk@9745 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 51 insertions, 36 deletions

diff --git a/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty b/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty
index 02dbfdecdc7..68a971b3fad 100644
--- a/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty
+++ b/Master/texmf-doc/source/texlive/texlive-en/tex-live.sty
@@ -264,8 +264,7 @@
   \typeout{TeX Live documentation in PDF format}
   \RequirePackage[breaklinks,
                   colorlinks,linkcolor=hypercolor,citecolor=hypercolor,
-                    pagecolor=hypercolor,urlcolor=hypercolor,
-                    filecolor=hypercolor,
+                    urlcolor=hypercolor,filecolor=hypercolor,
                   bookmarksopen,
                   %pdfstartview={FitBH -320000}, % fails with acrobat7
                   hyperindex]
diff --git a/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex b/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex
index 41be16f44fc..75cdadcccf5 100644
--- a/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex
+++ b/Master/texmf-doc/source/texlive/texlive-en/texlive-en.tex
@@ -4,7 +4,6 @@
 % Public domain.
 %
 \documentclass{article}
-
 \let\tldocenglish=1  % for live4ht.cfg
 \usepackage{tex-live}
 \usepackage[latin1]{inputenc} % translators: use your preferred encodings.
@@ -327,7 +326,7 @@ The default layout is:
       \item [texmf-config] \envname{TEXMFSYSCONFIG}
     \end{ttdescription}
     \item [texmf-local] \envname{TEXMFLOCAL}, intended to be
-      retained from release to release
+      retained from release to release.
   \end{ttdescription}
   \item[user's home] (\texttt{\$HOME} or
       \texttt{\%USERPROFILE\%})
@@ -445,7 +444,7 @@ utilities.
 \label{sec:install}
 
 \subsection{Starting the installer}
-\label{sec:inst_start}
+\label{sec:inst-start}
 
 To start with, get the \TK{} \DVD{} or download the \TL{} net installer,
 and locate the installer script: \filename{install-tl} for Unix,
@@ -564,9 +563,9 @@ documentation.
 
 \subsubsection{Mac\,OS\,X}
 
-As mentioned in \label{sec:tl-coll-dists}, a separate distribution is
-prepared for \MacOSX, named Mac\TeX\ (\url{http://tug.org/mactex}).  We
-recommend using the native Mac\TeX\ installer instead of the \TL\
+As mentioned in section~\ref{sec:tl-coll-dists}, a separate distribution
+is prepared for \MacOSX, named Mac\TeX\ (\url{http://tug.org/mactex}).
+We recommend using the native Mac\TeX\ installer instead of the \TL\
 installer on \MacOSX, because the native installer can make a few
 Mac-specific adjustments, in particular to allow easily switching
 between the various \TeX\ distributions for \MacOSX\ (Mac\TeX, gw\TeX,
@@ -1030,23 +1029,42 @@ or, for [t]csh:
 setenv TEXMFCNF /usr/local/texlive/2008/texmf-var/web2c
 \end{sverbatim}
 
+
 \subsubsection{\ConTeXt{} Mark IV}
 
 The `old' \ConTeXt{} should run out of the box. The new `Mark IV'
 \ConTeXt{} will require manual setup; see
 \url{http://wiki.contextgarden.net/Running_Mark_IV}.
 
+
 \subsubsection{Integrating local and personal macros}
+\label{sec:local-personal-macros}
 
 This is already mentioned implicitly in section~\ref{sec:texmftrees}:
 \dirname{TEXMFLOCAL} (by default,
-\dirname{/usr/local/texlive/texmf-local} or 
+\dirname{/usr/local/texlive/texmf-local} or
 \verb|C:\Program Files\texlive\texmf-local|)
+
 is intended for system-wide local fonts and macros; and
 \dirname{TEXMFHOME} (by default, \dirname{$HOME/texmf} or
 \verb|%USERPROFILE%\texmf|), is for personal fonts and macros.  These
-directories should stick around from release to release.  Their content
-will be seen automatically by a new \TL{} release.
+directories are intended to stick around from release to release, and
+have their content seen automatically by a new \TL{} release.
+Therefore, it is best to refrain from changing the definition of
+\dirname{TEXMFLOCAL} to be too far away from the main \TL{} directory,
+or you will need to manually change future releases.
+
+For both trees, files should be placed in their proper subdirectories;
+see \url{http://tug.org/tds} or consult
+\filename{texmf/web2c/texmf.cnf}. For instance, a \LaTeX{} class file or
+package should be placed in \dirname{TEXMFLOCAL/tex/latex} or
+\dirname{TEXMFHOME/tex/latex}, or a subdirectory thereof.
+
+\dirname{TEXMFLOCAL} requires an up-to-date filename database, or files
+will not be found.  You can update it with the command
+\cmdname{mktexlsr} or use the `Reinit file database' button on the
+configuration tab of \prog{tlmgr} in \GUI\ mode.
+
 
 \subsubsection{Integrating third-party fonts}
 
@@ -1100,7 +1118,7 @@ likely you have interference from old environment variables or
 configuration files; we recommend unsetting all \TeX-related environment
 variables for a start.  (For a deep analysis, you can ask \TeX{} to
 report on exactly what it is searching for, and finding; see ``Debugging
-actions'' on page~\pageref{Debugging}.)
+actions'' on page~\pageref{sec:debugging}.)
 
 \item Preview the result online:
 \begin{alltt}
@@ -1160,13 +1178,11 @@ If you are new to \TeX{}, or otherwise need help with actually writing
 \section{Network installations}
 \label{sec:netinstall}
 
-\TL{} has been designed to be shared between different users, and
-even different systems on a network. With a standard directory
-layout, no hard paths are configured: the locations for files needed
-by \TL{} programs are defined relative to the places of those
-programs. This is true even if \dirname{$TEXMFLOCAL} is on the same
-level as the other trees instead of one level higher. You can see
-this at work in the configuration file
+\TL{} has been designed to be shared between different users, and even
+different systems on a network. With a standard directory layout, no
+hard paths are configured: the locations for files needed by \TL{}
+programs are defined relative to the places of those programs.  You can
+see this at work in the configuration file
 \filename{$TEXMFMAIN/web2c/texmf.cnf}, which contains lines such as
 \begin{sverbatim}
 TEXMFMAIN = $SELFAUTOPARENT/texmf
@@ -1608,8 +1624,8 @@ colon (\samp{:}) and slash (\samp{/}).
 
 To check a particular path element \var{p}, \KPS{} first checks if a
 prebuilt database (see ``Filename data\-base'' on
-page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
-is in a directory that is a prefix of \var{p}.  If so, the path
+page~\pageref{sec:filename-database}) applies to \var{p}, i.e., if the
+database is in a directory that is a prefix of \var{p}.  If so, the path
 specification is matched against the contents of the database.
 
 If the database does not exist, or does not apply to this path
@@ -1652,7 +1668,7 @@ relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
 \fi
 
 \subsubsection{Path sources}
-\label{Path-sources}
+\label{sec:path-sources}
 
 A search path can come from many sources.  In the order in which
 \KPS{} uses them:
@@ -1670,9 +1686,9 @@ A search path can come from many sources.  In the order in which
   \samp{TEXINPUTS=/c:/d} (see below).
 \item The compile-time default.
 \end{enumerate}
-\noindent You can see each of these values for a given
-search path by using the debugging options (see ``Debugging actions''
-on page~\pageref{Debugging}).
+\noindent You can see each of these values for a given search path by
+using the debugging options (see ``Debugging actions'' on
+page~\pageref{sec:debugging}).
 
 \subsubsection{Config files}
 
@@ -1733,7 +1749,7 @@ shown in Figure~\ref{fig:config-sample}.
 \fi
 
 \subsubsection{Path expansion}
-\label{Path-expansion}
+\label{sec:path-expansion}
 
 
 \KPS{} recognizes certain special characters and constructions in
@@ -1745,11 +1761,11 @@ directory that contain a directory or file \file{baz}.  These
 expansions are explained in the sections below.
 %$
 \subsubsection{Default expansion}
-\label{Default-expansion}
+\label{sec:default-expansion}
 
 \tolerance=2500
 If the highest-priority search path (see ``Path sources'' on
-page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
+page~\pageref{sec:path-sources}) contains an \emph{extra colon} (i.e.,
 leading, trailing, or doubled), \KPS{} inserts at that point the
 next-highest-prio\-rity search path that is defined.  If that inserted
 path has an extra colon, the same happens with the next highest.  For
@@ -1803,7 +1819,7 @@ variable in all definitions, one is sure to always search the
 up-to-date tree first.
 
 \subsubsection{Subdirectory expansion}
-\label{Subdirectory-expansion}
+\label{sec:subdirectory-expansion}
 
 Two or more consecutive slashes in a path element following a directory
 \var{d} is replaced by all subdirectories of \var{d}: first those
@@ -1843,7 +1859,7 @@ configuration files.
 
 
 \subsection{Filename databases}
-\label{Filename-database}
+\label{sec:filename-database}
 
 \KPS{} goes to some lengths to minimize disk accesses for searches.
 Nevertheless, at installations with enough directories, searching each
@@ -1858,7 +1874,7 @@ names to the files listed in \file{ls-R}.  This can be helpful to
 confirm to \acro{DOS} 8.3 filename conventions in source files.
 
 \subsubsection{The filename database}
-\label{ls-R}
+\label{sec:ls-R}
 
 As explained above, the name of the main filename database must be
 \file{ls-R}.  You can put one at the root of each \TeX{} hierarchy in
@@ -1886,7 +1902,7 @@ element, never the disk.
 
 
 \subsubsection{kpsewhich: Standalone path searching}
-\label{Invoking-kpsewhich}
+\label{sec:invoking-kpsewhich}
 
 The \texttt{kpsewhich} program exercises path searching independent of any
 particular application.  This can be useful as a sort of \code{find}
@@ -1947,7 +1963,7 @@ The more important options are described next.
 
 
 \subsubsection{Examples of use}
-\label{SExamplesofuse}
+\label{sec:examples-of-use}
 
 Let us now have a look at \KPS{} in action.  Here's a straightforward search:
 
@@ -2066,7 +2082,7 @@ that the wrong version of a file is picked up somehow, since
 \cmdname{kpsewhich} will show you the first file encountered.
 
 \subsubsection{Debugging actions}
-\label{Debugging}
+\label{sec:debugging}
 
 Sometimes it is necessary to investigate how a program resolves file
 references. To make this practical, \KPS{} offers various levels of
@@ -2163,7 +2179,7 @@ names of the fonts.
 \cmdname{dvips} thus goes on to find all these files, plus the generic
 map file \file{psfonts.map}, which is always loaded (it contains
 declarations for commonly used \PS{} fonts; see the last part of
-Section \ref{SExamplesofuse} for more details about \PS{} map
+Section \ref{sec:examples-of-use} for more details about \PS{} map
 file handling).
 
 At this point \cmdname{dvips} identifies itself to the user:
@@ -2766,7 +2782,7 @@ latex --translate-file=empty.tcx yourfile.tex
 
 
 \subsection{Present}
-\label{tlcurrent}
+\label{sec:tlcurrent}
 
 In 2006--2007, the major new addition to \TL{} was the \XeTeX{} program,
 available as the \texttt{xetex} and \texttt{xelatex} programs; see