summaryrefslogtreecommitdiff
path: root/support/texdoc/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texdoc/doc
Initial commit
Diffstat (limited to 'support/texdoc/doc')
-rw-r--r--support/texdoc/doc/texdoc.1177
-rw-r--r--support/texdoc/doc/texdoc.pdfbin0 -> 76508 bytes
-rw-r--r--support/texdoc/doc/texdoc.tex867
3 files changed, 1044 insertions, 0 deletions
diff --git a/support/texdoc/doc/texdoc.1 b/support/texdoc/doc/texdoc.1
new file mode 100644
index 0000000000..cf072bd5fc
--- /dev/null
+++ b/support/texdoc/doc/texdoc.1
@@ -0,0 +1,177 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "TEXDOC" "1" "March 2019" "Texdoc 3.1" "Texdoc manual"
+.
+.SH "NAME"
+\fBtexdoc\fR \- find & view documentation in TeX Live
+.
+.SH "SYNOPSIS"
+\fBtexdoc\fR [OPTION\.\.\.] NAME\.\.\.
+.
+.br
+\fBtexdoc\fR [OPTION\.\.\.] ACTION
+.
+.SH "DESCRIPTION"
+Try to find appropriate TeX documentation for the specified NAME(s)\. Alternatively, perform the given ACTION and exit\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-w\fR, \fB\-\-view\fR
+Use view mode: start a viewer\. \fB(default)\fR
+.
+.TP
+\fB\-m\fR, \fB\-\-mixed\fR
+Use mixed mode (view or list)\.
+.
+.TP
+\fB\-l\fR, \fB\-\-list\fR
+Use list mode: show a list of results\.
+.
+.TP
+\fB\-s\fR, \fB\-\-showall\fR
+Use showall mode: show also "bad" results\.
+.
+.TP
+\fB\-i\fR, \fB\-\-interact\fR
+Use interactive menus\. \fB(default)\fR
+.
+.TP
+\fB\-I\fR, \fB\-\-nointeract\fR
+Use plain lists, no interaction required\.
+.
+.TP
+\fB\-M\fR, \fB\-\-machine\fR
+Machine\-readable output for lists (implies \-I)\.
+.
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Suppress warnings and most error messages\.
+.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Print additional information (e\.g\., viewer command)\.
+.
+.TP
+\fB\-D\fR, \fB\-\-debug\fR
+Activate all debug output (equal to "\-\-debug=all")\.
+.
+.TP
+\fB\-d\fR LIST, \fB\-\-debug\fR=LIST
+Activate debug output restricted to the items specified in LIST\.
+.
+.br
+Available items: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\.
+.
+.TP
+\fB\-c\fR NAME=VALUE
+Set configuration item NAME to VALUE\.
+.
+.SH "ACTIONS"
+.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print this help message\.
+.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print the version number\.
+.
+.TP
+\fB\-f\fR, \fB\-\-files\fR
+Print the list of configuration files used\.
+.
+.TP
+\fB\-\-just\-view\fR FILE
+Display FILE, given with full path (no searching)\.
+.
+.SH "ENVIRONMENT"
+.
+.TP
+\fBBROWSER\fR, \fBBROWSER_texdoc\fR
+Set the command to be used for HTML documents\.
+.
+.TP
+\fBDVIVIEWER\fR, \fBDVIVIEWER_texdoc\fR
+Set the command to be used for DVI documents\.
+.
+.TP
+\fBMDVIEWER\fR, \fBMDVIEWER_texdoc\fR
+Set the command to be used for Markdown documents\.
+.
+.TP
+\fBPAGER\fR, \fBPAGER_texdoc\fR
+Set the command to be used for text documents\.
+.
+.TP
+\fBPDFVIEWER\fR, \fBPDFVIEWER_texdoc\fR
+Set the command to be used for PDF documents\.
+.
+.TP
+\fBPSVIEWER\fR, \fBPSVIEWER_texdoc\fR
+Set the command to be used for PS documents\.
+.
+.TP
+\fBLANG\fR, \fBLC_ALL\fR and so on
+Set the locale (which will influence on the search results)\.
+.
+.TP
+\fBTEXDOCS\fR
+In addition to the documents included in the TeX Live database, Texdoc also searches documentation under TEXMF trees specified by the kpathsea variable \fBTEXDOCS\fR\.
+.
+.SH "FILES"
+\fB<texmf>/texdoc/texdoc\.cnf\fR, see output of the \fB\-\-files\fR option\.
+.
+.SH "EXIT STATUS"
+The \fBtexdoc\fR command exists with one of the following values:
+.
+.TP
+0
+Success\.
+.
+.TP
+1
+Internal error\.
+.
+.TP
+2
+Usage error\.
+.
+.TP
+3
+No documentation found\.
+.
+.SH "REPORTING BUGS"
+Report bugs to \fItexdoc@tug\.org\fR\.
+.
+.br
+Texdoc home page: \fIhttp://tug\.org/texdoc/\fR
+.
+.br
+Source: \fIhttps://github\.com/TeX\-Live/texdoc\fR
+.
+.SH "COPYRIGHT"
+Copyright 2018 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining\.
+.
+.br
+License: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\.
+.
+.br
+This is free software: you are free to change and redistribute it\.
+.
+.SH "SEE ALSO"
+The full documentation is maintained as a PDF manual\. The command
+.
+.IP "" 4
+.
+.nf
+
+texdoc texdoc
+.
+.fi
+.
+.IP "" 0
+.
+.P
+should give you access to the complete manual\.
diff --git a/support/texdoc/doc/texdoc.pdf b/support/texdoc/doc/texdoc.pdf
new file mode 100644
index 0000000000..d897017714
--- /dev/null
+++ b/support/texdoc/doc/texdoc.pdf
Binary files differ
diff --git a/support/texdoc/doc/texdoc.tex b/support/texdoc/doc/texdoc.tex
new file mode 100644
index 0000000000..37b4460259
--- /dev/null
+++ b/support/texdoc/doc/texdoc.tex
@@ -0,0 +1,867 @@
+%#!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: