summaryrefslogtreecommitdiff
path: root/support/texdoc/doc
diff options
context:
space:
mode:
Diffstat (limited to 'support/texdoc/doc')
-rw-r--r--support/texdoc/doc/texdoc-doc.cls236
-rw-r--r--support/texdoc/doc/texdoc.116
-rw-r--r--support/texdoc/doc/texdoc.pdfbin76508 -> 82654 bytes
-rw-r--r--support/texdoc/doc/texdoc.tex1327
4 files changed, 860 insertions, 719 deletions
diff --git a/support/texdoc/doc/texdoc-doc.cls b/support/texdoc/doc/texdoc-doc.cls
new file mode 100644
index 0000000000..a9d229b6a7
--- /dev/null
+++ b/support/texdoc/doc/texdoc-doc.cls
@@ -0,0 +1,236 @@
+% Document style for Texdoc user manual
+% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
+% distributed under the terms of GPL v3 or later
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{texdoc-doc}
+ [2020/02/02 Document class for Texdoc user manual]
+
+% class options
+\DeclareOption{draft}{\setlength\overfullrule{5pt}}
+\ProcessOptions\relax
+
+% remove "draft" from global options list
+% (code from https://tex.stackexchange.com/questions/33245/)
+\def\@clearglobaloption#1{%
+ \def\@tempa{#1}%
+ \def\@tempb{\@gobble}%
+ \@for\next:=\@classoptionslist\do
+ {\ifx\next\@tempa
+ \message{Cleared option \next\space from global list}%
+ \else
+ \edef\@tempb{\@tempb,\next}%
+ \fi}%
+ \let\@classoptionslist\@tempb
+ \expandafter\ifx\@tempb\@gobble
+ \let\@classoptionslist\@empty
+ \fi}
+\@clearglobaloption{draft}
+
+% basic dependency
+\LoadClass[a4paper,oneside,parskip=half-]{scrartcl}
+\RequirePackage[british]{babel}
+\RequirePackage{needspace}
+\RequirePackage{xunicode}
+\RequirePackage{fancyvrb}
+\RequirePackage{xparse}
+
+% font settings
+\RequirePackage{fontspec}
+\defaultfontfeatures{Ligatures=TeX}
+\setmainfont{DejaVuSerif}
+\setsansfont{DejaVuSans}
+\setmonofont{DejaVuSansMono}
+\renewcommand{\familydefault}{\sfdefault}
+
+% for math
+%\RequirePackage{unicode-math}
+%\setmathfont[math-style=ISO,bold-style=ISO]{TeX Gyre DejaVu Math}
+
+\setkomafont{title}{}
+\setkomafont{subtitle}{\Large}
+\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
+
+% headers
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.5\baselineskip]{section}
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.3\baselineskip]{subsection}
+
+% colors
+\RequirePackage{xcolor}
+\definecolor{links}{named}{violet}
+\definecolor{special}{rgb}{0,0.5,0}
+\definecolor{code}{rgb}{0,0,0.6}
+
+% list environments
+\RequirePackage{enumitem}
+\newlength\lssep \setlength\lssep{\smallskipamount}
+\setlist{noitemsep, topsep=\lssep, partopsep=\lssep}
+
+% hyperref and bookmark
+\RequirePackage[
+ colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links,
+ bookmarks=true, bookmarksnumbered=true, bookmarksopen=true,
+ bookmarksopenlevel=2]{hyperref}
+\RequirePackage{bookmark}
+
+% text styles
+\DeclareUrlCommand\path{\urlstyle{tt}\color{links}}
+\DeclareTextFontCommand{\emph}{\color{code}}
+
+% for metadata
+\AtBeginDocument{%
+ \bgroup
+ \def\and{, }%
+ \hypersetup{%
+ pdftitle={\@title: \@subtitle},
+ pdfauthor={\@author},
+ pdfsubject={Texdoc's user manual},
+ pdfkeywords={Texdoc, TeX Live, manual, documentation}}
+ \egroup}
+\RequirePackage[yyyymmdd]{datetime}
+\renewcommand{\dateseparator}{-}
+
+% title (overwrite \@maketitle from scrartcl)
+\newcommand*{\pkgurl}[1]{\gdef\@pkgurl{\url{#1}}}
+\renewcommand*{\@maketitle}{%
+ \global\@topnum=\z@
+ \setparsizes{\z@}{\z@}{\z@\@plus 1fil}\par@updaterelative
+ \ifx\@titlehead\@empty \else
+ \begin{minipage}[t]{\textwidth}
+ \usekomafont{titlehead}{\@titlehead\par}%
+ \end{minipage}\par
+ \fi
+ \null
+ \vskip 2em%
+ \begin{center}%
+ \ifx\@subject\@empty \else
+ {\usekomafont{subject}{\@subject \par}}%
+ \vskip 1.5em
+ \fi
+ {\usekomafont{title}{\huge \@title \par}}%
+ \vskip .5em
+ {\ifx\@subtitle\@empty\else\usekomafont{subtitle}\@subtitle\par\fi}%
+ \vskip .1em
+ {\ifx\@pkgurl\@empty\else\usekomafont{subtitle}\@pkgurl\par\fi}%
+ \vskip 1em
+ {%
+ \usekomafont{author}{%
+ \lineskip .5em%
+ \begin{tabular}[t]{c}
+ \@author
+ \end{tabular}\par
+ }%
+ }%
+ \vskip 1em%
+ {\usekomafont{date}{\@date \par}}%
+ \vskip \z@ \@plus 1em
+ {\usekomafont{publishers}{\@publishers \par}}%
+ \ifx\@dedication\@empty \else
+ \vskip 2em
+ {\usekomafont{dedication}{\@dedication \par}}%
+ \fi
+ \end{center}%
+ \par
+ \vskip 2em
+}
+
+% Low layer settings
+\lastlinefit=500 % e-TeX powered
+\catcode`\ 10\relax % take care of non-breakable spaces
+
+% some macros
+\DeclareRobustCommand{\TL}{\texorpdfstring{\TeX\,\,Live}{TeX Live}}
+\newcommand*{\TexdocML}
+ {\href{http://lists.tug.org/texdoc}{mailing list}}
+\newcommand*{\TexdocRepo}
+ {\href{https://github.com/TeX-Live/texdoc}{GitHub repository}}
+\newcommand*{\ie}{i.e.,\,}
+\newcommand*{\eg}{e.g.,\,}
+\newcommand*{\hyph}{-}
+\newcommand*{\meta}[1]{\bgroup
+ \normalfont\color{special}$\langle$\textit{#1}$\rangle$\egroup}
+\newcommand*{\metatab}{\code{\char`\\t}}
+\newcommand*{\choice}[1]{\bgroup
+ \def\@delim{\def\@delim{\space\char`\|\space}}%
+ \normalfont\color{special}%
+ \@for\@item:=#1\do{\@delim\@item}%
+ \egroup}
+\newcommand*{\code}[1]{\bgroup
+ \chardef\_=`\_\code@font #1\egroup}
+\newcommand*{\sopt}[1]{\hyperlink{cl:#1}{\code{\hyph#1}}}
+\newcommand*{\lopt}[1]{\hyperlink{cl:#1}{\code{\hyph{}\hyph#1}}}
+\newcommand*{\ci}[1]{\bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp@hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \hyperlink{\@tmp@hyname}{\code{#1}}}
+
+% verbatim
+\def\code@font{% code
+ \color{code}\normalfont\ttfamily}
+\fvset{%
+ formatcom=\code@font,
+ defineactive=\makeallfancy,
+ commandchars=\\\{\},
+ codes=\fancyactives}
+\newcommand{\fancyactives}{\catcode`\«\active}
+\newcommand{\makeallfancy}{\makefancyog}
+\bgroup
+ \catcode`\«\active
+ \gdef\makefancyog{\def«##1»{\meta{##1}}}
+\egroup
+
+% manual entries
+\newenvironment{manual@entry}{\begin{list}{}{%
+ \setlength{\leftmargin}{2em}%
+ \setlength{\itemindent}{0pt}%
+ \setlength{\itemsep}{0pt}%
+ \setlength{\parsep}{0pt}%
+ \setlength{\rightmargin}{0em}%
+ }\item}{\end{list}}
+
+\NewDocumentEnvironment{clopt}{ m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\sopt##1{\hypertarget{cl:##1}{\code{\hyph##1}}}%
+ \def\lopt##1{\hypertarget{cl:##1}{\code{\hyph{}\hyph##1}}}%
+ \needspace{3ex}\noindent #1\egroup
+ \IfNoValueF{#2}{\hfill (#2)}%
+ \begin{manual@entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual@entry}}
+
+\NewDocumentEnvironment{confitem}{ m m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp@hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \needspace{3ex}\noindent
+ \hypertarget{\@tmp@hyname}{\code{#1 = #2}}%
+ \IfNoValueF{#3}{\hfill (#3)}%
+ \begin{manual@entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual@entry}}
+
+% code in hors-text
+\newenvironment{htcode}
+ {\SaveVerbatim[samepage]{verbmat}}
+ {%
+ \endSaveVerbatim
+ \par\medskip\noindent\hspace*{2em}%
+ \BUseVerbatim{verbmat}%
+ \par\medskip\@endpetrue
+ }
+
+\DefineShortVerb{\|}
+% EOF
diff --git a/support/texdoc/doc/texdoc.1 b/support/texdoc/doc/texdoc.1
index cf072bd5fc..fb2b79f2ec 100644
--- a/support/texdoc/doc/texdoc.1
+++ b/support/texdoc/doc/texdoc.1
@@ -1,16 +1,16 @@
.\" 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"
+.TH "TEXDOC" "1" "February 2020" "Texdoc 3.2" "Texdoc manual"
.
.SH "NAME"
\fBtexdoc\fR \- find & view documentation in TeX Live
.
.SH "SYNOPSIS"
-\fBtexdoc\fR [OPTION\.\.\.] NAME\.\.\.
+\fBtexdoc\fR [OPTION]\.\.\. NAME\.\.\.
.
.br
-\fBtexdoc\fR [OPTION\.\.\.] ACTION
+\fBtexdoc\fR [OPTION]\.\.\. ACTION
.
.SH "DESCRIPTION"
Try to find appropriate TeX documentation for the specified NAME(s)\. Alternatively, perform the given ACTION and exit\.
@@ -59,10 +59,10 @@ 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\.
+Activate debug output restricted to the categories 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\.
+Available categories: \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
@@ -87,6 +87,7 @@ Print the list of configuration files used\.
Display FILE, given with full path (no searching)\.
.
.SH "ENVIRONMENT"
+The following environment variables can be split by colon and used to set viewers:
.
.TP
\fBBROWSER\fR, \fBBROWSER_texdoc\fR
@@ -112,6 +113,9 @@ Set the command to be used for PDF documents\.
\fBPSVIEWER\fR, \fBPSVIEWER_texdoc\fR
Set the command to be used for PS documents\.
.
+.P
+The following environment variables are also used:
+.
.TP
\fBLANG\fR, \fBLC_ALL\fR and so on
Set the locale (which will influence on the search results)\.
@@ -152,7 +156,7 @@ Texdoc home page: \fIhttp://tug\.org/texdoc/\fR
Source: \fIhttps://github\.com/TeX\-Live/texdoc\fR
.
.SH "COPYRIGHT"
-Copyright 2018 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining\.
+Copyright 2008\-2020 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, the TeX Live Team\.
.
.br
License: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\.
diff --git a/support/texdoc/doc/texdoc.pdf b/support/texdoc/doc/texdoc.pdf
index d897017714..d414706520 100644
--- a/support/texdoc/doc/texdoc.pdf
+++ b/support/texdoc/doc/texdoc.pdf
Binary files differ
diff --git a/support/texdoc/doc/texdoc.tex b/support/texdoc/doc/texdoc.tex
index 37b4460259..e1ab840ace 100644
--- a/support/texdoc/doc/texdoc.tex
+++ b/support/texdoc/doc/texdoc.tex
@@ -1,603 +1,530 @@
%#!xelatex
% Texdoc user manual
-% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008-2020 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}
+\documentclass{texdoc-doc}
\title{Texdoc}
-\subtitle{Find \& view documentation in \texlive\\
- \href{https://tug.org/texdoc/}{https://tug.org/texdoc/}}
+\subtitle{Find \& view documentation in \TL}
+\pkgurl{https://tug.org/texdoc/}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
-\date{v3.1\quad \today}
+\date{v3.2\quad \today}
\begin{document}
+
\VerbatimFootnotes
\maketitle
-\section{Quick guide}
-
-\subsection{Basics}
+\section{Quick Guide}
-Texdoc is a command line tool which find and view documentation in \texlive.
-If you type
+Texdoc is a command-line tool to find and view documents in {\TL}. Typing
%
-\begin{quote}
-|texdoc «name»|
-\end{quote}
+\begin{htcode}
+texdoc «name»
+\end{htcode}
%
-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
+in your command line, you will see a document of the |«name»| package is popped
+up. Of course, you have to replace |«name»| with the actual name of a package.
+To look up the documentation of more than one packages at once, just give
+multiple |«name»|s as arguments.
+
+\subsection{Modes}
+\label{sec:modes}
+
+Texdoc has several modes that determine how results will be returned. The
+default is \emph{view} mode, which opens the first, that is supposedly the
+best, result with a suitable viewer. It is rather handy when you know what you
+want to read. On the other hand, there may be other relevant documents for the
+given |«name»|, which are ignored in the view mode.
+
+In the \emph{list} mode, Texdoc lists all relevant documentation and ask you
+which one you want to view. This mode is useful when there are other
+interesting sources of information in addition to the main documentation of a
+package.
+
+There is also a \emph{mixed} mode, intended to get the best of the view mode
+and list mode: if there is only one good result, then Texdoc opens it in a
+viewer, like in the view mode. Otherwise, it offers you a menu, like in the
+list mode.
+
+By default, Texdoc hides some results, which expected to be less relevant,
+unless it cannot find any relevant result. In the \emph{showall} mode, Texdoc
+always shows all results, including bad ones.
+
+A couple of command-line options are available for selecting the mode to
+execute: \sopt{w} (\lopt{view}) for the view mode, \sopt{m} (\lopt{mixed}) for
+the mixed mode, \sopt{l} (\lopt{list}) for the list mode, and \sopt{s}
+(\lopt{showall}) for the showall mode.
+
+If you have your favorite mode and always use it, you may not want to keep
+typing the same option. The next section describes how to customize Texdoc
+using its configurations files.
+
+\subsection{Configuration files}
+\label{sec:quick-file}
+
+The configuration file enables you to tweak Texdoc in many ways. You can use
+the \lopt{files} option to know where to put your personal configuration file;
+you may need to create this file, possibly with some parent directories. If you
+want to know the full list of possible configuration files, see
+Section~\ref{sec:prec}.
+
+To set your favorite mode, just insert a line |\ci{mode} = «mode»| in your
+personal configuration file, where |«mode»| is one of |view|, |mixed|, |list|,
+and |showall|. Though your preferred language is usually detected automatically
+by getting the system locale, you can set it explicitly with a line
+|\ci{lang} = «2-letter code»| in the configuration file.
+
+\subsection{Viewers}
+\label{sec:viewer}
+
+The way of Texdoc 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}
+You may want to use a different viewer for some types of documents. This can be
+achieved by setting the various \ci{viewer\_\meta{ext}} configuration items,
+where |«ext»| is an extension corresponding to a file type. For example, if
+you want to set \code{xpdf} as your default PDF viewer, and run it in the
+background, insert the line |viewer_pdf = xpdf %s &| in your configuration
+file. Herein, |%s| is a place holder for the name of the file to view.
-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.
+\subsection*{\underline{You can stop reading now}}
-The final part is a full reference including a few points omitted in the
-present and next parts.
+The following parts explain the mechanisms of Texdoc for finding the best
+results and how to customize them. We have been trying hard to optimize the
+default configuration values so that normal users do not need to fiddle with
+it. Thus, the following parts are useful only when you are curious or have
+special needs.
\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}
+\section{Controlling Texdoc}
-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.
+\subsection{Command-line options}
+\label{sec:cl}
+The full usage of Texdoc can be summarized as follows:
+%
\begin{htcode}
- adjscore /Makefile = -1000
- adjscore /tex-virtual-academy-pl/ = -50
- adjscore(tex) texdoc = -10
+texdoc «names»
+texdoc «options» «names»
+texdoc «action»
+texdoc «options» «action»
\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}
+We have tried to implement a GNU-compatible option parser. Short options, each of
+which consists of a single letter, must start with a single hyphen |-|.
+Multiple short options can be specified with a single hyphen, \eg |-vl| is
+equivalent to |-v -l|. Long options have to be following double hyphens |--|.
+All options must be specified before the first argument. A String beginning
+with a hyphen after the first argument will be treated as an argument starting
+with a hyphen.
-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}
+Some options are called action options, which can be used for |«action»| in the
+above usage. Four actions are available:
+\begin{clopt}{\sopt{h}, \lopt{help}}
Shows a quick help message (namely a list of command-line options) and exit
successfully.
+\end{clopt}
-\begin{cmdsubsub}{-V, --version}{cl-V}
- -V, --version
-\end{cmdsubsub}
-
+\begin{clopt}{\sopt{V}, \lopt{version}}
Shows the current version of the program and exit successfully.
+\end{clopt}
-\begin{cmdsubsub}{-f, --files}{cl-f}
- -f, --files
-\end{cmdsubsub}
-
+\begin{clopt}{\sopt{f}, \lopt{files}}
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|.
+and ``disabled'' files are shown (see~\ci{lastfile\_switch}). To show ``not
+found'' files as well, you can use \lopt{verbose}.
+\end{clopt}
-\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,
+\begin{clopt}{\code{\lopt{just-view} \meta{file}}}
+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.
+\end{clopt}
+
+Some normal options such as \sopt{v} are effective for some actions but note
+that you have to specify such options \emph{before} the action option. Options
+after an action option will be ignored.
+
+The followings are other normal command-line options:
+
+\begin{clopt}{\sopt{w}, \lopt{view}}[default]
+Set \ci{mode} to |view|. Texdoc will open the best results it found by the best
+application it knows. See Section~\ref{sec:modes}.
+\end{clopt}
+
+\begin{clopt}{\sopt{l}, \lopt{list}}
+Set \ci{mode} to |list|. Texdoc will show the lists of all relevant documents
+it found and ask you which to open. When used with the \lopt{nointeract}
+option, Texdoc will just show the lists of documents and exist successfully.
+\end{clopt}
+
+\begin{clopt}{\sopt{m}, \lopt{mixed}}
+Set \ci{mode} to |mixed|. If Texdoc finds only a document for your keyword,
+then it opens it, and if it finds multiple, then it will behave like in the
+|list| mode.
+\end{clopt}
+
+\begin{clopt}{\sopt{s}, \lopt{showall}}
+Set \ci{mode} to |showall|. It also behave like in a |list| mode, but show all
+the documents it found including documents which seem to be not a good result.
+\end{clopt}
+
+\begin{clopt}{\sopt{i}, \lopt{interact}}[default]
+Texdoc may require user reactions, \eg ask you which document to open in the
+|list| mode. Internally, this sets \ci{interact\_switch} to |true|.
+\end{clopt}
+
+\begin{clopt}{\sopt{I}, \lopt{nointeract}}
+If this is specified, Texdoc will never request any input from users.
+Internally, this sets \ci{interact\_switch} to |false|.
+\end{clopt}
+
+\begin{clopt}{\sopt{M}, \lopt{machine}}
+This make the result list of Texdoc machine-readable. Only effective for the
+|list| mode and its friends. This option implies \lopt{nointeract}.
+Internally, this sets \ci{machine\_switch} to |true|.
+\end{clopt}
+
+\begin{clopt}{\sopt{q}, \lopt{quiet}}
+This suppress warnings and most error messages. Internally, this sets
+\ci{verbosity\_level} to minimum.
+\end{clopt}
+
+\begin{clopt}{\sopt{v}, \lopt{verbose}}
+Make Texdoc to print additional information such as viewer commands which are
+invoked by the program. Internally, this sets \ci{verbosity\_level} to maximum.
+\end{clopt}
+
+\begin{clopt}{%
+ \code{\sopt{d} \meta{list}}, \code{\lopt{debug}=\meta{list}},
+ \sopt{D}, \lopt{debug}}
+This sets \ci{debug\_list} to show dubbging information in the specified
+category. You can specify multiple categories with a comma-separated list. If
+you specify |-D| or |--debug| without specifying a list, it activates all
+available debug categories.
+\end{clopt}
+
+\begin{clopt}{\code{\sopt{c} \meta{name}=\meta{value}}}
+This enables you to set arbitrary configuration items |«name»| to |«value»|
+from the command-line. See Section~\ref{sec:conf} for the list of all available
+configuration items.
+\end{clopt}
+
+\subsection{Environment variables}
+\label{sec:envvar}
+
+Some environment variables affect the behavior of Texdoc. The environment
+variables can be roughly categorized into three groups.
+
+First, as well as other programs in {\TL}, searching path for the Texdoc are
+determined with the Kpathsea variables like |TEXMF*|. The mechanism of Kpathsea
+is complex, so please refer to `the {\TL} Guide', which supposed to be open by
+|texdoc texlive|, and the document of Kpathsea for the details. Usually, Texdoc
+searches documents for the |TEXMF| trees including |TEXMFDIST|, |TEXMFLOCAL|,
+and |TEXMFHOME| and trees specified in |TEXDOCS|. It also self-locates its own
+program using |TEXMF| search path. In addition, Texdoc uses |TEXMFROOT| and
+|TEXMFVAR| to look for the tlpdb database and the cache respectively.
+
+Second, the viewers for opening documents can be controlled by some environment
+variables. They all correspond to some \ci{viewer\_\meta{ext}}
+setting.\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. These variables can be split by colon |:| and the first non-nil
+occurrence is used. If a viewer command contains colon, please specify it by
+\ci{viewer\_\meta{ext}}.
+%
+\begin{center}
+\begin{tabular}{lll}
+Variable & Use for & Configuration item \\ \hline
+|BROWSER| & HTML files & |viewer_html| \\
+|DVIVIEWER| & DVI files & |viewer_dvi| \\
+|MDVIEWER| & Markdown files & |viewer_md| \\
+|PAGER| & Text files & |viewer_txt| \\
+|PDFVIEWER| & PDF files & |viewer_pdf| \\
+|PSVIEWER| & PS files & |viewer_ps| \\
+\end{tabular}
+\end{center}
-\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}
+Third, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
+are used for the default value of \ci{lang}.
-Set |interact_switch| to true (or false), see~\ref{cf-interact_switch}.
+\subsection{Precedence of configuration sources}
+\label{sec:prec}
-\begin{cmdsubsub}{-M, --machine}{cl-M}
- -M, --machine
-\end{cmdsubsub}
+Values for a particular setting can come from several sources. The sources are
+looked at 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}
-Set |machine_switch| to true, see~\ref{cf-machine_switch}.
+The configuration files are found in the directories \path{TEXMF/texdoc}, where
+\path{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 {\TL}
+ 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
+ {\TexdocRepo} for instructions on running the development version.
+\end{enumerate}
-\begin{cmdsubsub}{-q, --quiet}{cl-q}
- -q, --quiet
-\end{cmdsubsub}
+\subsection{Exit codes}
+\label{sec:exit}
-Set |verbosity_level| to minimum, see~\ref{cf-verbosity_level}.
+The status of Texdoc, which is whether or not it was successfully executed and
+an expected result was delivered, can be grasped by seeing its exit code. This
+will be useful to manage Texdoc by other programs. The current exit codes of
+Texdoc are:
+%
+\begin{description}[left=2em]
+\item[\code{0}] Success.
+\item[\code{1}] Internal error.
+\item[\code{2}] Usage error.
+\item[\code{3}] No documentation found.
+\end{description}
-\begin{cmdsubsub}{-v, --verbose}{cl-v}
- -v, --verbose
-\end{cmdsubsub}
+\section{Customizing the Search Results}
-Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}.
+\subsection{An overview of how Texdoc works}
-\begin{cmdsubsub}{-d, -D, --debug}{cl-d}
- -d «list», --debug=«list», -D, --debug
-\end{cmdsubsub}
+When you type |texdoc «keyword»|, first filenames related to the |«keyword»|
+are collected from the two following sources.
+%
+\begin{enumerate}
+\item the |TEXMF| trees containing documentation that specified by the
+ \href{https://www.tug.org/kpathsea/}{kpathsea} variable |TEXDOCS|: Texdoc
+ collects all files containing |«keyword»| in their filenames or in the names
+ of their parent directories.
+\item the {\TL} Database (|texlive.tlpdb|): Texdoc searches for packages named
+ |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be |sty|
+ or |cls|, and collects all document files of the found packages.
+\end{enumerate}
-Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug|
-without specifying a list, activates all available debug items.
+Second, the collected filenames are filtered by their extensions. After
+filtering, only files with known extensions (listed in \ci{ext\_list}) remain.
+If Texdoc cannot find any documentation, the fuzzy search will find the closest
+package name to the |«keyword»| and it will recollect document files (see
+Section~\ref{sec:fuzzy}).
+
+Third, the collected filenames are given numeric scores by using some
+heuristics. For example, a filename |«keyword».pdf| is good, and thus gets a
+high score. A name |«keyword»-«lang».pdf| is also good and gets a higher score
+if the |«lang»| is the preferred language code in your configuration. In
+addition, there are several rules such as ``a name |«keyword»-doc| always wins
+over any names |«keyword»whatever|'' and ``files under a directory named
+exactly |«keyword»| get bonuses''. Scores may also be adjusted based on the
+extensions and some known names or subwords. For example, by default,
+|Makefile|s get very low scores because basically they are not
+documents.\footnote{Nevertheless, they often end up in the |doc| trees,
+because in {\TL}, sources of documents are usually in the same directory as the
+documents themselves. Other source files for documents are discriminated by
+their extensions.}
+
+Finally, a file with the highest score is opened with a viewer, or the list
+of results is shown, depending on the current mode. Usually, only results with
+positive scores are displayed, except in the |showall| mode. Results with very
+bad scores, that are lower than |-100|, are never displayed.
+
+This model for searching and scoring is efficient, but unfortunately, it is not
+perfect: Texdoc may sometimes need a hint, either to find a relevant file or,
+more likely, to recognize which of the found files is the best. For example,
+suppose you are looking for a document of the {\LaTeX} package |shortvrb|.
+Texdoc will successfully find |shortvrb.sty| in the {\TL} package |latex|.
+However, Texdoc will not be able to sort a number of documents in the |latex|
+package correctly because none of them contains the string |shortvrb|.
+
+For such cases, \emph{aliases} are useful: in the default configuration file,
+|shortvrb| is aliased to |base/doc|, so that Texdoc primarily look for
+|base/doc| when you type |texdoc shortvrb|. Note that Texdoc will also look for
+the original keyword, and that a name can be aliased to more than one new
+name.
-\begin{cmdsubsub}{-c}{cl-c}
- -c «name»=«value»
-\end{cmdsubsub}
+\subsection{Aliases}
+\label{sec:alias}
-Set configuration item |«name»| to |«value»|. This is a general way to access
-any configuration items listed in \ref{ss-conf} from command line.
+Aliases can be set in configuration files of Texdoc with the following syntax:
+%
+\begin{htcode}
+alias «original keyword» = «name»
+alias(«score») «original keyword» = «name»
+\end{htcode}
+%
+A number of aliases are already set in the default configuration file. You can
+also define your own aliases in your personal configuration files (see
+Section~\ref{sec:quick-file} or \ref{sec:prec} to know where is that). For example,
+you can add a line
+%
+\begin{htcode}
+alias td = texdoc
+\end{htcode}
+%
+to the file to alias |td| to |texdoc|. Then, files in the doc trees matching
+exactly with |texdoc|, \ie this document |texdoc.pdf|, will be added to the
+result list when you search for the keyword |td|.
+
+By default, files match with the aliased name get a score of |10|. This score
+is greater than any result of heuristic scoring. It means that results found
+via aliases will always be ranked higher than results found for the original
+keyword. If you want the results associated with a particular alias to have a
+custom score instead of the default score |10|, you can use the optional
+argument to the |alias| directive. This can be useful if you associate multiple
+aliases to a keyword and want to specify the priorities for them.
+
+In addition, 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 when searching for |«keyword»|. Files match with these language-based
+aliases get additional bonus scores so that they win over the results for
+language-independent aliases.
+
+For concrete examples, please have a look at the default configuration file,
+which can be found in the last line of the output for |texdoc -f|. If you think
+aliases you defined locally should be added to the default configuration,
+please share the idea to the {\TexdocML} or {\TexdocRepo}.
-\subsection{Environment variables}\label{ss-envvar}
+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, add a line |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.
-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.
+Here are some notes for aliases. First, they are case-insensitive. Second, they
+do not work recursively: only aliases set to the original keyword are used.
+Third, results found for aliases always get the score defined by the |alias|
+directive (|10| by default). The adjustments described in the other subsections
+are not applied to results for aliases.
-\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}
+\subsection{Score adjustments}
+\label{sec:score}
-Also, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
-are used for the default value of |lang|.
+Scores can be arbitrary adjusted by using the |adjscore| directive in the
+configuration files. The adjustment can be done either for global, \ie for any
+keywords, or a particular keyword. The syntax is as follow:
+%
+\begin{htcode}
+adjscore «pattern» = «score adjustment»
+adjscore(«keyword») «pattern» = «score adjustment»
+\end{htcode}
+%
+When the optional argument |«keyword»| is specified, the adjustment will be
+applied only when a user searches for the |«keyword»|. Otherwise, the
+adjustment applied always for the |«pattern»|.
-\subsection{Configuration items}\label{ss-conf}
+Here are a few examples from the default configuration file.
-\subsubsection{Structure of configuration files}\label{sss-sonf-struct}
+\begin{htcode}
+adjscore /Makefile = -1000
+adjscore /tex-virtual-academy-pl/ = -50
+adjscore(tex) texdoc = -10
+\end{htcode}
+%
+Herein, all files named |Makefile|, and those with suffixes, \eg |Makefile.in|,
+will be eliminated from results: by adjusting their score with such a large
+negative value, their final score will be less than |-100|. Which means they
+will never be displayed. Files from the |tex-virtual-academy-pl| directory, on
+the other hand, are not eliminated but get a negative adjustment, since they
+are a common source of ``fake'' matches which hide better results. The third
+line gives a minus adjustment for results containing |texdoc| only when the
+searched keyword is |tex|. Otherwise, such results would get high scores
+because the heuristic scoring would assume |texdoc| is the name of
+documentation for {\TeX} itself. The adjustment value |-10| is enough to ensure
+that those results will have a negative score, so the files containing |texdoc|
+will not be displayed unless |showall| mode is used.
+
+Note that the values of scores, such as the default score for aliases and the
+range of heuristic scores, may be changed in a future version of Texdoc.
+Therefore, you may need to adapt your score adjustments after updating Texdoc
+in the future.
+
+\subsection{Extensions and basenames of files}
+\label{sec:ext}
+
+File extensions regarded as documents by Texdoc can be specified with the
+configuration item \ci{ext\_list}. By default, files with extensions |pdf|,
+|html|, |htm|, |txt|, |md|, |ps|, and |dvi| and files without extension are
+recognized as documents.
+
+During the scoring process, the configuration item |badext_list| is also used:
+files with a ``bad'' extension appearing in this list will get a lesser score.
+
+In the practical filenames, things which are not actually extensions can follow
+dots, \eg |readme.fr| and |readme.texlive|. Thus, in addition to the lists of
+known extensions, Texdoc has lists for known basenames: \ci{basename\_list} and
+\ci{badbasename\_list}. These configuration items are respectively similar to
+\ci{ext\_list} and \ci{badext\_list}. In short, a file will be selected if
+either its extension or its basename is known, and get a lesser score if either
+is known to be ``bad''.
+
+\subsection{Common filenames}
+\label{sec:common-names}
+
+Document filenames of packages are often in the form of |«package»-doc|.
+Respecting this culture in the {\TeX} community, Texdoc gives a special score
+for files named |«package»«suffix»|, where |«suffix»| is an element of the list
+\ci{suffix\_list}. Please refer to the shipped configuration file for the
+default setting. Also, feel free to suggest additional elements for the list to
+the {\TexdocML} with a real-life example.
+
+\subsection{Fuzzy search}
+\label{sec:fuzzy}
+
+When the normal search cannot find any document in {\TL}, Texdoc will execute a
+fuzzy search. The fuzzy search tries to find the closest name of a package in
+{\TL}\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 the fuzzy search are shown in an info
+message, which can be seen by using the command-line option |-v|.
+
+The default allowance of Levenshtein distance is |5|. You can change this
+allowance by using the configuration item \ci{fuzzy\_level}. Results of fuzzy
+search could be different among executions if multiple package names have the
+same Levenshtein distance to the input.
+
+\section{Configuration items}
+\label{sec:conf}
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»
+«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}).
+directives have already been presented (Section~\ref{sec:alias} and
+\ref{sec: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
@@ -606,56 +533,48 @@ 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.
+\item |_list|, then |«value»| is a coma-separated list of strings. Spaces
+ around commas are 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| and |_lines|, 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{confitem}{mode}
+ {\choice{view, list, mixed, showall}}[default: \code{view}]
+Set the mode to the given value. The various modes have been described
+in Section~\ref{sec:modes}.
+\end{confitem}
+
+\begin{confitem}{interact\_switch}{\choice{true, false}}[default: \code{true}]
+Turn on or off interaction. 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.
+\end{confitem}
+
+\begin{confitem}{suffix\_list}{\meta{list}}[default: empty]
+Set the list of known suffixes to |«list»| (see
+Section~\ref{sec:common-names}). Default is the empty list, but see the
+shipped configuration file for more.
+\end{confitem}
+
+\begin{confitem}{ext\_list}
+ {\meta{list}}[default: \code{pdf, html, htm, txt, md, dvi, ps,}]
+Set the list of recognised extensions to |«list»|. 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{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!
+\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,
@@ -669,171 +588,150 @@ 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
+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
+\end{confitem}
+
+\begin{confitem}{badext\_list}{\meta{list}}[default: \code{txt}]
+Set the list of ``bad'' extensions to |«list»|. Files with those extensions get
+a malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
+
+\begin{confitem}{basename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
+Set the list of ``known'' base names to |«list»|. 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.
+\end{confitem}
+
+\begin{confitem}{badbasename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
+
+Set the list of ``bad'' base names to |«list»|. Files with those names get a
+malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
+
+\begin{confitem}{viewer\_\meta{ext}}{\meta{command}}
+Set the viewer command for files with extension |«ext»| to |«command»|. For
+files without an extension, |viewer_txt| is used. Note that there is no
+|viewer_| variable. In |«command»|, |%s| can be used as a placeholder for the
+filename, which is otherwise inserted at the end of the command. The command
+can be an arbitrary shell construct.
+\end{confitem}
+
+\begin{confitem}{lang}{\meta{2-letter code}}
+Set your preferred language. By default, it reflects your system's locale.
+\end{confitem}
+
+\begin{confitem}{verbosity\_level}{\meta{number}}[default: \code{2}]
+Set the verbosity level to |«number»|. 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).
+\end{confitem}
-\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}
+\begin{confitem}{debug\_list}{\meta{list}}[default: empty]
+Set the list of activated debug categories. Available debug categories 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.
+\end{confitem}
+\begin{confitem}{max\_lines}{\meta{number}}[default: \code{20}]
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}
+mixed or showall mode. This setting has no effect if interaction is disabled.
+\end{confitem}
-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{confitem}{machine\_switch}{\choice{true, false}}[default: \code{false}]
+Turn on or off machine-readable output. 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»
+«argument»\metatab«score»\metatab«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)
+(mainly useful if there were many arguments), {\metatab} 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
+unstructured description, both taken from the CTAN catalogue (via the {\TL}
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}
-
+\end{confitem}
+
+\begin{confitem}{zipext\_list}{\meta{list}}[default: empty]
+List of supported extensions for zipped files. 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).
+
+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.
+
+Remark: {\TL} doesn't ship compressed documentation files, so this option is
+mainly useful with re-packaged version of {\TL} that do, for example in Linux
+distributions.
+\end{confitem}
+
+\begin{confitem}{unzip\_\meta{zipext}}{\meta{command}}[no default]
+The unzipping command for compressed files with extension |«zipext»|. Define
+one for each item in \ci{zipext\_list}. The command must print the result on
+stdout, like |gzip -d -c| does.
+\end{confitem}
+
+\begin{confitem}{rm\_file}{\meta{command}}[default: \code{rm -f}]
+Commands for removing files on your system. Only useful for zipped documents
+(see \ci{zipext\_list}).
+\end{confitem}
+
+\begin{confitem}{rm\_dir}{\meta{command}}[default: \code{rmdir}]
+Commands for removing directories on your system. Also only useful for zipped
+documents (see \ci{zipext\_list}).
+\end{confitem}
+
+\begin{confitem}{lastfile\_switch}{\choice{true, false}}[default: \code{false}]
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).
+\end{confitem}
-\begin{cmdsubsub}{fuzzy_level}{cf-fuzzy_level}
- fuzzy_level = «n»
-\end{cmdsubsub}
+\begin{confitem}{fuzzy\_level}{\meta{number}}[default: \code{5}]
+Set the allowance of Levenshtein distance to |«number»| for fuzzy search. At
+level~|0|, the fuzzy search feature is disabled.
+\end{confitem}
-Set the allowance of Levenshtein distance to |«n»| for the fuzzy search
-(default: 5). At level 0, the fuzzy search feature is disabled.
+\begin{confitem}{texlive\_tlpdb}{\meta{path}}[no default]
+This enables you to specify the |«path»| for the database |texlive.tlpdb| which
+Texdoc uses for searching documents. By default, Texdoc uses
+\path{TEXMFROOT/tlpkg/texlive.tlpdb}. Usually, you don't have to (or should
+not) set this configuration item. This is only useful when you want to use
+Texdoc within a {\TL}-based {\TeX} distribution which does not ship
+|texlive.tlpdb|.
+\end{confitem}
-\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{sec:licence}
-\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.
+The current version of Texdoc program and its documentation are copyright
+2008--2020 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} 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
@@ -851,17 +749,20 @@ 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.
+\item Contributions from Reinhard Kotucha (2008).
+\item First texlua versions by Frank K\"uster (2007).
+\item Original shell script version by Thomas Esser, David Aspinall, and Simon
+ Wilkinson.
\end{itemize}
\bigskip
-\begin{center}\Large\bfseries
- Happy {\TeX}ing!
+
+\begin{center}
+\Large\bfseries
+Happy {\TeX}ing!
\end{center}
\end{document}
-% vim: ambiwidth=single spell:
+% vim: set ambiwidth=single spell: