path: root/Master/texmf-dist/doc/support/texdoc/texdoc.tex

%#!xelatex
% Texdoc user manual
% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura
% distributed under the terms of GPL v3 or later

\setlength\overfullrule{5pt}

\documentclass[a4paper,oneside]{scrartcl}
\usepackage{fontspec}
\usepackage{xunicode}

\defaultfontfeatures{Ligatures=TeX}
\setmainfont{DejaVuSerif}
\setsansfont{DejaVuSans}
\setmonofont{DejaVuSansMono}
\renewcommand\familydefault{\sfdefault} \normalfont
\newcommand\mylangle{$\langle$}
\newcommand\myrangle{$\rangle$}

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

\usepackage[sf,bf]{titlesec}
\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
\titleformat{\subsubsection}[runin]{\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[bookmarks=true]{hyperref}
\usepackage{bookmark}
\hypersetup{%
  bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
  pdftitle={Texdoc: find and view documentation in TeX Live},
  pdfauthor={Manuel Pégourié-Gonnard, Takuto Asakura},
  pdfsubject={Texdoc's user manual},
  pdfkeywords={Texdoc, TeX Live, manual, documentation},
}

\usepackage[yyyymmdd]{datetime}
\renewcommand{\dateseparator}{-}

\newcommand\texlive{\TeX~Live\xspace}

\setlength\parindent{\baselineskip}

\lastlinefit=500 % e-TeX powered

\definecolor{links}{named}{violet}
\definecolor{special}{rgb}{0,0.5,0}
\definecolor{code}{rgb}{0,0,0.6}
\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}

\newcommand\cofont{% code
  \color{code}\normalfont\ttfamily}
\newcommand\meta[1]{% meta elements
  {\normalfont\color{special}\mylangle\textit{#1}\myrangle}}

% take care of non-breakable spaces
\catcode`\ 10\relax

\fvset{%
  formatcom=\cofont,
  defineactive=\makeallfancy,
  codes=\fancyactives,
}
\newcommand\fancyactives{\catcode`\«\active}
\newcommand\makeallfancy{\makefancyog}
\bgroup
  \catcode`\«\active
  \global\def\makefancyog{\def«##1»{\meta{##1}}}
\egroup

\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
% code in hors-text
\newenvironment{htcode}
  {\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\tdml{\href{http://lists.tug.org/texdoc}{texdoc mailing list}\xspace}

\title{Texdoc}
\subtitle{Find \& view documentation in \texlive\\
  \href{https://tug.org/texdoc/}{https://tug.org/texdoc/}}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
\date{v3.1\quad \today}

\begin{document}
\VerbatimFootnotes

\maketitle

\section{Quick guide}

\subsection{Basics}

Texdoc is a command line tool which find and view documentation in \texlive.
If you type
%
\begin{quote}
|texdoc «name»|
\end{quote}
%
in your command line, the documentation of the |«name»| package will pop up. Of
course, you have to replace |«name»| with the actual name of the package. To
look up the documentation of more than one package at once, just use multiple
|«name»|s as arguments.

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

Texdoc has different modes that determine how results will be handled. In the
default, ``view'' mode, it opens the first (supposedly the best) result with a
suitable 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 another 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.

By default, Texdoc hides the results it considers less relevant (unless it
finds no relevant result at all). In ``showall'' mode, it always shows all
results.

To select the mode on the command-line, 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, you don't want to keep typing the
same option. The next section describes how to customize Texdoc using
configurations files.

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

Use |texdoc --files| to know where to put your personal configuration file;
you'll need to create this file (a possibly some directories) the first time.
(If you want to know the full list of possible configuration files,
see~\ref{ss-prec}.)

In order to select you favorite mode, just insert a line |mode = «mode»| in
this file, where |«mode»| is one of |view|, |mixed|, |list| or |showall|. To
set your favorite language, use |lang = «2-letter code»|, though it is usually
detected automatically.

The configuration file 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}\label{ss-viewer}

Texdoc's mechanism for choosing a viewer varies according to your platform.
On Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
associations like when you double-click files in the Explorer, the Finder or
your default file manager (except for the text viewer, which is always a
pager). Otherwise, 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 setting 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{You can stop reading now}

Following parts explain Texdoc's mechanisms for finding the best results and
how to customize them. We have been trying hard to optimize the default
configuration values so that you normally don't need to fiddle with that, but
you may be curious or have special needs.

The final part is a full reference including a few points omitted in the
present and next parts.

\clearpage

\section{File search, aliases, score}

\subsection{An overview of how Texdoc works}

When you type |texdoc «keyword»|, Texdoc first makes a list of files, from two
sources:
\begin{enumerate}
  \item In the trees containing documentation (given by the
    \href{https://www.tug.org/kpathsea/} {kpathsea} variable |TEXDOCS|), it
    selects all files containing |«keyword»| in their name (including the
    directory name);
  \item In the \texlive Database, it looks for packages named
    |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be
    |sty| or |cls|, and selects all the documentation files from this package.
\end{enumerate}
Files are filtered by extension: only files with known extensions may be
selected. In case Texdoc cannot find any documentation here, fuzzy search will
find the closest package name to the |«keyword»| and reselect the files (see
\ref{ss-fuzzy}).

The selected files are then score according to some simple heuristics. For
example, a file named |«keyword».pdf|, is good, |«keyword»-«lang».pdf| will
score higher if your favorite language |«lang»| is detected or configured,
|«keyword»-doc| will be preferred over |«keyword»whatever|, files in a
directory named exactly |«keyword»| get a bonus, etc.

Score may also be adjusted base on file extensions or known names (or
subwords): for example, 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 \texlive. Other source files are discriminated
  by extension.}

Finally, 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. Results with very bad scores
(-100 and below) are never displayed.

\medskip

This model for searching and scoring is quite efficient, but is unfortunately
not perfect: Texdoc may sometimes need a hint, either to find a relevant file
or, more likely, to recognize which of the files found is the most relevant.

For example, assume you are looking for the documentation of the shortvrb
{\LaTeX} package. Texdoc will find |shortvrb.sty| in the |latex| \texlive
package, but since this package contains a lot of documentation files, none of
which contains the string |shortvrb|, it will sort them basically at random.

Here comes the notion of \emph{alias}: in the default configuration file,
|shortvrb| is aliased to |base/doc|, so that when you type |texdoc shortvrb|,
Texdoc knows it has to look primarily for |base/doc|. Note that Texdoc will
also look for the original name, and that a name can be aliased to more than
one new name.

\medskip

We will soon see how you can configure this, but let's start with a few
definitions about how a file can match keyword (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
    sequences of alphanumeric characters delimited by punctuation characters
    (there is no space in file names in \texlive) and a subword is a
    substring both ends of which are a word boundary.
  \item The keyword matches ``exactly'' the file name: that is, the file
    name is the keyword, possibly plus an 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 shortvrb = base/doc
\end{htcode}
in order to alias |shortvrb| to |base/doc|. Precisely, it means that files in
the doc trees matching exactly |base/doc| will be added to the result list
when you look for |shortvrb|, 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 useful if you associate many aliases to
a keyword and want one of them to show up first.

Additionally, starting from with v0.80, aliases for |«keyword»-«lang»|, where
|«lang»| is your preferred language's 2-letter code (as detected or
configured, see the |lang| option) are also used for |«keyword»| and get a
|+1| score upgrade.

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.

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. To prevent the default aliases
from being applied for a particular keyword, include |stopalias «keyword»| in
your personal configuration file. It will preserve the aliases defined before
this directive (if any) but prevent all further aliasing on this keyword.

\textit{Remark.} Aliasing is case-insensitive, and doesn't cascade:
only aliases associated to the original keyword are used.

\textbf{Warning.} Results found from aliases always have the score defined by
the |alias| directive (10 by default), regardless of the adjustments described
in the next subsections.

\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 a configuration file
(\ref{ss-quick-file} or \ref{ss-prec}) using the |adjscore| 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 named |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 will 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.
So, don't be surprised if you need to adapt your scoring directives after a
future update of Texdoc. This warning will hopefully disappear at some point.

\subsection{File extensions and names}\label{ss-ext}

The allowed file extensions are defined by the configuration item |ext_list|
(default: pdf, html, htm, txt, md, 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).

Unfortunately, sometimes what follows a dot in a file name is not a ``real''
extension. This often happens with readme files, for example |readme.fr| or
|readme.texlive|. So, in addition to his list of known extensions, Texdoc has
a list of known basenames, by default just |readme|.

The corresponding settings are |basename_list| and |badbasename_list|; both
are similar to |ext_list| and |badext_list|. So, a file will be selected if
either its extension or its base name is known, and get a lesser score if
either is known to be ``bad.''

\subsection{Variants}\label{ss-variants}

The documentation for a given package is often found in a file named like
|«package»-doc|. To handle this properly, Texdoc gives a special score files
named |«package»«suffix»| where |«suffix»| is one element of the list given by
the configuration setting |suffix_list|.

To customise this list, add a line with |suffix_list = «your, list»| in a
configuration file. Be warned, it will replace the default list, no expand
it. You'll find the default list in the shipped configuration file; feel free
to suggest additions on the \tdml (with a real-life example).

\subsection{Fuzzy search}\label{ss-fuzzy}

When the normal search can't find any document in {\texlive}, Texdoc will
execute fuzzy search without user-interactions. The fuzzy search finds the
closest name of package in {\texlive}\footnote{Note that the feature searches
only package names at this point. Other objects such as aliases cannot be found
by the fuzzy search.} to the input |«keyword»|. The results of fuzzy search are
shown by as an informational message (you can see that with option |-v|).

The default allowance of Levenshtein distance is 5. You can change this default
value by specifying |fuzzy_level| in your |texdoc.cnf| (see
\ref{cf-fuzzy_level}). Results of fuzzy search could be irreproducible if
multiple strings have the same Levenshtein distance.

\clearpage

\section{Full reference}

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

Values for a particular setting can come from several sources. The sources are
treated in the following order and the 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 (see below).
  \item Hard-coded defaults that may depend on the current machine.
\end{enumerate}

The configuration files are found in the directories |TEXMF/texdoc|, where
|TEXMF| is the kpathsea variable, in the order given by this variable. Inside
each directory, three files are recognized, in this order:
\begin{enumerate}
  \item |texdoc-«platform».cnf| where |«platform»| is the name of the current
    platform (defined as the name of the directories where the \texlive
    binaries are located, for example |x86-64-linux|). This may be useful when
    an installation is shared across machines with different architectures
    needing different settings, for example for viewers. Their use is not
    recommended in any other situation.
  \item |texdoc.cnf| is the recommended file for normal use.
  \item |texdoc-dist.cnf| is useful for installing a newer version of texdoc
    (including its default configuration file) in your home while retaining
    the use of the previous file for your personal setting; see
    \href{https://github.com/TeX-Live/texdoc}{our GitHub repository} for
    instructions on running the development version.
\end{enumerate}

\subsection{Command-line options}\label{ss-cl}

All command-line options (except the first four 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 exit
successfully.

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

Shows the current version of the program and exit successfully.

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

Shows the list of configuration files for the current installation and
platform, with their status and exit successfully. Normally, only ``active''
and ``disabled'' files are shown (see~\ref{cf-lastfile_switch}). To show ``not
found'' files as well, you can use |--verbose|.

\begin{cmdsubsub}{--just-view}{cl-just-view}
  --just-view «file»
\end{cmdsubsub}

Open «file» in the usual viewer. The file should be given with full path,
absolutely no searching is done. This option is not really meant for users,
but rather intended to be used from another program, like a GUI front-end to
Texdoc.

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

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

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

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

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

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

\begin{cmdsubsub}{-q, --quiet}{cl-q}
  -q, --quiet
\end{cmdsubsub}

Set |verbosity_level| to minimum, see~\ref{cf-verbosity_level}.

\begin{cmdsubsub}{-v, --verbose}{cl-v}
  -v, --verbose
\end{cmdsubsub}

Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}.

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

Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug|
without specifying a list, activates all available debug items.

\begin{cmdsubsub}{-c}{cl-c}
  -c «name»=«value»
\end{cmdsubsub}

Set configuration item |«name»| to |«value»|. This is a general way to access
any configuration items listed in \ref{ss-conf} from command line.

\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.\footnote{Old names of environment variables,
namely |TEXDOCVIEW_{html,dvi,md,txt,pdf,ps}| and
|TEXDOC_VIEWER_{HTML,DVI,MD,TXT,PDF,PS}|, are deprecated but still work.} You can
append |_texdoc| to every name in the first column: this wins over every other
name.

\begin{center}
\begin{tabular}{ll}
Environment variables & Configuration items \\
|BROWSER|             & |viewer_html|       \\
|DVIVIEWER|           & |viewer_dvi|        \\
|MDVIEWER|            & |viewer_md|         \\
|PAGER|               & |viewer_txt|        \\
|PDFVIEWER|           & |viewer_pdf|        \\
|PSVIEWER|            & |viewer_ps|         \\
\end{tabular}
\end{center}

Also, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
are used for the default value of |lang|.

\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»
\end{cmdsubsub}
Set the  mode to the given value. Default is |view|. The various modes
have been presented in~\ref{ss-modes}.

\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 from asking you to choose a file to view when there are multiple
choices, so it just prints the list of files found.

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

Set the list of known suffixes to |«list»| (see~\ref{ss-variants}). Default is
the empty list, but see the shipped configuration file for more.

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

Set the list of recognised extensions to |«list»|. The default value is:
%
\begin{htcode}
  pdf, html, htm, txt, md, 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»|, independently of the
current value of |ext_list| and |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, htm, 1, 5, txt, md, dvi, ps,
  viewer_1 = man
  viewer_5 = man
\end{htcode}

As a special case, if the extension is |sty|, then the |txt| viewer is used;
similarly, if it is |htm| the |html| viewer is used. Otherwise, the |txt|
viewer is used and a warning is issued.

\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 malus of |1| on their heuristic score if it was
previously positive.

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

Set the list of ``known'' base names to |«list»|. Default is ``|readme|''.
Files with those base names are selected regardless of their extension. If the
extension is unknown, the text viewer will be used to view the file.

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

Set the list of ``bad'' base names to |«list»|. Default is ``|readme|''. Files
with those names get a malus of |1| on their heuristic score if it was
previously positive.

\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 an arbitrary
shell construct.

\begin{cmdsubsub}{lang}{cf-lang}
  lang = «2-letter code»
\end{cmdsubsub}

Set you preferred language. Defaults to your system's locale.

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

Set the verbosity level to |«n»| (default: 2). At level~3, errors, warnings and
informational messages will be printed on stderr; 2 means only errors and
warnings, 1 only errors and 0 nothing except internal errors (obviously not
recommended).

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

Set the list of activated debug items (default: none). Available debug items
are |config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|,
|view|, and |all| to activate all of these. Implies |--verbose|. Debug
information are printed on standard error.

\begin{cmdsubsub}{max_line}{cf-max_lines}
  max_lines = «number»
\end{cmdsubsub}

Set the maximum number of results to be printed without confirmation in list,
mixed or showall mode (default: 20). This setting has no effect if interaction
is disabled.

\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 an 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.

Currently, there are two additional fields: a two-letter language code, and an
unstructured description, both taken from the CTAN catalogue (via the \texlive
database). These fields may be empty, and they are not guaranteed to keep the
same meaning in future versions of Texdoc.

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

List of supported extensions for zipped files (default: empty). Allows
compressed files with names like |foobar.«zip»|, with |«zip»| in the given
|«list»|, to be found and unzipped before the viewer is started (the
temporary file will be destroyed right after).

\textbf{Warning.} Support for zipped documentation is not meant to work on
windows, a Unix shell is assumed! If you add anything to this list, please make
sure that you also set a corresponding |unzip=«ext»| value for each |«ext»| in
the list. At the same time, make sure you are using blocking (i.e., not
returning immediately) viewers.

\textit{Remark.} \texlive doesn't ship compressed documentation files, so
this option is mainly useful with re-packaged version of \texlive that do,
for example in Linux distributions.

\begin{cmdsubsub}{unzip_*}{cf-unzip_star}
  unzip_«zipext» = «command»
\end{cmdsubsub}

The unzipping command for compressed files with extension |«zipext»| (default:
none). Define one for each item in |zipext_list|. The command must print
the result on stdout, like |gzip -d -c| does.

\begin{cmdsubsub}{rm_file, rm_dir}{cf-rm_star}
  rm_file = «command»
  rm_dir  = «command»
\end{cmdsubsub}

Commands for removing files (resp. directories) on your system (defaults:
|rm -f| and |rmdir|). Only useful for zipped documents (see |zipext_list|).

\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{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do
so).

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

Set the allowance of Levenshtein distance to |«n»| for the fuzzy search
(default: 5). At level 0, the fuzzy search feature is disabled.

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

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

\section{Licence}\label{s-licence}

The current version of Texdoc program and its documentation are copyright 2008
Manuel Pégourié-Gonnard, Takuto Asakura, and the {\texlive} Team.

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

\end{document}
% vim: ambiwidth=single spell: