path: root/Master/texmf/doc/texdoc/texdoc.tex

% this is texdoc's user manual
% written by Manuel Pégourié-Gonnard in 2008, 2009
% distributed under the terms of GPL v3 or later

%!TEX encoding=latin1
%!TEX program=pdflatex

\setlength\overfullrule{5pt}

\documentclass[a4paper, oneside]{scrartcl}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{fixltx2e}

\usepackage{tgbonum}
\usepackage{tgheros}
\usepackage[scaled=1.10]{inconsolata}
\renewcommand\familydefault{\sfdefault} \normalfont
\newcommand\otherfamily{\rmfamily}
\newcommand\mylangle{$\langle$}
\newcommand\myrangle{$\rangle$}

\usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}

\usepackage[rm, bf]{titlesec}
\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
\titleformat{\subsubsection}[runin]{\otherfamily\itshape}{%
  \makebox[0pt][r]{\thetitle\kern1pc}}{%
  0pt}{}[\maybedot\space --- \kern0pt]
\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt}

\usepackage{enumitem}
\newlength\lssep \setlength\lssep{\smallskipamount}
\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}

\usepackage[british]{babel}
\usepackage[babel=true, expansion=false]{microtype}
\usepackage[bookmarks=true]{hyperref}
\hypersetup{%
  bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
  pdftitle=texdoc: find and view documentation in TeX Live,
  pdfauthor=Manuel Pégourié-Gonnard,
  pdfsubject=texdoc's user manual,
  pdfkeywords={texdoc, TeX Live, manual}}

\newcommand\CTAN[1]{%
  \href{http://mirror.ctan.org/tex-archive/#1}{CTAN:#1}}
\newcommand\mailto[1]{%
  \href{mailto:#1}{#1}}
\newcommand\package[1]{%
  \href{http://ctan.org/pkg/#1}{#1}}
\newcommand\http[1]{%
  \href{http://#1}{#1}}

\newcommand\texlive{%
  \TeX{}\thinspace Live\xspace}

\setlength\parindent{\baselineskip}

\let\TeXori\TeX \def\TeX{\TeXori\xspace} % breaks the l2e logo
\lastlinefit=500 % e-TeX powered

\definecolor{links}{named}{violet}
\definecolor{special}{rgb}{0,0.5,0}
\definecolor{code}{rgb}{0,0,0.6}
\definecolor{input}{rgb}{1.0,0,0}
\newcommand\inputcolorname{red}
\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
\newcommand\cofont{% % code
  \color{code}\normalfont\ttfamily}
\newcommand\textco[1]{{\cofont#1}}
\newcommand\textme[1]{% % éléments meta
  {\normalfont\color{special}\itshape #1\/}}
\newcommand\epfont{% % épigraphes
  \normalcolor\usefont{T1}{pzc}{m}{it}}
\newcommand\textlmi[1]{% passage en lmodern italique pour voir
  {\usefont{T1}{lmr}{m}{it}#1}}
\newcommand\textcm[1]{% % passage en cm pour voir
  {\fontencoding{T1}\fontfamily{cmr}\selectfont#1}}
\newcommand\file{\nolinkurl}

% take care of nbsp
\catcode`\ 10\relax

\newcommand\meta[1]{% % variantes à remplacer
  {\color{special}\mylangle\textme{#1}\myrangle}}
\newcommand\commandline[1]{%
  \prompt\space \textcolor{input}{#1}}
\newcommand\prompt{\ding{229}}

\fvset{formatcom=\cofont, defineactive={\makeallfancy}}%
\newcommand\makefancyog{%
  \def«##1»{\meta{##1}}}
{\catcode32\active
\gdef\makefancythorn{%
\defþ ##1 þ{\commandline{##1}}}%
}
\newcommand\makefancypar{%
  \def¶##1¶{\textcolor{input}{##1}}}
\newcommand\makeallfancy{%
  \makefancyog\makefancythorn\makefancypar}

\newif\ifframed
\newlength\dec
\setlength\dec{\heightof{\cofont{texdoc \meta{name}}}}

\makeatletter
\newenvironment{commandes}[3]{%
  \def\thecmd{\noexpand#1}%
  \def\bmtext{#2}%
  \def\thelabel{#3}%
  \SaveVerbatim[samepage, gobble=2]{verbmat}%
  }{%
  \endSaveVerbatim
  \xdef\sectioncmd{\noexpand\nodotthistime
    \thecmd[\bmtext]{%
      \ifframed
        \unexpanded{\normalsize\normalfont
          \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
      \else
        \unexpanded{\normalsize\normalfont
          \BUseVerbatim{verbmat}}%
      \fi
      \noexpand\label{\thelabel}}}%
  \aftergroup\sectioncmd}
\makeatother

\newcommand\maybedot{.}
\newcommand\nodotthistime{%
  \renewcommand\maybedot{%
    \global\def\maybedot{.}}}

\newenvironment{cmdsubsec}[2]{%
  \framedtrue \commandes\subsection{#1}{#2}%
  }{%
  \endcommandes}

\newenvironment{cmdsubsub}[2]{%
  \framedfalse \commandes\subsubsection{#1}{#2}%
  }{%
  \endcommandes}

\makeatletter
\newenvironment{htcode}{% % code en hors-texte
  \SaveVerbatim[samepage, gobble=2]{verbmat}%
  }{%
  \endSaveVerbatim
  \par\medskip\noindent\hspace*{\parindent}%
  \BUseVerbatim{verbmat}%
  \par\medskip\@endpetrue}
\makeatother
\DefineShortVerb{\©}

\setkomafont{title}{}
\setkomafont{subtitle}{\Large}
\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}

\newcommand\texdoc{texdoc\xspace}
\newcommand\tdml{\href{mailto:texdoc@tug.org}{texdoc mailing list}\xspace}

\title{\texdoc}
\subtitle{Find \& view documentation in \TeX\ Live}
\author{\url{http://tug.org/texdoc/}\\
  Manuel Pégourié-Gonnard}
\date{v0.60 2009-11-24}

\begin{document}
\VerbatimFootnotes

\maketitle

\section{Quick guide}

\subsection{Basics}

Open a command line\footnote{On windows, use ``Execute'' from the Start menu
  and type ©cmd©.  On Mac OS X, use the ``terminal'' icon on Mac OS X.  If you
  are using another flavour of Unix, you probably know what to do.} and type
©texdoc «name»©: the documentation of the ©«name»© package will pop up. Of
course, replace ©«name»© with the actual name of the package you want to learn
about. You can also look for the documentation of more than one package at
once: just give many names as arguments.

The rest of this section describes the most usual options, like how to
see all documentation related to a package or use a different viewer.

\subsection{Modes}\label{ss-modes}

\texdoc has different modes that determine how results will be handled. The
default mode, called ``view'' mode, is to open the first (supposedly the best)
result in a viewer. It is rather handy when you know what you want to read,
and want to access it quickly. On the other hand, there may be other relevant
documents for the given ©«name»©, which are ignored in view mode.

The so-called ``list mode'' makes \texdoc list all relevant documentation and
ask you which one you want to view. It is useful when there a other
interesting sources of information besides the package's main documentation.

There is also a ``mixed'' mode, intended to combine the best of view mode and
list mode: if there is only one relevant result, then \texdoc opens it in a
viewer, else it offers you a menu.

Usually, \texdoc shows you only results it considers relevant. If there are no
``good'' results, it falls back to less relevant results. You can force
\texdoc to show you also ``bad'' results even when there are good ones by
using the ``showall'' mode. (This implies using a menu rather than starting a
viewer.)

You can select with command-line options: use ©texdoc «option» «name»© with
one of the following options: ©-w© or ©--view© for view mode, ©-m© or
©--mixed© for mixed mode, ©-l© or ©--list© for list mode, ©-s© or ©--showall©
for showall mode.

If you always (or mostly) use the same mode, it is probably easier to
select it in a configuration file than to always use the command-line
option. For this, see the next section.

\subsection{Configuration files}\label{ss-quick-file}

\texdoc use various configuration files, which you can see using the ©-f© or
©--files© options. The second entry in this list is marked with a star ©(*)©:
it is the file you should use for your personal preferences as a user; you may
need to create it (and the parents directories).

In order to select you favorite mode, just insert a line ©mode = «yourmode»©
in this files, where ©«yourmode»© is one of ©view©, ©mixed©, ©list© or
©showall©.

The configuration files can be used to tweak \texdoc in many ways, the most
useful of which is probably the selection of the viewers for various types of
documents, explained in the next section.

\subsection{Viewers}

\texdoc's mechanism for choosing a viewer varies according to your platform.
On Windows and MacOS, it uses your file associations like when you
double-click files in the Explorer or the Finder (except for the text viewer,
which is always a pager). On Unix, it tries to find a viewer in the path from
a list of ``known' viewers.

You may want to select a different viewer for some kind of file. This is
achieved by the various ©viewer_«ext»© configuration options, where ©«ext»© is
the extension corresponding to the file type. For example, if you want to set
xpdf as your default PDF viewer, and run it in the background, insert the line
©viewer_pdf = xpdf %s &© in your configuration file. Here, ©%s© stands for the
name of the file to view.

\subsection{Conclusion}

We have now covered the most common needs. The next part explains
how \texdoc proceeds to find the best results.
The default configuration file tries hard to set appropriate values so that
you have a good out-of-the-box experience, but you may want to understand the
underlying mechanisms and adapt them to your needs. The final part is a full
reference for configuration options, including points omitted in the present
part.

Your feedback is very welcome of the \tdml. Feel free to post comments, bug
reports, suggestions for improvements (inc. new aliases), even without
subscribing.

\clearpage

\section{File search, aliases, score}

\subsection{An overview of how texdoc works}

When you type ©texdoc «keyword»©, texdoc browses the trees containing
documentation (given by the \href{http://www.tug.org/kpathsea/} {kpathsea}
variable ©TEXDOCS©), lists all files containing ©«keyword»© in their name
(including the directory name) and give them a score based on some simple
heuristics. For example, a file named ©«keyword».pdf©, will get a high score,
©«keyword»-doc© will be preferred over ©«keyword»whatever©, files in a
directory named exactly ©«keyword»© get a bonus, etc.

There is also some filtering based on extensions: only files with known
extensions are listed, and some extensions get a lesser score. Also, there is
some score adjustments based on keywords; by default, Makefile's get a very
bad score since they are almost never documentation.\footnote{They often end
  up in the doc tree, since the source of documentation is often in the same
  directory as the documentation itself in \TeX\ Live. Other source files are
  discriminated by extension.}

Then, depending on the mode, the file with the highest score is opened in a
viewer, or the list of results is shown. Usually, only results with a positive
score are displayed, except in showall mode. Result with very bad score (-100
and below) are never displayed.

\medskip

However, this model works only if the documentation for ©«keyword»© has
©«keyword»© in its name, which is not always true. The documentation of the
memoir class is in ©memman.pdf©, for example, but it will be found anyway
since it is in a directory named memoir. But there are more complicated cases:
the documentation for mathptmx is in ©psnfss2e.pdf©, which is quite more
complicated to guess.\footnote{But not totally impossible: using the \TeX\
  Live database, texdoc can know which documentation files are associated with
  a given ©.sty© file. Here, it could guess that the documentation is either
  ©psfonts.pdf© of ©psnfss2e.pdf©. This will probably be done in a future
  version.}

Here comes the notion of \emph{alias}: in the default configuration file,
mathptmx is aliased to psnfss2e, so that when you type ©texdoc mathptmx©,
texdoc knows it has to look also for psnfss2e. Note that texdoc will also look
for the original name, and that a name can be aliased to more than one new
name (this is new in texdoc 0.60).

\medskip

We will soon see how you can configure this, but let's give a few definitions
about how a file can match keyword first (all matching is case-insensitive):
\begin{enumerate}
  \item The keyword is a substring of the file name.
  \item The keyword is a ``subword'' of the file name; words are defined as a
    sequence of alphanumeric characters delimited by punctuation characters
    (there is no space in file names in \TeX\ Live) and a subword is a
    substring both ends of which are a word boundary.
  \item The keyword can match ``exactly'' the file name: that is, the file
    name is the keyword + and extension.
\end{enumerate}

\subsection{Alias directives}\label{ss-alias}

\begin{htcode}
  alias «original keyword» = «name»
  alias(«score») «original keyword» = «name»
\end{htcode}

You can define your own aliases in \texdoc's configuration files
(see~\ref{ss-quick-file} or \ref{ss-prec}). For example,
insert\footnote{Actually, you don't need to do this, the default configuration
  file already includes this directive.}
\begin{htcode}
  alias mathptmx = psnfss2e
\end{htcode}
in order to alias mathptmx to psnfss2e. Precisely, it means that files
matching exactly psnfss2e will be added to the result list when you look for
mathptmx, and get a score of 10 (default score for alias results). This is
greater than the results of heuristic scoring: it means that results found via
aliases will always rank before results associated to the original keyword.

If you want the results associated to a particular alias to have a custom
score instead of the default 10, you can use the optional argument to the
alias directive. This can be usefull if you associate many aliases to
a keyword and want one of them to show up first.

You can have a look at the configuration file provided (the last shown by
©texdoc -f©) for examples.  If you feel one of the aliases you defined locally
should be added to the default configuration, please share it on the \tdml.

Please note than aliasing is case-insensitive, and the aliases don't cascade:
only aliases associated to the original keyword are used.
Aliases are additive: if you define your own aliases for a keyword in your
configuration file, and there are also aliases for the same keyword in the
default configuration, they will add up. You can prevent the default aliases
from begin applied for a particular keyword by saying ©stopalias «keyword»© in
your personal configuration file. It will keep the aliases defined before
this directive (if any) and prevent all further aliasing on this keyword.

If, for some reason, you want to prevent any alias from begin used for one
particular session of texdoc, you can use the ©-A© or ©--noalias© command-line
option (see~\ref{cl-a}).

\subsection{Score directives}\label{ss-score}

\begin{htcode}
  adjscore «pattern» = «score adjustment»
  adjscore(«keyword») «pattern» = «score adjustment»
\end{htcode}

It is possible to adjust the score of results containing some pattern as a
subword, either globally (for the result of all searches) or only 
when searching with a particular keyword. This is done in the
configuration file (\ref{ss-quick-file} or \ref{ss-prec}) using the 
©adjustscore© directive. Here are a few examples from the default
configuration file.

\begin{htcode}
  adjscore /Makefile = -1000
  adjscore /tex-virtual-academy-pl/ = -50
  adjscore(tex) texdoc = -10
\end{htcode}

All files named ©Makefile© (and also files names ©Makefile-foo© if there are
any): are ``killed'' : by adjusting their score with such a large negative
value, their final score will most probably be less than -100, so they will
never be displayed. Files from the ©tex-virtual-academy-pl© directory, on the
other hand, are not killed but just get a malus, since they are a common
source of ``fake'' matches which hide better results (even for the lucky ones
who can read polish).

The third directive gives a malus for results containing ©texdoc© only if the
search keyword is ©tex©. Otherwise, such results would get a high score
because the heuristic scoring would think ©texdoc© is the name of \TeX's
documentation. The value -10 is enough to ensure that those results will have
a negative score, so wil not be displayed unless ``showall'' mode is active.

\textbf{Warning}: Values of scores (like the default score for aliases, the
range of heuristic scoring, etc.) may change in a future version of texdoc.
Scoring is quite new and may need some adjustments. So, don't be surprised if
you need to adapt your scoring directives after a future update of texdoc.
This warning will disappear at some point.

\subsection{File extensions}

The allowed file extensions are defined by the configuration item ©ext_list©
(default: pdf, html, txt, ps, dvi, no extension). You can configure it with
a line ©ext_list = «your, list»© in a configuration file. Be aware
that it will completely override the default list, not add to it. An empty
string in the list means files without extension (no dot in the name), while a
star means any extension.

For scoring purposes, there is also a ©badext_list© parameter: files whose
extension is ``bad'' according to this list will get a lesser score (currently
0). This only affect heuristic scoring (results found from the original
keyword, not from aliases).

\clearpage

\section{Full reference}

\subsection{Precedence of configuration sources}\label{ss-prec}

Values for a particular setting can come from several sources. They are treated
in the following order, where first value found is always used:
\begin{enumerate}
  \item Command-line options.
  \item Environment variables ending with ©_texdoc©.
  \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 ©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»© 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. 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}

All command-line options (except the first three below) correspond to
configuration item that can be set in the configuration files: we refer
the reader to the corresponding section for the meaning of this configuration
item.

\begin{cmdsubsub}{-h, --help}{cl-h}
  -h, --help
\end{cmdsubsub}

Shows a quick help message (namely a list of command-line options) and exits
successfully.

\begin{cmdsubsub}{-V, --version}{cl-V}
  -V, --version
\end{cmdsubsub}

Show the current version of the program and exits successfully.

\begin{cmdsubsub}{-f, --files}{cl-f}
  -f, --files
\end{cmdsubsub}

Shows the list of the configuration files for the current installation and
platform, with their status (active, not found, or disabled
(see~\ref{cf-lastfile_switch})) and exits successfully.

\begin{cmdsubsub}{-w, -l, -m, -s, -r, --view, --list, --mixed, --showall,
    --regex}{cl-mode}
  -w, --view, -l, --list, -m, --mixed, -s, --showall, -r, --regex
\end{cmdsubsub}

\hfill Set ©mode© to the given value, see~\ref{cf-mode}.

\begin{cmdsubsub}{-a, -A, --alias, --noalias}{cl-a}
  -a, --alias, -A, --noalias
\end{cmdsubsub}

Set ©alias_switch© true (resp. false), see~\ref{cf-alias_switch}

\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
  -i, --interact, -I, --nointeract
\end{cmdsubsub}

Set ©interact_switch© to true (resp. false), see~\ref{cf-interact_switch}.

\begin{cmdsubsub}{-e, --extensions}{cl-e}
  -e=«l», --extensions=«l»
\end{cmdsubsub}

Set ©ext_list©, see~\ref{cf-ext_list}. \textbf{Warning}: this command-line
option is deprecated and will likely be removed soon. It is recommended to set
©ext_list© in a configuration file instead. Please protest on the \tdml if you
want to keep this command-line option.

\begin{cmdsubsub}{-v, --verbosity}{cl-v}
  -v=«n», --verbosity=«n»
\end{cmdsubsub}

Set ©verbosity_level© to ©«n»©, see~\ref{cf-verbosity_level}. Be aware that you
must avoid spaces on the command line, and the ©=© sign is optional.

\begin{cmdsubsub}{-d, --debug}{cl-d}
  -d, -d=«list», --debug, --debug=«list»
\end{cmdsubsub}

Set ©debug_list©, see~\ref{cf-debug_list}. If not list is given, activates all
available debug items.

\begin{cmdsubsub}{-M, --machine}{cl-M}
  -M, --machine
\end{cmdsubsub}

Set ©machine_switch© to true, see~\ref{cf-machine_switch}.

\subsection{Environment variables}\label{ss-envvar}

They all correspond to some ©viewer_«ext»© setting, and the reader is referred
to~\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}{*4l}
    New name    & Old name 1        & Old name 2           & Config. item\\
    ©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 items}\label{ss-conf}

\subsubsection{Structure of configuration files}\label{sss-sonf-struct}

Configuration files are line-oriented text files. Comments begin with a ©#©
and run to the end of line. Lines containing only space are ignored. Space at
the beginning or end of a line, as well as around an ©=© sign, is ignored.
Apart from comments and empty lines, each line must be of one of the following
forms.

\begin{htcode}
  «configuration item» = «value»
  alias «original keyword» = «name»
  alias(«score») «original keyword» = «name»
  stopalias «original keyword»
  adjscore «pattern» = «score adjustment»
  adjscore(«keyword») «pattern» = «score adjustment»
\end{htcode}

We will concentrate on the ©«configuration item»© part here, since other
directives have already been presented (\ref{ss-alias} and \ref{ss-score}).

In the above, ©«value»©  never needs to be quoted: quotes would be interpreted
as part of the value, not as quotation marks (this also holds for the other
directives).

Lines which do not obey these rules raise a warning, as well as unrecognised
values of ©«configuration item»©. The ©«value»© can be an arbitrary string,
except when the name of the ©«configuration item»© ends with:
\begin{enumerate}
  \item ©_list©, then ©«value»© is a coma-separated list of strings. Space
    around commas is ignored. Two consecutive comas or a coma at the beginning
    or end of the list means the empty string at the corresponding place.
  \item ©_switch©, then ©«value»© must be either ©true© or ©false©
    (lowercase).
  \item ©_level©, then ©«value»© is an integer.
\end{enumerate}
In these cases, an improper ©«value»© will raise a warning too.

\begin{cmdsubsub}{mode}{cf-mode}
  mode = «view, list, mixed, showall, regex»
\end{cmdsubsub}
Set the  mode to the given value.  Default is ©view©. All mode except regex
have been presented in~\ref{ss-modes}.

In regex mode, the given name is interpreted as a Lua regex, and only files
whose full name (including path) matches it are found. Alias and score
mechanisms are disabled.  \textbf{Warning}: this mode is deprecated and will
likely be removed soon.  Please protest on the \tdml if you want it to stay.

\begin{cmdsubsub}{interact}{cf-interact_switch}
  interact_switch = «true, false»
\end{cmdsubsub}

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,
so it just prints the list of files found.

\begin{cmdsubsub}{alias}{cf-alias_switch}
  alias_switch = «true, false»
\end{cmdsubsub}

Turn on or off aliasing.  Default is on.

\begin{cmdsubsub}{ext_list}{cf-ext_list}
  ext_list = «list»
\end{cmdsubsub}

Set the list of recognised extensions to ©«list»©.  Default is
\begin{htcode}
  pdf, html, txt, dvi, ps,
\end{htcode}
This list is used to filter and  sort the results that have the same
score(with the default value: pdf first, etc).  Two special values are
recognised:
\begin{itemize}
  \item \emph{The empty element}. This means files without extensions, or more
    precisely without a dot in their name.  This is meant for files like
    ©README©, etc.  The file is assumed to be plain text for viewing purpose.
  \item ©*© means any extension.  Of course if it is present in the list, it
    can be the only element!
\end{itemize}

There is a very special case: if the searched ©«name»© has ©.sty© extension,
\texdoc enters a special search mode for ©.sty© files (not located in the same
place as real documentation files) for this ©«name»©, indepandantly of the
current value of ©ext_list© and ©mode© (unless it is the ©regex© mode). In an
ideal world, this wouldn't be necessary since every sty file would have a
proper documentation in pdf, html or plain text, but\dots

For each ©«ext»© in ©ext_list© there should be a corresponding
©viewer_«ext»© value set.  Defaults are defined corresponding to the default
©ext_list©, but you can add values if you want.  For example, if you want
\texdoc to be able to find man pages and display them with the ©man© command,
you can use
\begin{htcode}
  ext_list = pdf, html, 1, 5, txt, dvi, ps,
  viewer_1 = man
  viewer_5 = man
\end{htcode}

\begin{cmdsubsub}{badext_list}{cf-badext_list}
  badext_list = «list»
\end{cmdsubsub}

Set the list of ``bad'' extensions to ©«list»©.  Default is ``©txt,©''. Files
with those extensions get a heuristic score of 0.

\begin{cmdsubsub}{viewer_*}{cf-viewer_*}
  viewer_«ext» = «cmd»
\end{cmdsubsub}

Set the viewer command for files with extension ©«ext»© to ©«cmd»©. For files
without extension, ©viewer_txt© is used, and there's no ©viewer_© variable.
In ©«cmd»©, ©%s© can be used as a placeholder for the file name, which is
otherwise inserted at the end of the command.  The command can be a arbitrary
shell construct. 

\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
  verbosity_level = «n»
\end{cmdsubsub}

Set the verbosity level to ©«n»©. 3 means errors, warnings and informational
message will be printed (on stdout); 2 means only errors and warnings, 1 only
errors and 0 nothing (not recommended).

\begin{cmdsubsub}{debug_list}{cf-debug_list}
  debug_list = «list»
\end{cmdsubsub}

Set the list of activated debug items (default: none). For a list of available
items, see the source code, file ©constants.tlu©, variable ©known_debugs©.
Debug information is printed on standard error.

\begin{cmdsubsub}{machine_switch}{cf-machine_switch}
  machine_switch = «true, false»
\end{cmdsubsub}

Turn on or off machine-readable output (default: off).  With this option
active, the value of ©interact_switch© is forced to ©false©, and each line of
output is
\begin{htcode}
  «argument»\t«score»\t«filename»
\end{htcode}
where ©«argument»© is the name of the argument to which the results correspond
(mainly useful if there were many arguments), ©\t© is the tab (ascii 9)
character, and the other entries are pretty self-explanatory. Nothing else is
printed on stdout, except if a internal error occurs (in which case exit code
will be 1). In the future, more tab-separated fields may be added at the end
of the line, but the first 3 fields will remain unchanged.

\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch}
  lastfile_switch = «true, false»
\end{cmdsubsub}

If set to true, prevents \texdoc from reading any other configuration file
after this one (they will be reported as ``disabled'' by ©texdoc -f©).  Mainly
useful for installing a newer version of \texdoc in your home and preventing
the default configuration file from older versions to be used(see the
\href{http://tug.org/texdoc/}{web site} for instructions on how to do so).

\subsection{Exit codes}\label{ss-exit}

The current exit codes are:
\begin{enumerate}[start=0]
  \item Success.
  \item Internal error.
  \item Usage error.
\end{enumerate}

\clearpage

\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\rmfamily\bfseries
  Happy \TeX{}ing!
\end{center}

\end{document}