Texdoc version 0.42.

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

6 files changed, 530 insertions, 353 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}
 
diff --git a/Master/texmf/scripts/texdoc/texdoc.tlu b/Master/texmf/scripts/texdoc/texdoc.tlu
index defad83abb8..2f5969af8ed 100755
--- a/Master/texmf/scripts/texdoc/texdoc.tlu
+++ b/Master/texmf/scripts/texdoc/texdoc.tlu
@@ -1,89 +1,109 @@
 #!/usr/bin/env texlua
 -- $Id$ -*-Lua-*-
---[[Revised 2008 by Manuel Pégourié-Gonnard 
-    with contributions from Reinhard Kotucha.
-    First texlua versions by Frank Küster (2007). 
-    Origial shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
-    Public domain.]]
---[[ Changelog
-  0.4 2008-07
-  - moved configuration from texmf.cnf to texdoc.cnf
-  - added an 'alias' feature
-  - new modes 'mixed' and 'regex'
-  - file lists are now menus (select number to view results)
-  - changed the search modes to get only the more relevant results (hopefully)
-  - /!\ zip support disabled by default (not portable) (see comments below)
-
-  0.3 2007-06-28
-  - added changelog
-  - better OS detection for default viewer settings
-  - removed some debugging code
-  - -s now works in dirs without ls-R, too
-  
-  0.2 2007-06-28
-  - implemented reading of configuration from texmf.cnf
-  - fixed "-s" option
-  
-  0.1
-  - initial public release 
-]]
-
--- some constants 
+--[[
+Copyright 2008, 2009 Manuel Pégourié-Gonnard.
+
+This program is 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 WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or 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 <http://www.gnu.org/licenses/>.
+
+Previous work in the public domain:
+- Contributions from Reinhard Kotucha (2008).
+- First texlua versions by Frank Küster (2007).
+- Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
+--]]
+
+--------------------------------------------------------------------------------
+------------------   global constants and general functions   ------------------
+--------------------------------------------------------------------------------
+
+-----------------------------   global constants   -----------------------------
+
+-- progname and version
 progname = 'texdoc'
-version = '0.4'
--- make sure to update setup_config_from_cl() accordingly
+version = '0.42'
+if string.sub(version, -1) == '+' then
+    local svnrev = string.match('$Rev: 44 $', '%$Rev:%s*(%d*)%s*%$');
+    version = version..' svn r'..svnrev
+end
+
+-- make sure to update setup_config_from_cl() accordingly 
 -- and set a default value in setup_config_from_defaults() if relevant
 usage_msg = [[
-Usage:  texdoc  -h, --help | -v, --version | -f, --files | [option(s)] name(s)
-    -h, --help              Show this short help.
-    -v, --version           Print the version of the program.
-    -f, --files             Print the name of the config files being used.
-    -e, --extensions=L      Require file extensions to be in the list L.
-    -w, --view              Use view mode: start a viewer.
-    -m, --mixed             Use mixed mode (view or list).
-    -l, --list              Use list mode: don't start a viewer.
-    -s, --search            Search for name as a substring.
-    -r, --regex             Search for name as a lua regex.
-    -a, --alias             Use the alias table.
-    -A, --noalias           Don't use the alias table.
-    -i, --interact          Use interactive menus.
-    -I, --nointeract        Use plain lists, no interaction required.
-    -n, --noise-level=N     Set verbosity level to N.
-Environment: 
-    PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
-Files: 
-    <texmf>/texdoc/texdoc.cnf files, see the -f option.
-Homepage: 
-    http://tug.org/texdoc/
-The full manual is accessed via `texdoc texdoc'.]]
+texdoc tries to find appropriate TeX documentation for the specified NAME(s).
+With no NAME, it can print configuration information (-f, --files);
+the usual --help and --version options are also accepted.
+Usage: texdoc [OPTIONS]... [NAME]...
+  -f, --files           Print the name of the config files being used.
+  -e, --extensions=L    Require file extensions to be in the list L.
+  -w, --view            Use view mode: start a viewer.
+  -m, --mixed           Use mixed mode (view or list).
+  -l, --list            Use list mode: don't start a viewer.
+  -s, --search          Search for name as a substring.
+  -r, --regex           Search for name as a lua regex.
+  -a, --alias           Use the alias table.
+  -A, --noalias         Don't use the alias table.
+  -i, --interact        Use interactive menus.
+  -I, --nointeract      Use plain lists, no interaction required.
+  -v, --verbosity=N     Set verbosity level to N.
+  -d, --debug           Set verbosity level to maximum.
+Environment: PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
+Files: <texmf>/texdoc/texdoc.cnf files, see the -f option.
+Homepage: http://tug.org/texdoc/
+Manual: displayed by `texdoc texdoc'.]]
+
+error_msg = [[
+Try `texdoc --help' for a short help, `texdoc texdoc' for the user manual.]]
 notfound_msg = [[
 Sorry, no documentation found for PKGNAME.
 If you are unsure about the name, try searching CTAN's TeX catalogue at
 http://ctan.org/search.html#byDescription.]]
-place_holder = '%%s' -- used for viewer commands
+
+known_options = {
+    'viewer_.*',
+    'mode',
+    'interact_switch', 'alias_switch',
+    'ext_list',
+    'verbosity_level',
+    'lastfile_switch',
+}
+
 err_priority = {
     error   = 1,
     warning = 2,
     info    = 3,
     debug1  = 4,
+    debug2  = 5,
+    debug3  = 6,
 }
+err_max = 6
+
+place_holder = '%%s' -- used for viewer commands
 
 -- zip/gz support
 --
 -- optionally, texdoc can support compressed documentation, but this is
 -- system-dependant (commands for unzipping, temporary files, etc).
 -- Since TeX Live doesn't ship compressed doc, downstream distributors who
--- want to ship zipped should change support_zipped to true *and* make sure
+-- want to ship zipped doc should change support_zipped to true *and* make sure
 -- everything  works for them (look for support_zipped in the code).
 -- If you use this feature, please let us know: if nobody uses it,
 -- we'll drop it at some point.
 support_zipped = false
 
+--------------------------   general-use functions   ---------------------------
 
--- BEGIN function definitions (till the 'END' mark)
----=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
--- a general-use function
+-- Remark: we always assume our tables have no hole (that is, no nil value
+-- followed by a non-nil value). So we use the simple iterator below, and 
+-- the # operator sometimes (a bit faster than table.getn).
 function list (t)
     local i = 0
     return function ()
@@ -92,66 +112,81 @@ function list (t)
     end
 end
 
--- Remark: we always assume our tables have no hole (that is, no nil value
--- followed by a non-nil value). So we use the simple iterator above, and 
--- the # operator sometimes (bit faster than table.getn).
+-- remove the 'abc/../' components in a path
+function simplify_path (path)
+    local res = string.gsub (path, '/[^/]+/%.%./', '/')
+    return res -- get rid of gsub's 2nd return value
+end
 
--- functions for the search options
------------------------------------
+-- change '/' to '\' on windows, removine 'abc/../' components first
+if os.type == "windows" then
+    function win32_hook (path)
+        local res = string.gsub (simplify_path(path), '/', '\\')
+        return res -- get rid of gsub's 2nd return value
+    end
+else
+    function win32_hook (path)
+        return simplify_path(path)
+    end
+end
+
+--------------------------------------------------------------------------------
+--------------------------   functions for searching   -------------------------
+--------------------------------------------------------------------------------
+
+------------------   exploring trees (kpse-style functions)   ------------------
 
--- BEGIN kpse-like
+-- global variables:
+-- texdocs: a Lua table version of $TEXDOCS
+-- do_recurse: do_recurse[i] = 1 iff texdocs[i] ends with // in $TEXDOCS
+-- must_have_lsr: must_have_lsr[i] = 1 iff texdocs[i] starts with !! in $TEXDOCS
+-- exact_docfiles: list of "exact matches"
+-- rel_docfiles: list of "non-exact matches"
 
--- get global texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
+-- set texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
 function get_texdocs ()
     local sep = (os.type == 'windows') and ';' or ':'
     texdocs = kpse.expand_var ("$TEXDOCS")
     -- expand the path and turn it into a lua list
     texdocs = string.explode (kpse.expand_braces (texdocs), sep)
     do_recurse, must_have_lsr = {}, {} -- global
+    err_print('Search paths:', 'debug3')
     for i, dir in ipairs (texdocs) do
         local n
         dir, n = string.gsub (dir, '//$', '')
         do_recurse[i] = (n == 1)
         texdocs[i], n = string.gsub (dir, '^!!', '')
         must_have_lsr[i] = (n == 1)
+        err_print(string.format('%s (do_recurse=%s, must_have_lsr=%s)',
+            texdocs[i],
+            do_recurse[i] and 'true' or 'false',
+            must_have_lsr[i] and 'true' or 'false'), 'debug3')
     end
 end
 
--- says if ext is 'good' according to ext_list
-function is_good_ext (ext)
-    for e in list (config.ext_list) do
-        if e == '*' then
-            return true 
-        elseif (e == '') and (not ext) then
-            return true
-        elseif ext == e then
-            return true
-        end
-    end
-    return false
-end
+-- once get_texdocs() is done, roots are represented by their index in texdocs
+-- usefull to avoid fake matches and also for the sort routine
+-- the next two functions do the conversions
 
--- include a file in the lists if it should be
-function process_file (file, pathfile, code, pattern)
-    local base, ext = string.match(file, '^(.*)%.(.*)$')
-    if string.find(pathfile, pattern, 1, no_regex) and is_good_ext (ext)
-        then 
-        if (base == pattern) or (file == pattern) then 
-            table.insert(exact_docfiles, code_path (code, pathfile))
-        else
-            table.insert(rel_docfiles, code_path (code, pathfile))
-        end
-    end
-end
-
--- encodes the base path on two digits and concatenate with filename
--- see real_path() for decoding
+-- encode the base path on two digits and concatenate with filename
 function code_path (code, file)
     local padding = (code > 9) and '' or '0'
     return padding..code..':'..file
 end
 
--- scan a tree
+-- decode a path as given in *_docfiles into a real path
+function real_path (fake)
+    local code, file = string.match (fake, '^(.-):(.*)$')
+    code = tonumber (code)
+    return win32_hook (texdocs[code]..'/'..file)
+end
+
+-- merge two components of a path, taking care of empty components
+function merge_path (a, b)
+    return ((a == '') or (b == '')) and a..b or a..'/'..b
+end
+
+-- scan a tree without ls-R file
 function scan_tree (code, path, pattern, recurse)
     for file in lfs.dir(path) do
         if file ~= '.' and file ~= '..' then
@@ -165,7 +200,7 @@ function scan_tree (code, path, pattern, recurse)
     end
 end
 
--- finds a root with ls-R above path and return it or nil
+-- finds a ls-R file in a parent directory an return it or nil
 function lsr_root (path)
     if not lfs.isdir (path) then return end
     local root, shift = path, ''
@@ -181,11 +216,6 @@ function lsr_root (path)
     end
 end
 
--- merge two components of a path, taking care of empty components
-function merge_path (a, b)
-    return ((a == '') or (b == '')) and a..b or a..'/'..b
-end
-
 -- scan a ls-R file
 function scan_lsr (code, shift, pattern)
     local isdoc = false
@@ -215,8 +245,18 @@ function scan_lsr (code, shift, pattern)
     lsr:close()
 end
 
--- find dirfiles according to pattern
+-- remove directories from a list
+function rmdirs (files)
+    local res = {}
+    for f in list (files) do
+        if not is_dir[f] then table.insert(res, f) end
+    end
+    return res
+end
+
+-- find docfiles "matching" pattern
 function populate_docfiles (pattern)
+    pattern = normalize_pattern(pattern)
     if not texdocs then get_texdocs() end
     rel_docfiles, exact_docfiles = {}, {} -- global
     is_dir = {} -- global; is_dir[path] = true iff path is a dir, see scan_lsr
@@ -236,8 +276,6 @@ function populate_docfiles (pattern)
     rel_docfiles = rmdirs (rel_docfiles)
 end
 
--- END kpse-like
-
 -- like populate_docfiles, but rel replaces exact if exact is empty
 function mixed_populate_docfiles (pattern)
     populate_docfiles (pattern)
@@ -249,99 +287,149 @@ function mixed_populate_docfiles (pattern)
     end
 end
 
--- translate a path as given by populate_docfiles into a real path
--- should never be called before get_texdocs()
-function real_path (fake)
-    local code, file = string.match (fake, '^(.-):(.*)$')
-    code = tonumber (code)
-    return win32_hook (texdocs[code]..'/'..file)
+-- for sty files, we obviously don't want to look in TEXDOCS...
+-- and we don't need a list since those are not duplicated (ahem...)
+function populate_docfiles_sty (styname)
+    exact_docfiles = { kpse.find_file (styname) }
+    rel_docfiles = {}
 end
 
--- now a special function that does nothing on Unix
-if os.type == "windows" then
-    function win32_hook (path)
-        local res = string.gsub (path, '/', '\\')
-        return res -- get rid of gsub's 2nd arg
-    end
-else
-    function win32_hook (path)
-        return path
+----------------------------   selecting results   -----------------------------
+
+-- says if ext is 'good' according to ext_list
+function is_good_ext (ext)
+    for e in list (config.ext_list) do
+        if e == '*' then
+            return true 
+        elseif (e == '') and (not ext) then
+            return true
+        elseif ext == e then
+            return true
+        end
     end
+    return false
 end
 
--- remove directories from the files list
-function rmdirs (files)
-    local res = {}
-    for f in list (files) do
-        if not is_dir[f] then table.insert(res, f) end
+-- include a file in the *_docfiles lists if it "matches"
+function process_file (file, pathfile, code, pattern)
+    local base, ext = string.match(string.lower(file), '^(.*)%.(.*)$')
+    if string.find(string.lower(pathfile), pattern, 1, no_regex) 
+        and is_good_ext (ext) then 
+        if (base == pattern) or (file == pattern) then 
+            table.insert(exact_docfiles, code_path (code, pathfile))
+        else
+            table.insert(rel_docfiles, code_path (code, pathfile))
+        end
     end
-    return res
 end
 
--- for sty files, we obviously don't want to look in TEXDOCS...
--- and we don't need a list since those are not duplicated (ahem...)
-function populate_docfiles_sty (styname)
-    exact_docfiles = { kpse.find_file (styname) }
-    rel_docfiles = {}
+-- for now, just make lowercase, but may do more later
+function normalize_pattern (pattern)
+    return string.lower(pattern)
+end
+
+-----------------------------   sorting results   ------------------------------
+
+-- compare two filenames with the following rule:
+-- 1. extensions are ordered as in ext_list first,
+-- 2. then filenames lexicographically.
+function file_order (a, b)
+    local ext_a = string.match (a, '^.*%.(.*)$')
+    local ext_b = string.match (b, '^.*%.(.*)$')
+    ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
+    ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
+    if ext_pos_a < ext_pos_b then
+        return true
+    elseif ext_pos_a > ext_pos_b then
+        return false
+    else
+        return (a < b)
+    end
 end
 
+--------------------------------------------------------------------------------
+----------------   functions to set config values and aliases   ----------------
+--------------------------------------------------------------------------------
 
--- functions to set config values and aliases
----------------------------------------------
+----------------------------   general functions   -----------------------------
 
--- set a value without overwriting if already set and
--- using to special types: *_list and *_switch
-function set_config_element (key, value, file, line)
-    if config[key] == nil then -- must explicitly test for nil, not false
-        if string.match(key, '_list$') then
-            -- this is actually a coma-separated list of values
-            local values = string.explode(value, ',')
-            local inverse = {}
-            for i, j in ipairs(values) do
-                values[i] = string.gsub(j, '%s*$', '')
-                values[i] = string.gsub(j, '^%s*', '')
-                inverse[j] = i
-            end
-            config[key] = values
-            config[key..'_inv'] = inverse
-            config[key..'_max'] = #values
-        elseif string.find (key, '_switch$') then
-            if value == 'true' then
-                config[key] = true
-            elseif value == 'false' then
-                config[key] = false
-            else
-                config_warn (key, value, file, line)
-            end
-        elseif string.find (key, '_level$') then
-            local val = tonumber (value)
-            if val then 
-                config[key] = val
-            else
-                config_warn (key, value, file, line)
-            end
+-- set a config parameter, but don't overwrite it if already set
+-- three special types: *_list (list), *_switch (boolean), *_level (number)
+function set_config_element (key, value, context)
+    local is_known = false -- is key a valid option?
+    for option in list(known_options) do
+        if string.match(key, option) then is_known = true break end
+    end
+    -- warn and exit if key is not a known option
+    if not is_known then config_warn(key, nil, context) return end
+    -- exit if key is already set (/!\ must test for nil, not false)
+    if not (config[key] == nil) then return nil end
+    if string.match(key, '_list$') then -- coma-separated list
+        local values = string.explode(value, ',')
+        local inverse = {}
+        for i, j in ipairs(values) do -- sanitize values...
+            values[i] = string.gsub(j, '%s*$', '')
+            values[i] = string.gsub(j, '^%s*', '')
+            inverse[j] = i -- ... and build inverse mapping on the way
+        end
+        config[key] = values
+        config[key..'_inv'] = inverse
+        config[key..'_max'] = #values
+    elseif string.find (key, '_switch$') then -- boolean
+        if value == 'true' then
+            config[key] = true
+        elseif value == 'false' then
+            config[key] = false
+        else
+            config_warn (key, value, context)
+        end
+    elseif string.find (key, '_level$') then -- integer
+        local val = tonumber (value)
+        if val then 
+            config[key] = val
         else
-            config[key] = value
+            config_warn (key, value, context)
         end
+    else -- string
+        config[key] = value
+    end
+    -- special case: if we just set verbosity_level, print version info now
+    if key == 'verbosity_level' then
+        err_print(arg[0]..' version '..version, 'debug1')
     end
+    -- now tell what we have just done, for debugging
+    err_print('Setting "'..key..'='..value..'" '
+    ..context_to_string(context)..'.', 'debug2')
 end
 
 -- a helper  function for warning messages in the above
-function config_warn (key, value, file, line)
-    local begin = 'illegal value '..value..' for key '..key
+function config_warn (key, value, context)
+    local begin = value and 'Illegal value "'..value..'" for option "'..key..'"'
+    or 'Unkown option "'..key..'"'
     local ending = '.  Skipping.'
-    if file and line then
-        err_print (begin..'\nin '..file..' line '..line..ending, 'warning')
+    err_print (begin..'\n    '..context_to_string(context)..ending, 'warning')
+end
+
+-- interpreting 'context' for the previous functions
+function context_to_string(context)
+    if not context then return '(no context)' end
+    if      context.src == 'cl' then
+        return 'from command line option "'..context.name..'"'
+    elseif  context.src == 'env' then
+        return 'from environment variable "'..context.name..'"'
+    elseif  context.src == 'file' then
+        return 'in file "'..context.file..'" on line '..context.line
+    elseif  context.src == 'def' then
+        return 'from built-in defaults'
     else
-        err_print (begin..ending, 'warning')
+        return 'from unkown source (should not happen, please report)'
     end
 end
 
-
 -- set a whole list, also whithout overwriting
-function set_config_list (conf)
+function set_config_list (conf, context)
     for key, value in pairs(conf) do
-        set_config_element (key, value)
+        set_config_element (key, value, context)
     end
 end
 
@@ -352,89 +440,96 @@ function set_alias (key, value)
     end
 end
 
+------------------------   options from command line   -------------------------
+
 -- set config from the command line
 -- Please make sure to update usage_msg accordingly
 -- and set a default value in setup_config_from_defaults() if relevant.
+-- TODO: should use some getopt_long()-like mechanism some day
 function setup_config_from_cl ()
+    local curr_arg
+    local function set_config_elt(key, val) 
+        set_config_element(key, val, {src='cl', name=curr_arg})
+    end
     while arg[1] and string.match(arg[1],'^%-') do
         curr_arg = table.remove(arg,1)
         if (curr_arg == '-h') or (curr_arg == '--help') then
             print (usage_msg)
             os.exit(0)
-        elseif (curr_arg == '-v') or (curr_arg == '--version') then
-            print (progname .. ' version: ' .. version )
+        elseif (curr_arg == '-V') or (curr_arg == '--version') then
+            print (progname .. ' ' .. version )
             os.exit(0)
         elseif (curr_arg == '-f') or (curr_arg == '--files') then
-            print_config_files ()
+            print (progname .. ' ' .. version )
+            setup_config_from_files ()
+            show_config_files (print, true)
             os.exit(0)
         elseif (curr_arg == '-w') or (curr_arg == '--view') then
-            set_config_element('mode', 'view')
+            set_config_elt('mode', 'view')
         elseif (curr_arg == '-m') or (curr_arg == '--mixed') then
-            set_config_element('mode', 'mixed')
+            set_config_elt('mode', 'mixed')
         elseif (curr_arg == '-l') or (curr_arg == '--list') then
-            set_config_element('mode', 'list')
+            set_config_elt('mode', 'list')
         elseif (curr_arg == '-s') or (curr_arg == '--search') then
-            set_config_element ('mode', 'search')
+            set_config_element ('mode', 'search', {src='cl', name=curr_arg})
         elseif (curr_arg == '-r') or (curr_arg == '--regex') then
-            set_config_element ('mode', 'regex')
+            set_config_element ('mode', 'regex', {src='cl', name=curr_arg})
         elseif (curr_arg == '-I') or (curr_arg == '--nointeract') then
-            set_config_element('interact_switch', 'false')
+            set_config_elt('interact_switch', 'false')
         elseif (curr_arg == '-i') or (curr_arg == '--interact') then
-            set_config_element('interact_switch', 'true')
+            set_config_elt('interact_switch', 'true')
         elseif (curr_arg == '-A') or (curr_arg == '--noalias') then
-            set_config_element('alias_switch', 'false')
+            set_config_elt('alias_switch', 'false')
         elseif (curr_arg == '-a') or (curr_arg == '--alias') then
-            set_config_element('alias_switch', 'true')
-        elseif string.match(curr_arg, '^%-n') then 
-            set_config_element('noise_level', 
-            string.gsub(curr_arg, '^%-n=?', ''))
-        elseif string.match(curr_arg, '^%-%-noise%-level') then
-            set_config_element('noise_level', 
-            string.gsub(curr_arg, '^%-%-noise%-level=?', ''))
+            set_config_elt('alias_switch', 'true')
+        elseif (curr_arg == '-d') or (curr_arg == '--debug') then
+            set_config_elt('verbosity_level', err_max)
+        elseif string.match(curr_arg, '^%-v') then 
+            local value = string.gsub(curr_arg, '^%-v=?', '')
+            set_config_elt('verbosity_level', value)
+        elseif string.match(curr_arg, '^%-%-verbosity') then
+            local value = string.gsub(curr_arg, '^%-%-verbosity=?', '')
+            set_config_elt('verbosity_level', value)
         elseif string.match(curr_arg, '^%-e') then 
-            set_config_element('ext_list', 
-            string.gsub(curr_arg, '^%-e=?', ''))
+            local value = string.gsub(curr_arg, '^%-e=?', '')
+            set_config_elt('ext_list', value)
         elseif string.match(curr_arg, '^%-%-extensions') then
-            set_config_element('ext_list', 
-            string.gsub(curr_arg, '^%-%-extensions=?', ''))
+            local value = string.gsub(curr_arg, '^%-%-extensions=?', '')
+            set_config_elt('ext_list', value)
         else
-            err_print ("unknow option: "..curr_arg, "error")
-            print (usage_msg)
+            err_print ("unknown option: "..curr_arg, "error")
+            print (error_msg)
             os.exit(1)
         end
     end
 end
 
--- the default value af config.alias_switch depends on the mode as follows
-function alias_from_mode (mode)
-    if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then 
-        return 'true'
-    else
-        return 'false'
-    end
-end
+-------------------------   config from environment   --------------------------
 
 -- set config from environment if available
 function setup_config_from_env ()
-    set_config_list {
-        viewer_pdf  = os.getenv ("PDFVIEWER_texdoc") 
-        or os.getenv ("TEXDOCVIEW_pdf") or os.getenv ("TEXDOC_VIEWER_PDF")
-        or os.getenv ("PDFVIEWER"),
-        viewer_ps   = os.getenv ("PSVIEWER_texdoc")
-        or os.getenv ("TEXDOCVIEW_ps") or os.getenv ("TEXDOC_VIEWER_PS")
-        or os.getenv ("PSVIEWER"),
-        viewer_dvi  = os.getenv ("DVIVIEWER_texdoc")
-        or os.getenv ("TEXDOCVIEW_dvi") or os.getenv ("TEXDOC_VIEWER_DVI")
-        or os.getenv ("DVIVIEWER"),
-        viewer_html = os.getenv ("BROWSER_texdoc")
-        or os.getenv ("TEXDOCVIEW_html") or os.getenv ("TEXDOC_VIEWER_HTML")
-        or os.getenv ("BROWSER"),
-        viewer_txt  = os.getenv ("PAGER_texdoc")
-        or os.getenv ("TEXDOCVIEW_txt") or os.getenv ("TEXDOC_VIEWER_TXT")
-        or os.getenv ("PAGER"),
-    }
+    local function set_config_elt_from_vars(key, vars)
+        for var in list(vars) do
+            local value = os.getenv(var)
+            if value then
+                set_config_element(key, value, {src='env', name=var})
+            end
+        end
+    end
+    set_config_elt_from_vars('viewer_pdf',
+    {"PDFVIEWER_texdoc", "TEXDOCVIEW_pdf", "TEXDOC_VIEWER_PDF", "PDFVIEWER"})
+    set_config_elt_from_vars('viewer_ps',
+    {"PSVIEWER_texdoc", "TEXDOCVIEW_ps", "TEXDOC_VIEWER_PS", "PSVIEWER"})
+    set_config_elt_from_vars('viewer_dvi',
+    {"DVIVIEWER_texdoc", "TEXDOCVIEW_dvi", "TEXDOC_VIEWER_DVI", "DVIVIEWER"})
+    set_config_elt_from_vars('viewer_html',
+    {"BROWSER_texdoc", "TEXDOCVIEW_html", "TEXDOC_VIEWER_HTML", "BROWSER"})
+    set_config_elt_from_vars('viewer_txt',
+    {"PAGER_texdoc", "TEXDOCVIEW_txt", "TEXDOC_VIEWER_TXT", "PAGER"})
 end
 
+----------------------   options and aliases from files   ----------------------
+
 -- set config+aliases from a particular config file assumed to exist
 function read_config_file(configfile)
     local cnf = assert(io.open(configfile, 'r')) 
@@ -449,7 +544,8 @@ function read_config_file(configfile)
         line = string.gsub(line, '^%s*', '')    -- remove leading spaces
         key, val = string.match(line, '^([%a%d_]+)%s*=%s*(.+)')
         if key and val then 
-            set_config_element(key, val, configfile, lineno)
+            set_config_element(key, val, {
+                src='file', file=configfile, line=lineno})
         else
             key, val = string.match(line, '^alias%s+([%a%d_-]+)%s*=%s*(.+)')
             if key and val then
@@ -471,33 +567,54 @@ function get_config_files ()
     local TEXMFHOME  = kpse.var_value ('TEXMFHOME')
     local TEXMFLOCAL = kpse.var_value ('TEXMFLOCAL')
     local TEXMFMAIN  = kpse.var_value ('TEXMFMAIN')
-    local config_files = {}
     return {
         TEXMFHOME  .. '/texdoc/texdoc-'..platform..'.cnf',
         TEXMFHOME  .. '/texdoc/texdoc.cnf',
+        TEXMFHOME  .. '/texdoc/texdoc-dist.cnf',
         TEXMFLOCAL .. '/texdoc/texdoc-'..platform..'.cnf',
         TEXMFLOCAL .. '/texdoc/texdoc.cnf',
         TEXMFMAIN  .. '/texdoc/texdoc.cnf'
     } 
 end
 
+-- the config_files table is shared by the next two functions
+do
+local config_files = {}
+
 -- set config/aliases from all config files 
 function setup_config_from_files ()
-    for file in list (get_config_files ()) do
-        if lfs.isfile(file) then read_config_file (file) end
+    for i, file in ipairs (get_config_files ()) do
+        local found = lfs.isfile(file)
+        config_files[i] = {
+            path = file,
+            status = found and (config.lastfile_switch 
+            and 'disabled' or 'active') or 'absent',
+        }
+        if config_files[i].status == 'active' then
+            read_config_file (file) 
+        end
     end
 end
 
 -- now a special information function (see -f,--file option)
-function print_config_files ()
-    print "Configuration files are:"
-    for i, file in ipairs (get_config_files ()) do
-        local found = lfs.isfile(file) and "(active)" or "(not found)"
-        local home = (i==2) and "* " or "" -- home conffile is the 2nd
-        print (home..found, win32_hook(file))
+function show_config_files (print_fun, prefix)
+    print_fun("Configuration files are:")
+    for i, file in ipairs (config_files) do
+        local home = prefix and 
+        ((i==2) and "(*) " or "    ") -- home conffile is the 2nd
+        or ''
+        print_fun (home..file.status..'\t'..win32_hook(file.path))
+    end
+    if prefix then 
+        print("(*) This is the recommended configuration file "
+        .. "for your personal preferences.")
     end
 end
 
+end -- scope of config_files
+
+----------------------   options from built-in defaults   ----------------------
+
 -- for default viewer on general Unix, we have a list; the following two
 -- functions are used to check in the path which program is available
 
@@ -521,19 +638,23 @@ end
 
 -- set some fall-back default values if no previous value is set
 function setup_config_from_defaults()
+    local function set_config_ls(ls) set_config_list(ls, {src='def'}) end
+    local function set_config_elt(key, val) 
+        set_config_element(key, val, {src='def'}) 
+    end
     if (os.type == "windows") then
         -- probably Windows (or OS/2)
         -- which commands should we use for unzipping?
-        set_config_list {
+        set_config_ls {
             viewer_dvi    = 'start ""',
             viewer_html   = 'start ""',
             viewer_pdf    = 'start ""',
             viewer_ps     = 'start ""',
-            viewer_txt    = 'start ""',
+            viewer_txt    = 'start cmd /k more',
         }
     else -- since we don't support msdos, if os.type is not windows, it's unix
         if (os.name == 'macosx') then
-            set_config_list {
+            set_config_ls {
                 viewer_dvi    = 'open',
                 viewer_html   = 'open',
                 viewer_pdf    = 'open',
@@ -541,7 +662,7 @@ function setup_config_from_defaults()
                 viewer_txt    = 'less',
             }
         else
-            set_config_list {
+            set_config_ls {
                 viewer_dvi      = first_in_path {
                     {'evince',  '(evince %s) &'},
                     {'okular',  '(okular %s) &'},
@@ -583,33 +704,45 @@ function setup_config_from_defaults()
         end
     end
     -- then various stuff
-    set_config_list {
+    set_config_ls {
         mode                = 'view',
-        interact_switch  = 'true',
-        noise_level         = '3',
+        interact_switch     = 'true',
+        verbosity_level     = '3',
     }
     -- must be set after mode!
-    set_config_element ('alias_switch', alias_from_mode(config.mode))
+    set_config_elt ('alias_switch', alias_from_mode(config.mode))
     -- now a particular case for config.ext_list and zip-related stuff
     -- Note: removed texdoc_formats/zip_formats, gives simpler & generic code
     if support_zipped then
-        set_config_element('ext_list', 
+        set_config_elt('ext_list', 
         'pdf,pdf.gz,pdf.bz2, html,html.gz,html.bz2, txt,txt.gz,txt.bz2,'..
         'dvi,dvi.gz,dvi.bz2, ps,ps.gz,ps.bz2, ,gz,bz2')
-        set_config_list {
+        set_config_ls {
             unzip_gz    = 'gzip -d -c ',
             unzip_bz2   = 'bzip -d -c ',
             rm_file     = 'rm -f',
             rm_dir      = 'rmdir'
         }
     else
-        set_config_element('ext_list', 'pdf, html, txt, dvi, ps, ')
+        set_config_elt('ext_list', 'pdf, html, txt, dvi, ps, ')
+    end
+end
+
+-- the default value of config.alias_switch depends on the mode as follows
+function alias_from_mode (mode) -- /!\ returns a string!
+    if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then
+        return 'true'
+    else
+        return 'false'
     end
+
 end
 
+--------------------------------------------------------------------------------
+---------------   functions for viewing/displaying the results   ---------------
+--------------------------------------------------------------------------------
 
--- functions for viewing/displaying the results
------------------------------------------------
+---------------------------------   viewing   ----------------------------------
 
 -- prepare for viewing: set viewer_replacement and viewer_ext
 -- may uncompress if support_zipped is set (giving the complete filename on the
@@ -640,7 +773,7 @@ function how_to_view (filename)
         -- files without extension are assumed to be text
         viewext = string.match(filename,'.*%.(.*)$') or 'txt'
         if not config['viewer_'..viewext] then
-            err_print (": cannot determine type of file\n\t"
+            err_print ("cannot determine type of file\n\t"
             ..filename.."Assuming text.  Set the `viewer_"..viewext..
             "' variable in texdoc.cnf to avoid this.", "warning")
             viewext = 'txt'
@@ -674,22 +807,7 @@ function try_viewing (view_command, viewer_replacement)
     return view_result
 end
 
--- compare two filenames with the following rule:
--- 1. extensions are ordered as in ext_list first,
--- 2. then filenames lexicograhpicaly.
-function file_order (a, b)
-    local ext_a = string.match (a, '^.*%.(.*)$')
-    local ext_b = string.match (b, '^.*%.(.*)$')
-    ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
-    ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
-    if ext_pos_a < ext_pos_b then
-        return true
-    elseif ext_pos_a > ext_pos_b then
-        return false
-    else
-        return (a < b)
-    end
-end
+--------------------------------   displaying   --------------------------------
 
 -- display a table, sorted, numbered with given offset (0 by default), 
 -- with real path
@@ -697,11 +815,7 @@ function display_table (t, offset)
     offset = offset or 0
     table.sort(t, file_order)
     for i, val in ipairs (t) do
-        if config.interact_switch then 
-            print (i+offset, real_path(val))
-        else
-            print (real_path(val))
-        end
+        print(string.format('%2d %s', i+offset, real_path(val)))
     end
 end
 
@@ -732,8 +846,9 @@ function print_menu (files, comp)
     end
 end
 
--- error handling
------------------
+--------------------------------------------------------------------------------
+-----------------------   functions for error handling   -----------------------
+--------------------------------------------------------------------------------
 
 -- exit codes (probably make sense only with a single argument)
 -- 0    OK
@@ -764,19 +879,18 @@ end
 
 -- generic error display function (see the error_priority constant)
 function err_print (msg, lvl)
-    -- be careful: maybe config.noise_level is not set yet
-    local noise_level = config.noise_level or 10000
-    if err_priority[lvl] <= noise_level then
+    -- be careful: maybe config.verbosity_level is not set yet
+    local verbosity_level = config.verbosity_level or 2
+    if err_priority[lvl] <= verbosity_level then
         io.stderr:write ("texdoc "..lvl..": "..msg.."\n")
     end
 end
 
+--------------------------------------------------------------------------------
+---------------------------   main code execution   ----------------------------
+--------------------------------------------------------------------------------
 
--- END of function definitions: here starts the execution
---=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-
--- initialisations
-------------------
+-----------------------------   initialisations   ------------------------------
 
 -- initialize kpathsea
 kpse.set_program_name(arg[-1], "texdoc")
@@ -791,8 +905,10 @@ setup_config_from_env ()
 setup_config_from_files ()
 setup_config_from_defaults ()
 
--- the main loop over the args
-------------------------------
+-- now that verbosity_level is known...
+show_config_files(function(s) err_print(s, 'debug1') end)
+
+------------------------   looping over the arguments   ------------------------
 
 -- initialising and saving a few values
 exit_code = 0
diff --git a/Master/texmf/texdoc/texdoc.cnf b/Master/texmf/texdoc/texdoc.cnf
index b121e1e7318..a0ec73aae51 100644
--- a/Master/texmf/texdoc/texdoc.cnf
+++ b/Master/texmf/texdoc/texdoc.cnf
@@ -37,7 +37,7 @@
 # interact_switch = true
 # alias_switch = true			# but false if mode is 'regex'
 # ext_list = pdf, html, txt, ps , 	# note the empty string at end
-# noise_level = 3
+# verbosity_level = 3
 
 ### Aliases ###
 
@@ -51,8 +51,6 @@ alias latex = latex-doc-ptr
 ## various stuff
 
 # a few useful general documents
-alias mathmode = Mathmode
-alias visualfaq = visualFAQ
 alias symbols = symbols-a4
 alias faq-en = newfaq
 alias faq = newfaq
@@ -82,6 +80,7 @@ alias lshort-vi	= lshort-vi		# vietnamese
 
 
 # *TeX engines reference manuals, man pages and related
+alias e-tex-ref = etex_man
 alias etex-ref = etex_man
 alias pdftex-ref = pdftex-a
 alias xetex-ref = XeTeX-reference
@@ -92,6 +91,7 @@ alias pdftex-man = man1/pdftex
 alias luatex-pkg = oberdiek/luatex.pdf
 
 # by default, <engine> = <engine>-ref (duplicated: no alias cascading)
+alias e-tex = etex_man
 alias etex = etex_man
 alias pdftex = pdftex-a
 alias xetex = XeTeX-reference
@@ -145,6 +145,7 @@ alias metapost = mpman
 alias iso = isoman
 alias pstricks = pstricks-doc
 alias extramarks = fancyhdr
+alias fonttable = fonttable/fonttable
 
 ## a few easy patterns 
 
@@ -454,4 +455,10 @@ alias vrbexin = vrbexin.sty
 alias vruler = vruler.sty
 alias wrapfig = wrapfig.sty
 
+# the next line has no effect when this file is installed as
+# TEXMFMAIN/texdoc/texdoc.cnf but is useful when it is installed as
+# TEXMFHOME/texdoc/texdoc-dist.cnf for the purpose of installing a newer
+# version of texdoc in one's home (eg, running texdoc from SVN)
+lastfile_switch = true
+
 # vim: ts=8 noexpandtab: