Texdoc version 0.42.

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

4 files changed, 126 insertions, 72 deletions

diff --git a/Master/texmf/doc/man/man1/texdoc.1 b/Master/texmf/doc/man/man1/texdoc.1
index e814337e00c..96ab325f496 100644
--- a/Master/texmf/doc/man/man1/texdoc.1
+++ b/Master/texmf/doc/man/man1/texdoc.1
@@ -1,17 +1,14 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.36.
-.TH TEXDOC "1" "September 2008" "texdoc version: 0.4" "User Commands"
+.TH TEXDOC "1" "April 2009" "texdoc 0.42" "User Commands"
 .SH NAME
-texdoc \- manual page for texdoc version: 0.4
+texdoc \- finding & viewing TeX documentation
 .SH SYNOPSIS
 .B texdoc
-\fI-h, --help | -v, --version | -f, --files | \fR[\fIoption(s)\fR] \fIname(s)\fR
+[\fIOPTIONS\fR]... [\fINAME\fR]...
 .SH DESCRIPTION
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show this short help.
-.TP
-\fB\-v\fR, \fB\-\-version\fR
-Print the version of the program.
+texdoc tries to find appropriate TeX documentation for the specified NAME(s).
+With no NAME, it can print configuration information (\fB\-f\fR, \fB\-\-files\fR);
+the usual \fB\-\-help\fR and \fB\-\-version\fR options are also accepted.
 .TP
 \fB\-f\fR, \fB\-\-files\fR
 Print the name of the config files being used.
@@ -46,8 +43,11 @@ Use interactive menus.
 \fB\-I\fR, \fB\-\-nointeract\fR
 Use plain lists, no interaction required.
 .TP
-\fB\-n\fR, \fB\-\-noise\-level\fR=\fIN\fR
+\fB\-v\fR, \fB\-\-verbosity\fR=\fIN\fR
 Set verbosity level to N.
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+Set verbosity level to maximum.
 .SS "Environment:"
 .IP
 PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
@@ -57,5 +57,6 @@ PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
 .SS "Homepage:"
 .IP
 http://tug.org/texdoc/
-.PP
-The full manual is accessed via `texdoc texdoc'.
+.SS "Manual:"
+.IP
+displayed by `texdoc texdoc'.
diff --git a/Master/texmf/doc/man/man1/texdoc.pdf b/Master/texmf/doc/man/man1/texdoc.pdf
index 92222ab40c4..996ff813ef8 100644
--- a/Master/texmf/doc/man/man1/texdoc.pdf
+++ b/Master/texmf/doc/man/man1/texdoc.pdf
diff --git a/Master/texmf/doc/texdoc/texdoc.pdf b/Master/texmf/doc/texdoc/texdoc.pdf
index 101d08f5ac9..60543cbda06 100644
--- a/Master/texmf/doc/texdoc/texdoc.pdf
+++ b/Master/texmf/doc/texdoc/texdoc.pdf
diff --git a/Master/texmf/doc/texdoc/texdoc.tex b/Master/texmf/doc/texdoc/texdoc.tex
index c83ed8bebc3..ed521cf88ba 100644
--- a/Master/texmf/doc/texdoc/texdoc.tex
+++ b/Master/texmf/doc/texdoc/texdoc.tex
@@ -1,19 +1,27 @@
 % this is texdoc's user manual
-% written by Manuel Pégourié-Gonnard in 2008
-% licensed under the WTFPL version 2 
+% written by Manuel Pégourié-Gonnard in 2008, 2009
+% distributed under the terms of GPL v3 or later
 
 \documentclass[a4paper, oneside]{scrartcl}
 \usepackage[latin1]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage{textcomp}
 \usepackage{fixltx2e}
-\usepackage{lmodern}
+
+\usepackage{lmodern} \edef\ttmodern{\ttdefault}
+\usepackage[osf]{mathpazo}
+\renewcommand\sfdefault{uop} % optima
+\renewcommand\ttdefault{lmvtt} % lm tt proportional
+\renewcommand\familydefault{\sfdefault}
+\newcommand\otherfamily{\rmfamily}
+\newcommand\mylangle{\textlangle}
+\newcommand\myrangle{\textrangle}
 
 \usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}
 
 \usepackage[rm, bf]{titlesec}
 \titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
-\titleformat{\subsubsection}[runin]{\itshape}{%
+\titleformat{\subsubsection}[runin]{\otherfamily\itshape}{%
   \makebox[0pt][r]{\thetitle\kern1pc}}{%
   0pt}{}[\maybedot\space --- ]
 
@@ -55,7 +63,7 @@
 \newcommand\inputcolorname{red}
 \hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
 \newcommand\textpa[1]{% % noms d'extensions (package)
-  {\normalfont\color{special}\sffamily #1}}
+  {\normalfont\color{special}\otherfamily #1}}
 \newcommand\cofont{% % code
   \color{code}\normalfont\ttfamily}
 \newcommand\textco[1]{{\cofont#1}}
@@ -73,7 +81,7 @@
 \catcode`\ 10\relax
 
 \newcommand\meta[1]{% % variantes à remplacer
-  {\color{special}\textlangle\textme{#1}\textrangle}}
+  {\color{special}\mylangle\textme{#1}\myrangle}}
 \newcommand\commandline[1]{%
   \prompt\space \textcolor{input}{#1}}
 \newcommand\prompt{\ding{229}}
@@ -105,10 +113,10 @@
   \xdef\sectioncmd{\noexpand\nodotthistime
     \thecmd[\bmtext]{%
       \ifframed
-        \unexpanded{\normalsize
+        \unexpanded{\normalsize\normalfont
           \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
       \else
-        \unexpanded{\normalsize
+        \unexpanded{\normalsize\normalfont
           \BUseVerbatim{verbmat}}%
       \fi
       \noexpand\label{\thelabel}}}%
@@ -149,13 +157,8 @@
 \subtitle{Finding \& viewing \TeX documentation
   }
 \author{\url{http://tug.org/texdoc/}\\
-  Manuel Pégourié-Gonnard\thanks{%
-    for the documentation.  The script itself was last updated and revised by
-    Manuel Pégourié-Gonnard with contributions from Reinhard Kotucha, based on
-    the previous texlua versions by Frank Küster.  Original (bash) shell
-    script by Thomas Esser, David Aspinall, and Simon Wilkinson.}
-  }
-\date{v0.4---2008/08/01}
+  Manuel Pégourié-Gonnard}
+\date{v0.42---2009/04/09}
 
 \begin{document}
 \VerbatimFootnotes
@@ -197,8 +200,13 @@ In this case, what you actually type is in \textcolor{input}{\inputcolorname},
 and the funny symbol \textco{\prompt} represents your shell's prompt, which
 can actually be something like ©C:\>© or ©name@host:~%© or funnier.
 
-Now, let's talk about this ©-s© option you've just seen in the previous
-example. 
+\bigskip
+
+\texdoc's normal mode of operation is to find the more appropriate document
+for your request and open it. But sometimes it has a weird notion of
+``appropriate'', and you'd better look at the list of all results and choose
+to see oen or more of them. For this, \texdoc offers various modes, like the
+``search mode'' illustrated above.
 
 \begin{cmdsubsec}{Search mode}{ss-search}
   texdoc -s «name» 
@@ -228,7 +236,7 @@ which you might want to read, whereas in normal mode \texdoc offers you no
 choice and just displays the user manual ©babelbib.pdf©.  On the other hand,
 the view mode is much faster when you know exactly what you want to read.
 
-To try and make you happy, \texdoc offers three other modes, introduced below.
+To try and make you happy, \texdoc offers two other modes, introduced below.
 
 \begin{cmdsubsec}{List mode}{ss-list}
   texdoc -l «name»
@@ -259,7 +267,7 @@ documented source code\dots
 
 As the name says, \emph{mixed mode} is an attempt to provide you the best of
 the normal (view) and list modes, by mixing them in the following way:  If
-only one file is found, the \texdoc opens it, and if many are found, it
+only one file is found, then \texdoc opens it, and if many are found, it
 displays a menu to let you choose.  You may want to make this mode the
 default, see~\ref{cf-mode}.
 
@@ -315,8 +323,8 @@ The concept of alias is very\footnote{See~\ref{ss-alias-rem} for why it is
 when you type and ©geometry© is aliased to ©geometry/manual.pdf©, then
 everything happens as if you actually typed ©texdoc geometry/manual.pdf©
 (without any further alias substitution), and \texdoc informs you that
-something happened so you can understand the results (see~\ref{cf-noise_level}
-to get rid of this message):
+something happened so you can understand the results
+(see~\ref{cf-verbosity_level} to get rid of this message):
 
 \begin{cmdsubsec}{Command line options}{ss-alias-cl}
   texdoc -a «options» «name»
@@ -328,8 +336,9 @@ to get rid of this message):
 By default, aliased are used in view, list and mixed modes, and disabled in
 search mode. But you may want to disable it, because the default alias doesn't
 do what you want\footnote{In this case, please report it to
-  \mailto{texlive@tug.org}.} or for another reason.  In this case, you just
-have to add ©-A© or ©--noalias© to the options, like:
+  \mailto{texdoc@tug.org}, so that the faulty alias can be updated.} or for
+another reason.  In this case, you just have to add ©-A© or ©--noalias© to the
+options, like:
 
 \begin{htcode}
   þ texdoc -A -l geometry þ
@@ -385,10 +394,11 @@ If you want to use another viewer, you have two ways of telling this to
 \texdoc: in your configuration file or using environment variables.  If you
 hesitate, the configuration file is the recommended way.
 
-To find you configuration file, type ©texdoc -f© and pick the file mark with a
-star (unless you are a system administrator or your home is shred between many
-machines, see~\ref{ss-prec}); you may need to create the file and a few
-directories. Then you can add lines like:
+To find your configuration file, type ©texdoc -f© and pick the file marked
+with a star (unless you are a system administrator or your home is shared
+between many machines whith different architectures, see~\ref{ss-prec}); you
+may need to create the file and a few directories. Then you can add lines
+like:
 
 \begin{htcode}
   viewer_pdf = (xpdf %s) &
@@ -408,8 +418,8 @@ See~\ref{cf-ext_list} for how to allow for more extensions.
 The corresponding environment variables are ©PDFVIEWER©, ©BROWSER©, ©PAGER©,
 ©DVIVIEWER©, ©PSVIEWER©. They follow the same convention as values from the
 configuration files, and override them if they are set. Since some of those
-variable are shared by other programs, you can override them by adding
-©_texdoc© at the end, like in ©BROWSER_texdoc©.
+variable are shared by other programs, you can override them just for \texdoc
+by adding ©_texdoc© at the end, like in ©BROWSER_texdoc©.
 
 \section{Full reference}\label{s-ref}
 
@@ -427,22 +437,26 @@ in the following order, where first value found is always used:
   \item Other environment variables.
   \item Values from configuration files, read in the following order:
     \begin{enumerate}
-      \item ©$TEXMFHOME/texdoc/texdoc-«platform».cnf©
-      \item ©$TEXMFHOME/texdoc/texdoc.cnf©
-      \item ©$TEXMFLOCAL/texdoc/texdoc-«platform».cnf©
-      \item ©$TEXMFLOCAL/texdoc/texdoc.cnf©
-      \item ©$TEXMFMAIN/texdoc/texdoc.cnf© %stopzone
+      \item ©TEXMFHOME/texdoc/texdoc-«platform».cnf©
+      \item ©TEXMFHOME/texdoc/texdoc.cnf©
+      \item ©TEXMFHOME/texdoc/texdoc-dist.cnf©
+      \item ©TEXMFLOCAL/texdoc/texdoc-«platform».cnf©
+      \item ©TEXMFLOCAL/texdoc/texdoc.cnf©
+      \item ©TEXMFMAIN/texdoc/texdoc.cnf©
     \end{enumerate}
   \item Hard-coded defaults that may depend on the current platform or the
     current value of another setting.
 \end{enumerate}
 
-For the configuration files, ©«platform»© stand for the name of the current
+For the configuration files, ©«platform»© stands for the name of the current
 platform, with names matching those of the directories in ©TEXLIVEROOT/bin©,
 and ©TEXMFHOME© and others are the kpse's values, see the kpathsea and web2c
 manuals. The name with ©«platform»© can be used on installation shared between
 many machines where, for example, not the same viewers are available. However,
-their use is not recommended in other situations.
+their use is not recommended in other situations. Finally, the special file
+©texdoc-dist.cnf© allows you to install a newer version of \texdoc (including
+its default config file) in your home: see \href{http://tug.org/texdoc/}{the
+  web page} for instructions on running \texdoc from the SVN.
 
 \subsection{Command-line options}\label{ss-cl}
 
@@ -457,8 +471,8 @@ corresponding configuration option.
 Shows a quick help message (namely a list of command-line options) and exits
 successfully.
 
-\begin{cmdsubsub}{-v, --version}{cl-v}
-  -v, --version
+\begin{cmdsubsub}{-V, --version}{cl-v}
+  -V, --version
 \end{cmdsubsub}
 
 Show the current version of the program and exits successfully.
@@ -476,7 +490,7 @@ recommended file for user settings.
   -w, --view, -l, --list, -m, --mixed, -s, --search, -r, --regex
 \end{cmdsubsub}
 
-\leavevmode\par\noindent See \ref{cf-mode}.
+See~\ref{cf-mode}.
 
 \begin{cmdsubsub}{-a, -A, --alias, --noalias}{cl-a}
   -a, --alias, -A, --noalias
@@ -500,27 +514,30 @@ shell's convention) not between the ©-e© or ©--extension© option, the equal
 sign, and the list.  Also take care to quote the special value ©*© if
 necessary.  The equal sign is optional.
 
-\begin{cmdsubsub}{-n, --noise-level}{cl-n}
-  -n=«n», --noise-level=«n»
+\begin{cmdsubsub}{-v, --verbosity, -d, --debug}{cl-n}
+  -v=«n», --verbosity=«n», -d, --debug
 \end{cmdsubsub}
 
-See~\ref{cf-noise_level} and be aware that you must avoid spaces on the command
-line, and the ©=© sign is optional.
+See~\ref{cf-verbosity_level} and be aware that you must avoid spaces on the
+command line, and the ©=© sign is optional. The ©--debug© option sets
+verbosity at the maximum level.
 
 \subsection{Environment variables}\label{ss-envvar}
 
 They all correspond to some ©viewer_«ext»© setting, and the reader is referred
-to~\ref{s-viewer} and~\ref{cf-viewer_*} for details. Here is the (obvious)
-correspondence:
+to~\ref{s-viewer} and~\ref{cf-viewer_*} for details. Also, environment
+variables used by older versions of \texdoc are accepted. You can append
+©_texdoc© to every name in the first column: this wins over every other name.
 
 \begin{center}
-\begin{tabular}{lll}
-  ©PAGER_texdoc©        & ©PAGER©       & ©viewer_html© \\
-  ©BROWSER_texdoc©      & ©BROWSER©     & ©viewer_txt©  \\
-  ©DVIVIEWER_texdoc©    & ©DVIVIEWER©   & ©viewer_dvi©  \\
-  ©PSVIEWER_texdoc©     & ©PSVIEWER©    & ©viewer_ps©   \\
-  ©PDFVIEWER_texdoc©    & ©PDFVIEWER©   & ©viewer_pdf©  \\
-\end{tabular}
+  \begin{tabular}{@{}l*3{@{ }l}@{}}
+    New name    & Old name 1        & Old name 2           & Config. param.\\
+    ©PAGER©     & ©TEXDOCVIEW_txt©  & ©TEXDOC_VIEWER_TXT©  & ©viewer_txt©  \\
+    ©BROWSER©   & ©TEXDOCVIEW_html© & ©TEXDOC_VIEWER_HTML© & ©viewer_html© \\
+    ©DVIVIEWER© & ©TEXDOCVIEW_dvi©  & ©TEXDOC_VIEWER_DVI©  & ©viewer_dvi©  \\
+    ©PSVIEWER©  & ©TEXDOCVIEW_ps©   & ©TEXDOC_VIEWER_PS©   & ©viewer_ps©   \\
+    ©PDFVIEWER© & ©TEXDOCVIEW_pdf©  & ©TEXDOC_VIEWER_PDF©  & ©viewer_pdf©  \\
+  \end{tabular}
 \end{center}
 
 \subsection{Configuration files}\label{ss-conf}
@@ -583,7 +600,7 @@ use\footnote{The quotes in the example are just to make the shell happy.}
   interact_switch = «true, false»
 \end{cmdsubsub}
 
-Turn on or of interaction.  Default is on.  Turning interaction off prevents
+Turn on or off interaction.  Default is on.  Turning interaction off prevents
 \texdoc to ask you to choose a file to view when there are multiple choices,
 and merely just print the list of files found.
 
@@ -641,8 +658,8 @@ shell construct.
 
 Everything has already been said in section~\ref{s-alias}.
 
-\begin{cmdsubsub}{noise_level}{cf-noise_level}
-  noise_level = «n»
+\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
+  verbosity_level = «n»
 \end{cmdsubsub}
 
 Set the verbosity level to ©«n»©.  This determines whether \texdoc will print
@@ -653,12 +670,20 @@ numeric codes are as follow:
   \item Print only error messages.
   \item Also print warnings.
   \item Also print information messages.
-  \item Also print debug1 information messages.
+  \item[n] Also print debug(n-3) information messages.
 \end{enumerate}
 
-Currently, the levels 5 and greater are not used, and the only ``debug''
-information at level 4 is to print the command used to view a file just before
-executing it.
+Currently, debug goes from 1 to 3 : ©debug1© prints the command used to view a
+file just before executing it, ©debug2© prints information about setting
+configuration paramters, and ©debug3© about the search paths used.
+
+\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch}
+  lastfile_switch = «true, false»
+\end{cmdsubsub}
+
+Prevents \texdoc from reading any other configuration file after this one.
+Mainly useful for installing a newer version of \texdoc in your home (see the
+\href{http://tug.org/texdoc/}{web site} for instructions on how to do so).
 
 \subsection{Exit codes}\label{ss-exit}
 
@@ -699,8 +724,36 @@ GUI version of \texdoc, and is unmaintained and probably unmaintainable
 anyway).  This is on the list, but the time line is rather unclear at the
 moment.
 
+\section{Licence}\label{s-licence}
+
+The current \texdoc program and its documentation are copyright 2008, 2009
+Manuel Pégourié-Gonnard.
+
+They are free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but
+\emph{without any warranty}; without even the implied warranty of
+\emph{merchantability} or \emph{fitness for a particular purpose}.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program.  If not, see \url{http://www.gnu.org/licenses/}.
+
+\bigskip
+
+Previous work (texdoc program) in the public domain:
+\begin{itemize}
+  \item Contributions from Reinhard Kotucha (2008).
+  \item First texlua versions by Frank Küster (2007).
+  \item Original shell script by Thomas Esser, David Aspinall, and Simon
+	Wilkinson.
+\end{itemize}
+
 \bigskip
-\begin{center}\Large
+\begin{center}\Large\rmfamily
   Happy \TeX{}ing!
 \end{center}