texdoc (2feb20)

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

16 files changed, 1143 insertions, 857 deletions

diff --git a/Master/texmf-dist/doc/man/man1/texdoc.1 b/Master/texmf-dist/doc/man/man1/texdoc.1
index cf072bd5fce..fb2b79f2ec5 100644
--- a/Master/texmf-dist/doc/man/man1/texdoc.1
+++ b/Master/texmf-dist/doc/man/man1/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/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf b/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf
index b3af528aebe..cb13587285b 100644
--- a/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf
diff --git a/Master/texmf-dist/doc/support/texdoc/NEWS b/Master/texmf-dist/doc/support/texdoc/NEWS
index 430c925d24f..aae48497e53 100644
--- a/Master/texmf-dist/doc/support/texdoc/NEWS
+++ b/Master/texmf-dist/doc/support/texdoc/NEWS
@@ -2,6 +2,13 @@ NEWS for texdoc
 ===============
 (This file public domain.)
 
+Version 3.2 (TeX Live 2020)
+===========================
+- Improved the scoring scheme to prioritize the latex tree than the latex-dev
+- Support invoking the program with absolute paths
+- The document was entirely rewritten
+- Other small improvements and bug fixes
+
 Version 3.1 (TeX Live 2019)
 ===========================
 - New option -c: changing configure temporally
diff --git a/Master/texmf-dist/doc/support/texdoc/README.md b/Master/texmf-dist/doc/support/texdoc/README.md
index f0da3fc2341..b71ab747430 100644
--- a/Master/texmf-dist/doc/support/texdoc/README.md
+++ b/Master/texmf-dist/doc/support/texdoc/README.md
@@ -1,4 +1,4 @@
-# Texdoc v3.1 (2019-03-28)
+# Texdoc 3.2 (2020-02-02)
 
 [![Build Status](https://travis-ci.org/TeX-Live/texdoc.svg?branch=master)](https://travis-ci.org/TeX-Live/texdoc)
 [![Build status](https://ci.appveyor.com/api/projects/status/uq28ms7eba7ns6d3/branch/master?svg=true)](https://ci.appveyor.com/project/wtsnjp/texdoc/branch/master)
@@ -106,7 +106,7 @@ More specific information (e.g., TODO) can be found in the Wiki of our GitHub re
 
 ## Copyright and License
 
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
 
 This package is distributed under the terms of the GNU General Public License as published by the Free Software Foundation, either [version 3](./COPYING) of the License, or (at your option) any later version.
 
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls b/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
new file mode 100644
index 00000000000..a9d229b6a71
--- /dev/null
+++ b/Master/texmf-dist/doc/support/texdoc/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/Master/texmf-dist/doc/support/texdoc/texdoc.pdf b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
index d897017714d..d414706520b 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc.tex b/Master/texmf-dist/doc/support/texdoc/texdoc.tex
index 37b44602591..e1ab840ace1 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.tex
+++ b/Master/texmf-dist/doc/support/texdoc/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:
diff --git a/Master/texmf-dist/scripts/texdoc/texdoc.tlu b/Master/texmf-dist/scripts/texdoc/texdoc.tlu
index b8598682364..bc2139435a3 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoc.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoc.tlu
@@ -7,11 +7,39 @@
 -- Note: we keep this file small as much as possible so that make it easier
 --       to install a new version of texdoc in TEXMFHOME.
 
--- setup the kpse library and load texdoclib
+local lfs = require 'lfs'
+local kpse = require 'kpse'
+
+-- setup kpse library
 kpse.set_program_name(arg[-1], 'texdoc')
-local texdoc = require('texdoclib')
 
--- execute
+-- get realpath of this file
+local function realpath(p)
+    if os.type == 'unix' then
+        local h = io.popen(string.format("realpath '%s'", p))
+        local r = h:read('*a')
+        h:close()
+        return r:gsub('\n$', '')
+    else
+        return ''
+    end
+end
+local file = realpath(arg[0])
+
+-- if the file is not in TEXMFMAIN, set temporal TEXMFAUXTREES and TEXMFDIST
+local texmf = file:match('^(.*/texmf[^/]*)/scripts/texdoc/texdoc.tlu$')
+if texmf ~= nil then
+    if texmf ~= kpse.var_value('TEXMFMAIN') then
+        io.stderr:write('Info: ' ..
+            'Running Texdoc not installed in the current TEXMFMAIN.\n')
+        os.setenv('TEXMFAUXTREES', texmf .. ',')
+        os.setenv('TEXMFDIST', ',')
+    end
+end
+
+-- load the library and execute
+local texdoc = require 'texdoclib'
+assert(texdoc.cli, 'Internal error: Texdoc is not installed properly.')
 texdoc.cli.exec()
 
 -- vim: ft=lua:
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
index 16c375b3bad..d430623a41c 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
@@ -5,7 +5,7 @@
 --[[ structure of the alias table
 
 alias = {
-  name1 = {<true or nill> stop, <aliasentry> aliasentry1, ...},
+  name1 = {<true or nil> stop, <aliasentry> aliasentry1, ...},
   ...
 }
 stop == true means further alias directives should be ignored
@@ -22,7 +22,7 @@ score == nil means to use the default score (defined in texdoclib-score.tlu)
 
 -- dependencies
 local texdoc = {
-    config = require('texdoclib-config'),
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
index 3de786ef2c8..95a43b7ddd9 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
@@ -4,11 +4,11 @@
 
 -- dependencies
 local texdoc = {
-    const = require('texdoclib-const'),
-    util = require('texdoclib-util'),
-    config = require('texdoclib-config'),
-    search = require('texdoclib-search'),
-    view = require('texdoclib-view'),
+    const = require 'texdoclib-const',
+    util = require 'texdoclib-util',
+    config = require 'texdoclib-config',
+    search = require 'texdoclib-search',
+    view = require 'texdoclib-view',
 }
 
 -- shortcuts
@@ -21,7 +21,7 @@ local err_print = texdoc.util.err_print
 -- modified Alternative GetOpt
 -- cf. http://lua-users.org/wiki/AlternativeGetOpt
 local function getopt(arg, options)
-    local tmp
+    local tmp = nil
     local tab = {}
     local saved_arg = {table.unpack(arg)}
 
@@ -30,25 +30,36 @@ local function getopt(arg, options)
             table.remove(arg, 1)
             local x = string.find(v, '=', 1, true)
             if x then
-                table.insert(tab, {string.sub(v, 3, x-1), string.sub(v, x+1)})
+                table.insert(tab, {string.sub(v, 3, x - 1), string.sub(v, x+1)})
             else
                 table.insert(tab, {string.sub(v, 3), true})
             end
+
         elseif string.sub(v, 1, 1) == '-' then
             table.remove(arg, 1)
             local y = 2
             local l = string.len(v)
             local jopt
+
             while (y <= l) do
                 jopt = string.sub(v, y, y)
+
                 if string.find(options, jopt, 1, true) then
                     if y < l then
-                        tmp = string.sub(v, y+1)
+                        tmp = string.sub(v, y + 1)
                         y = l
                     else
                         table.remove(arg, 1)
                         tmp = saved_arg[k + 1]
                     end
+
+                    -- check the existence of an argument
+                    if not tmp then
+                        err_print('error',
+                            'Option -%s requires an argument.', jopt)
+                        os.exit(C.exit_error)
+                    end
+
                     if string.match(tmp, '^%-') then
                         table.insert(tab, {jopt, false})
                     else
@@ -59,6 +70,9 @@ local function getopt(arg, options)
                 end
                 y = y + 1
             end
+
+        else
+            if tmp then tmp = nil else break end
         end
     end
 
@@ -67,7 +81,6 @@ end
 
 local function parse_options()
     local curr_arg
-    local action = true
     local cl_config = {}
 
     local function insert_cl_config(key, val, opt_name)
@@ -87,13 +100,13 @@ local function parse_options()
 
         -- action
         if (curr_arg == '-h') or (curr_arg == '--help') then
-            action = 'help'
+            return true, 'help', cl_config
         elseif (curr_arg == '-V') or (curr_arg == '--version') then
-            action = 'version'
+            return true, 'version', cl_config
         elseif (curr_arg == '-f') or (curr_arg == '--files') then
-            action = 'files'
+            return true, 'files', cl_config
         elseif curr_arg == '--just-view' then
-            action = 'view'
+            return true, 'view', cl_config
 
         -- mode
         elseif (curr_arg == '-w') or (curr_arg == '--view') then
@@ -117,8 +130,7 @@ local function parse_options()
 
         -- config
         elseif curr_arg == '-c' then
-            local item, value = string.match(v, '^([%a%d_]+)%s*=%s*(.+)')
-            insert_cl_config(item, value, curr_arg)
+            insert_cl_config(v, nil, curr_arg)
 
         -- debug
         elseif (curr_arg == '-d') or (curr_arg == '--debug') then
@@ -141,7 +153,7 @@ local function parse_options()
         end
     end
 
-    return action, cl_config
+    return true, action, cl_config
 end
 
 --------------------------   process execution   --------------------------
@@ -157,7 +169,7 @@ local function do_action(action)
             '\n\n' .. C.copyright_msg)
         os.exit(C.exit_ok)
     elseif action == 'files' then
-        print(C.fullname .. ' ' .. C.version)
+        print(texdoc.util.w32_path(C.fullname) .. ' ' .. C.version)
         texdoc.config.show_config_files(true)
         os.exit(C.exit_ok)
     elseif action == 'view' then
@@ -189,9 +201,9 @@ end
 
 function M.exec()
     -- parsing command line options
-    local action, cl_config = parse_options()
+    local ok, action, cl_config = parse_options()
 
-    if not action then
+    if not ok then
         os.exit(C.exit_usage)
     end
 
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
index 471fef9fdcb..4eb660873f9 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
@@ -2,9 +2,12 @@
 --
 -- The TeX Live Team, GPLv3, see texdoclib.tlu for details
 
+-- dependencies
+local lfs = require 'lfs'
+
 -- shortcuts
 local M = {}
-local C = require('texdoclib-const')
+local C = require 'texdoclib-const'
 
 -- config is local to this file
 local config = {}
@@ -172,8 +175,20 @@ end
 -- Note: Make sure to set a default value in setup_config_from_defaults()
 --       if relevant.
 local function setup_config_from_cl(cl_config)
+    local err_print = import_function('util', 'err_print')
+
     for _, e in ipairs(cl_config) do
-        set_config_element(e[1], e[2], {src='cl', name=e[3]})
+        if e[3] == '-c' then
+            local item, value = string.match(e[1], '^([%a%d_]+)%s*=%s*(.+)')
+            if item and value then
+                set_config_element(item, value, {src='cl', name='-c'})
+            else
+                err_print('warning',
+                    'Invalid argument "%s" for Option -c. Ignoring.', e[1])
+            end
+        else
+            set_config_element(e[1], e[2], {src='cl', name=e[3]})
+        end
     end
 end
 
@@ -184,6 +199,7 @@ local function setup_config_from_env()
     local function set_config_elt_from_vars(key, vars)
         for _, var in ipairs(vars) do
             local value = os.getenv(var)
+            value = value and string.gmatch(value, '([^:]+)')()
             if value then
                 set_config_element(key, value, {src='env', name=var})
             end
@@ -316,7 +332,7 @@ function M.show_config_files(is_action)
         or function(s) dbg_print('files', s) end
 
     -- show the list of configuration files
-    print_func('Configuration files are:')
+    print_func('Configuration file(s):')
     for i, file in ipairs(config_files) do
         -- if not verbose, do not show "not found" files for -f
         if file.status ~= "not found"
@@ -329,7 +345,7 @@ function M.show_config_files(is_action)
     if is_action then
         print_func('Recommended file(s) for personal settings:')
         local sep = (os.type == 'windows') and ';' or ':'
-        local texmfhomes = string.explode(kpse.var_value('TEXMFHOME'), sep)
+        local texmfhomes = string.explode(kpse.expand_path('$TEXMFHOME'), sep)
         for _, home in ipairs(texmfhomes) do
             print_func(indent .. w32_path(home .. '/texdoc/texdoc.cnf'))
         end
@@ -340,12 +356,20 @@ end -- end scope of config_files
 
 ----------------------   config from locale settings   -------------------------
 
+-- set up the locale from the system setting
+-- Note that luatex set the locale to a neutral value for a reason, so we need
+-- to set the locale (for the category 'all') to nil to ignore it.
 local function setup_config_from_locale()
-    local current = os.setlocale(nil, 'all')
-    os.setlocale('', 'all')
-    local native = os.setlocale(nil, 'time')
-    os.setlocale(current, 'all')
-    local lang = string.match(native, '^[a-z][a-z]')
+    local current, native, lang
+    current = os.setlocale(nil, 'all')  -- save the default value
+    os.setlocale('', 'all')             -- set it to nil temporary
+    native = os.setlocale(nil, 'all')   -- get the actual system locale
+    os.setlocale(current, 'all')        -- put back the default value
+    if native == 'C' then -- the default C locale is en
+        lang = 'en'
+    else
+        lang = string.match(native, '^[a-z][a-z]')
+    end
     if lang then
         set_config_element('lang', lang, {src='loc'})
     end
@@ -381,6 +405,8 @@ local function desktop_environment_viewer()
     end
     if os.getenv('GNOME_DESKTOP_SESSION_ID')
         or string.match(xdg_current_desktop, '.*GNOME.*') then  -- gnome
+        if is_in_path('gio') then return '(gio open %s) &' end
+        -- followings are deplecated commands but keep these for compatibility
         if is_in_path('gvfs-open') then return '(gvfs-open %s) &' end
         if is_in_path('gnome-open') then return '(gnome-open %s) &' end
     end
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
index 5d34bed3f67..9562122d38a 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
@@ -4,7 +4,7 @@
 
 -- use an empty environment that will become texdoc_env.C (see EOF)
 local constants = {}
-local kpse = kpse
+local kpse = kpse or require 'kpse'
 local setfenv = setfenv
 local texdoc_env
 
@@ -21,14 +21,14 @@ end
 -- progname and version
 fullname = kpse.find_file('texdoc/texdoclib', 'lua')
 progname = 'Texdoc'
-version = '3.1'
-release_date = '2019-03-28'
+version = '3.2'
+release_date = '2020-02-02'
 
 -- make sure to update setup_config_from_cl() accordingly
 -- and set a default value in setup_config_from_defaults() if relevant
 usage_msg = [[
-Usage: texdoc [OPTION...] NAME...
-  or:  texdoc [OPTION...] ACTION
+Usage: texdoc [OPTION]... NAME...
+   or: texdoc [OPTION]... ACTION
 
 Try to find appropriate TeX documentation for the specified NAME(s).
 Alternatively, perform the given ACTION and exit.
@@ -63,7 +63,7 @@ Repository: <https://github.com/TeX-Live/texdoc>
 Please email bugs to <texdoc@tug.org>.]]
 
 copyright_msg = [[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
 License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.]]
 
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
index 81e1be2a333..fdc2ef3467f 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
@@ -3,14 +3,14 @@
 -- The TeX Live Team, GPLv3, see texdoclib.tlu for details
 
 -- dependencies
+local md5 = require 'md5'
 local texdoc = {
-    util = require('texdoclib-util'),
-    config = require('texdoclib-config'),
+    util = require 'texdoclib-util',
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
 local M = {}
-local dbg_print = texdoc.util.dbg_print
 
 -- shared variables
 local global_adjscore, spec_adjscore = {}, {}
@@ -73,18 +73,19 @@ local function has_bad_basename(file)
 end
 
 -- compute a heuristic score -10 <= s < 10
-local function heuristic_score(file, pat)
-    dbg_print('score', 'Start heuristic scoring with pattern: ' .. pat)
+local function heuristic_score(file, pat, dbg_score)
+    dbg_score('Start heuristic scoring with pattern: ' .. pat)
+
     -- score management
     local score = -10
     local function upscore(s, reason, force)
         if s > score or force then
             score = s
-            dbg_print('score',
-                'New heuristic score: %.1f. Reason: %s', s, reason)
+            dbg_score('New heuristic score: %.1f. Reason: %s', s, reason)
         end
     end
     local slash = not not string.find(pat, '/', 1, true)
+
     -- look for exact or subword match
     if M.is_exact_locale(file, pat) then
         upscore(5, 'exact match with correct locale')
@@ -93,104 +94,121 @@ local function heuristic_score(file, pat)
     elseif is_subword(file, pat) then
         upscore(1, 'subword match')
     end
+
     -- try derivatives unless pat contains a slash
     if not slash then
         for _, suffix in ipairs(texdoc.config.get_value('suffix_list')) do
-            local deriv = pat..suffix
+            local deriv = pat .. suffix
             if M.is_exact(file, deriv) then
-                upscore(3, 'exact match for derived pattern: ' .. deriv)
+                upscore(4.5, 'exact match for derived pattern: ' .. deriv)
             elseif is_subword(file, deriv) then
-                upscore(2, 'subword match for derived pattern: ' .. deriv)
+                upscore(3.5, 'subword match for derived pattern: ' .. deriv)
             end
         end
     end
+
     -- if extension is bad, score becomes an epsilon
     local ext = texdoc.config.get_value('ext_list')[M.ext_pos(file)]
     if ext and texdoc.config.get_value('badext_list_inv')[ext] and score > 0 then
         upscore(0.1, 'bad extension', true)
     end
+
     -- if basename is bad, score becomes an epsilon
     if has_bad_basename(file) and score > 0 then
         upscore(0.1, 'bad basename', true)
     end
+
     -- bonus for being in the right directory
     if string.find('/' .. file, '/' .. pat .. '/', 1, true) and not slash then
         upscore(score + 1.5, 'directory bonus')
     end
+
     -- done
-    dbg_print('score', 'Final heuristic score: %.1f', score)
+    dbg_score('Final heuristic score: %.1f', score)
     return score
 end
 
 -- set the score of a docfile
 local function set_score(df, original_kw)
     -- scoring is case-insensitive (patterns are already lowercased)
-    local name = string.lower(df.shortname)
-    dbg_print('score', '----------')
-    dbg_print('score', 'Start scoring ' .. df.realpath)
-    dbg_print('score', 'Name used: ' .. name)
+    local name = string.lower(df.normname)
+    local df_id = string.sub(md5.sumhexa(name), 1, 7)
+
+    -- special debugging function
+    local function dbg_score(msg, ...)
+        -- add the hash id prefix to make the outputs grep-friendly
+        local msg = string.format('(%s) ', df_id) .. msg
+        texdoc.util.dbg_print('score', msg, ...)
+    end
+
+    dbg_score('Start scoring ' .. df.realpath)
+    dbg_score('Name used: ' .. name)
+
     -- get score from patterns
     local score = -10
     for _, pat in ipairs(df.matches) do
         local s = -10
         local p = string.lower(pat.name)
-        if pat.original then
-            s = df.tree > -1 and heuristic_score(name, p) or 1
-        elseif M.is_exact(name, p) then
+        if pat.original then  -- non-alias
+            s = df.tree > -1 and heuristic_score(name, p, dbg_score) or 1
+        elseif M.is_exact(name, p) then  -- alias
             local bonus, note = 0, ''
             if pat.locale then
                 bonus, note = 5, ', (language-based)'
             end
-            s = (pat.score or 10) + bonus -- default alias score is 10
-            dbg_print('score',
-                'Matching alias "%s", score: %.1f%s', pat.name, s, note)
+            s = (pat.score or 10) + bonus  -- default alias score is 10
+            dbg_score('Matching alias "%s", score: %.1f%s', pat.name, s, note)
         end
         if s > score then score = s end
     end
-    dbg_print('score', 'Max pattern score: %.1f', score)
+    dbg_score('Max pattern score: %.1f', score)
+
     -- get score from tlp associations
     if score == -10 and df.tlptodoc then
         score = -1
-        dbg_print('score',
-            'New score: %.1f from package name association', score)
+        dbg_score('New score: %.1f from package name association', score)
     end
+
     if score == -10 and df.runtodoc then
         score = -5
-        dbg_print('score',
-            'New score: %.1f from sty/cls association', score)
+        dbg_score('New score: %.1f from sty/cls association', score)
     end
+
     -- bonus for metadata
     if df.details then
         if string.find(string.lower(df.details), 'readme') then
             score = score + 0.1
-            dbg_print('score', 'Catalogue "readme" bonus: +0.1')
+            dbg_score('Catalogue "readme" bonus: +0.1')
         else
             score = score + 1.5
-            dbg_print('score', 'Catalogue details bonus: +1.5')
+            dbg_score('Catalogue details bonus: +1.5')
         end
     end
+
     -- adjust from keyword-specific tables
     if df.tree > -1 and spec_adjscore[original_kw] then
         for pat, val in pairs(spec_adjscore[original_kw]) do
             if val and is_subword('/' .. name, pat) then
                 score = score + val
-                dbg_print('score',
-                    'Adjust by %.1f from specific pattern "%s"', val, pat)
+                dbg_score('Adjust by %.1f from specific pattern "%s"', val, pat)
             end
         end
     end
+
     -- adjust from global tables
     if df.tree > -1 then
         for pat, val in pairs(global_adjscore) do
             if val and is_subword('/' .. name, pat) then
                 if score > -10 or val < 0 then score = score + val end
-                dbg_print('score',
-                    'Adjust by %.1f from global pattern "%s"', val, pat)
+                dbg_score('Adjust by %.1f from global pattern "%s"', val, pat)
             end
         end
     end
-    dbg_print('score', 'Final score: %.1f', score)
-    df.score = score
+
+    dbg_score('Final score: %.1f', score)
+
+    -- the final score should be a float value
+    df.score = score + 0.0
 end
 
 -- set the scores for a doclist
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
index 1a7270d0b73..addb59a01f4 100755
--- a/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
@@ -5,12 +5,14 @@
 -- Warning: Some functions here assume that M.init_databases() has been called.
 
 -- dependencies
+local kpse = require 'kpse'
+local lfs = require 'lfs'
 local texdoc = {
-    const = require('texdoclib-const'),
-    util = require('texdoclib-util'),
-    alias = require('texdoclib-alias'),
-    score = require('texdoclib-score'),
-    config = require('texdoclib-config'),
+    const = require 'texdoclib-const',
+    util = require 'texdoclib-util',
+    alias = require 'texdoclib-alias',
+    score = require 'texdoclib-score',
+    config = require 'texdoclib-config',
 }
 
 -- shortcuts
@@ -24,11 +26,11 @@ local s_doclist -- the Doclist object to be populated by various functions
 local s_meta -- {[normname] = meta, ...} (populated by init_tlp_database)
 local vanilla -- is this a vanilla TL or a re-package one without tlpdb?
 
-----------------------------   utility functions   -----------------------------
+---------------------------   utility functions   ----------------------------
 
 -- find the TeX Live root
 local function get_tlroot()
-    local tlroot = kpse.var_value('TEXMFROOT')
+    local tlroot = kpse.expand_path('$TEXMFROOT') -- it should be exisitng one
     get_tlroot = function() return tlroot end
     return tlroot
 end
@@ -36,7 +38,7 @@ end
 -- says if file has a known extension according to ext_list
 -- (or known basename according to basename_list)
 local function check_ext(file)
-    file = string.lower(file)
+    file = file:lower()
     -- remove zipext if applicable
     file = texdoc.util.parse_zip(file)
     -- then do the normal thing
@@ -44,12 +46,12 @@ local function check_ext(file)
         if e == '*' then
             return true
         elseif (e == '') then
-            if not string.find(file, '.', 1, true) then
+            if not file:find('.', 1, true) then
                 return true
             end
         else
-            local dot_e = '.'..e
-            if string.sub(file, -string.len(dot_e)) == dot_e then
+            local dot_e = '.' .. e
+            if file:sub(-#dot_e) == dot_e then
                 return true
             end
         end
@@ -63,7 +65,7 @@ local function check_ext(file)
     return false
 end
 
------------------------   docfile and doclist objects   ------------------------
+----------------------   docfile and doclist objects   -----------------------
 
 --[[
 doclist = {
@@ -128,7 +130,6 @@ docfile = {
     -- those are virtual members, see below
     realpath  = full path
     normname  = nomrmalised (path removed up to the 'doc' component)
-    shortname = short name used for scoring
     basename  = basename
     lang      = language tag from the catalogue metadata
     details   = details tag from the catalogue metadata
@@ -201,7 +202,7 @@ end
 
 -- normalise a name from the tlpdb (use for s_meta indexes)
 local function reloc_tlpdb_path(name)
-    return string.gsub(name, '^texmf[^/]*/doc/', '', 1)
+    return name:gsub('^texmf[^/]*/doc/', '')
 end
 
 -- return normalised name
@@ -221,16 +222,9 @@ function Docfile:get_details()
     return meta and (meta.details or false) or false
 end
 
--- return the short name used for scoring
-function Docfile:get_shortname()
-    if self.tree == -1 then return self.name end
-    -- remove first component of name if at least two directory levels
-    return string.match(self.normname, '^..-/(.+/.+)$') or self.normname
-end
-
 -- return the base name
 function Docfile:get_basename()
-    return string.gsub(self.name, '.*/', '', 1)
+    return self.name:gsub('.*/', '')
 end
 
 -- for interface consistency, matches should always be a table, never nil
@@ -246,12 +240,12 @@ function Docfile:get_ext_pos()
     return texdoc.score.ext_pos(self.basename)
 end
 
---------------------   select results from TEXDOCS trees   ---------------------
+-------------------   select results from TEXDOCS trees   --------------------
 
 -- says if a file (with its path) matches a pattern
 local function matches(pattern, file)
     if pattern.original then
-        return string.find(file:lower(), pattern.name:lower(), 1, true)
+        return file:lower():find(pattern.name:lower(), 1, true)
     else
         return texdoc.score.is_exact(file, pattern.name)
     end
@@ -296,25 +290,28 @@ local function init_lsr_db(root, shift)
 
     -- scan it
     local db = {}
-    local maybe_dir, isdoc = true, false
+    local maybe_dir, is_doc = true, false
     local current_dir
     local l = #shift
     while true do
         local line = lsr:read('*line')
         while line == '' do line, maybe_dir = lsr:read('*line'), true end
         if line == nil then break end -- EOF
-        local dir_line = maybe_dir and string.match(line, '^%./(.*):$')
+        local dir_line = maybe_dir and line:match('^%./(.*):$')
         if dir_line then
             maybe_dir = false -- next line may not be a dir
             if string.sub(dir_line .. '/', 1, l) == shift then
-                isdoc = true
-                current_dir = string.sub(dir_line, l+1)
+                is_doc = true
+                current_dir = dir_line:sub(l + 1)
                 db[current_dir] = nil
-            elseif isdoc then
+            elseif is_doc then
                 break -- we're exiting the ./doc (or shift) dir, so it's over
             end
-        elseif isdoc then
-            local file = (current_dir == '') and line or current_dir .. '/' .. line
+        elseif is_doc then
+            local file = line
+            if current_dir ~= '' then
+                file = current_dir .. '/' .. line
+            end
             if check_ext(line) then db[file] = line end
         end
     end
@@ -361,24 +358,24 @@ init_texdocs_database = function()
     local function lsr_root(path)
         if not lfs.isdir (path) then return end
         local root, shift = path, ''
-        if string.sub(root, -1) == '/' then root = string.sub(root, 1, -2) end
-        while string.find(root, '/', 1, true) do
+        if root:sub(-1) == '/' then root = root:sub(1, -2) end
+        while root:find('/', 1, true) do
             if lfs.isfile(root .. '/ls-R') then
                 return root, shift
             end
-            local last_comp = string.match(root, '^.*/(.*)$')
+            local last_comp = root:match('^.*/(.*)$')
             -- /!\ cannot put last_comp in a regex: can contain special char
-            root = string.sub(root, 1, - (#last_comp + 2))
+            root = root:sub(1, - (#last_comp + 2))
             shift = last_comp .. '/' .. shift
         end
     end
 
     doc_roots = {}
     local sep = (os.type == 'windows') and ';' or ':'
-    local kpse_texdocs = kpse.expand_var("$TEXDOCS")
+    local kpse_texdocs = kpse.expand_var('$TEXDOCS')
 
     -- expand the path and turn it into a lua list
-    local raw_doc_roots = string.explode(kpse.expand_braces(kpse_texdocs), sep)
+    local raw_doc_roots = kpse.expand_braces(kpse_texdocs):explode(sep)
     local max = #raw_doc_roots + 1
 
     for j, dir in ipairs(raw_doc_roots) do
@@ -387,9 +384,9 @@ init_texdocs_database = function()
         local path, db
 
         -- get path, !! and // values
-        dir, n = string.gsub (dir, '//$', '')
+        dir, n = dir:gsub('//$', '')
         local recursion_allowed = (n == 1)
-        local path, n = string.gsub (dir, '^!!', '')
+        local path, n = dir:gsub('^!!', '')
         local index_mandatory = (n == 1)
         dbg_print('texdocs',
             'texdocs[%d] = %s (index_mandatory=%s, recursion_allowed=%s)',
@@ -426,7 +423,7 @@ end
 
 end -- end scope of doc_roots
 
-----------------------------   look for sty files   ----------------------------
+---------------------------   look for sty files   ---------------------------
 
 -- add doclist entries for sty files in patlist
 local function get_doclist_sty(patlist)
@@ -443,7 +440,7 @@ local function get_doclist_sty(patlist)
     end
 end
 
---------------------------------   use tlpdb   ---------------------------------
+-------------------------------   use tlpdb   --------------------------------
 
 -- tlpdb mean TeX Live Package DataBase and tlp means TeX Live Package
 
@@ -493,23 +490,23 @@ get_tlpinfo_from_tlpdb = function(filename)
     local curr_tlp
     local state = 'none'
     for line in io.lines(filename) do
-        if state == 'none' and string.find(line, '^name ') then
+        if state == 'none' and line:find('^name ') then
             -- begin a new package
-            curr_tlp = string.lower(string.sub(line, 6, -1))
+            curr_tlp = line:sub(6, -1):lower()
             tlp_doclist[curr_tlp] = {}
         elseif state == 'docfiles' then
-            if not string.find(line, '^ ') then
+            if not line:find('^ ') then
                 state = 'none'
             else
-                local file = string.match(line, '^ ([^ ]*)')
-                local meta = string.match(line, '^ [^ ]* (.+)')
-                local basename = string.match(file, '([^/]*)$')
+                local file = line:match('^ ([^ ]*)')
+                local meta = line:match('^ [^ ]* (.+)')
+                local basename = file:match('([^/]*)$')
                 if check_ext(basename) then
                     -- we've got a docfile here, add it
                     table.insert(tlp_doclist[curr_tlp], file)
                     if meta then
-                        local details = string.match(meta, 'details="([^"]+)"')
-                        local lang = string.match(meta, 'language="([^"]+)"')
+                        local details = meta:match('details="([^"]+)"')
+                        local lang = meta:match('language="([^"]+)"')
                         s_meta[reloc_tlpdb_path(file)] = {
                             details = details,
                             lang = lang,
@@ -518,22 +515,22 @@ get_tlpinfo_from_tlpdb = function(filename)
                 end
             end
         elseif state == 'runfiles' then
-            if not string.find(line, '^ ') then
+            if not line:find('^ ') then
                 state = 'none'
             else
                 -- check for interesting runfiles
-                local e = string.sub(line, -4, -1)
+                local e = line:sub(-4, -1)
                 if e == '.tex' or e == '.sty' or e == '.cls' then
-                    local f = string.match(line, '.*/(.*)%.')
+                    local f = line:match('.*/(.*)%.')
                     tlp_from_runfile[f] = tlp_from_runfile[f] or {}
                     tlp_from_runfile[f][curr_tlp] = true
                 end
             end
         end
         -- update state
-        if string.find(line, '^docfiles ') then
+        if line:find('^docfiles ') then
             state = 'docfiles'
-        elseif string.find(line, '^runfiles ') then
+        elseif line:find('^runfiles ') then
             state = 'runfiles'
         end
     end
@@ -658,8 +655,8 @@ end -- end scope of tlpinfo table
 
 -- get tlpinfo tables initialised by whatever mean
 local function init_tlp_database()
-    local TEXMFVAR = kpse.var_value('TEXMFVAR')
-    local cache_file = TEXMFVAR .. '/' .. C.cache_name
+    -- we assume TEXMFVAR always consists of an element
+    local cache_file = kpse.expand_var('$TEXMFVAR/' .. C.cache_name)
 
     -- set vanilla and detect texlive.tlpdb to use
     local texlive_tlpdb = get_tlroot() .. '/tlpkg/texlive.tlpdb'
@@ -686,7 +683,8 @@ local function init_tlp_database()
             dbg_print('tlpdb', 'Using cached data from ' .. cache_file)
             get_tlpinfo_from_cache(cache_file)
         else
-            dbg_print('tlpdb', 'Getting data from tlpdb file ' .. texlive_tlpdb)
+            dbg_print('tlpdb',
+                'Getting data from tlpdb file ' .. texlive_tlpdb)
             get_tlpinfo_from_tlpdb(texlive_tlpdb)
             dbg_print('tlpdb', 'Writing data in cache file ' .. cache_file)
             local ok, msg = mkdir_p(texdoc.util.path_parent(cache_file))
@@ -704,7 +702,7 @@ local function init_tlp_database()
     end
 end
 
-------------------------------   main function   -------------------------------
+-----------------------------   main function   ------------------------------
 
 -- initialise the various databases (must be called first)
 function M.init_databases()
@@ -714,11 +712,13 @@ end
 
 -- find docfiles according to pattern
 function M.get_doclist(pattern, no_alias)
+    dbg_print('search', 'Searching documents for pattern "%s"', pattern)
+
     -- separate sty patterns from the rest
     local function normal_vs_sty(list)
         local normal, sty = {}, {}
         for _, p in ipairs(list) do
-            if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then
+            if p.name:lower():match('%.([^/.]*)$') == 'sty' then
                 table.insert(sty, p)
             else
                 table.insert(normal, p)
diff --git a/Master/texmf-dist/scripts/texdoc/texdoclib.tlu b/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
index fb85895d37e..7c93fba54cf 100644
--- a/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
+++ b/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
@@ -1,7 +1,7 @@
 -- texdoclib.tlu: the texdoc library
 
 --[[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
 
 This program is free software: you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
diff --git a/Master/texmf-dist/texdoc/texdoc.cnf b/Master/texmf-dist/texdoc/texdoc.cnf
index 5fcb2a53448..b54f56352f2 100644
--- a/Master/texmf-dist/texdoc/texdoc.cnf
+++ b/Master/texmf-dist/texdoc/texdoc.cnf
@@ -141,6 +141,9 @@ adjscore /demos/ = -1
 adjscore /figures/ = -3
 adjscore /images/ = -3
 
+# latex-dev stuff are less important than stable ones
+adjscore /latex-dev/ = -2
+
 # readme files usually get negative scores because they have bad extensions,
 # but they're still slightly better than other results with negative scores
 adjscore readme = +0.1
@@ -165,6 +168,14 @@ adjscore(latex) tufte-latex = -10
 adjscore(latex) Content_LaTeX_Package_Demo = -10
 adjscore(latex) example_latex = -10
 adjscore(latex) test_latex = -10
+# dir names
+adjscore(latex) /latex/ = -4
+adjscore(latex) /latex-dev/ = -5
+adjscore(latex) /generic/ = -5
+
+# prioritize official documents for 'latex'
+adjscore(latex) /latex/base/ = +5
+adjscore(latex) /latex/tools/ = +5
 
 # beamer
 adjscore(beamer) beamer-tut-pt/tutorialbeamer = +10
@@ -206,11 +217,47 @@ adjscore(layout) /tools/ = +1
 # To override one of the settings below, use the 'noalias' directive in
 # your personal configuration file, see the manual for details.
 
-## Essential documentation
+## TeX Live documentation
 
-alias live = texlive-en
+# texlive-en for general, but prioritized local version if exists
 alias texlive = texlive-en
+alias texlive-cz = texlive-cz
+alias texlive-de = texlive-de
+alias texlive-en = texlive-en
+alias texlive-es = texlive-es
+alias texlive-fr = texlive-fr
+alias texlive-it = texlive-it
+alias texlive-ja = texlive-ja
+alias texlive-pl = texlive-pl
+alias texlive-ru = texlive-ru
+alias texlive-sr = texlive-sr
+alias texlive-zh-cn = texlive-zh-cn
+
+alias live = texlive-en
+alias live-cz = texlive-cz
+alias live-de = texlive-de
+alias live-en = texlive-en
+alias live-es = texlive-es
+alias live-fr = texlive-fr
+alias live-it = texlive-it
+alias live-ja = texlive-ja
+alias live-pl = texlive-pl
+alias live-ru = texlive-ru
+alias live-sr = texlive-sr
+alias live-zh-cn = texlive-zh-cn
+
 alias tex-live = texlive-en
+alias tex-live-cz = texlive-cz
+alias tex-live-de = texlive-de
+alias tex-live-en = texlive-en
+alias tex-live-es = texlive-es
+alias tex-live-fr = texlive-fr
+alias tex-live-it = texlive-it
+alias tex-live-ja = texlive-ja
+alias tex-live-pl = texlive-pl
+alias tex-live-ru = texlive-ru
+alias tex-live-sr = texlive-sr
+alias tex-live-zh-cn = texlive-zh-cn
 
 ## various stuff
 
@@ -281,6 +328,10 @@ alias textcomp = source2e
 alias tracefnt = source2e
 # TODO: try to avoid the huge amount of false positives for `doc' itself.
 
+# latex-dev instruction
+alias latex-dev = latex/base/ltnews30
+alias(9) latex-dev = latex-dev.man1
+
 # latex's required graphics bundle
 alias color-dev = color
 alias epsfig-dev = epsfig
@@ -374,7 +425,8 @@ alias l3clist = interface3
 alias l3prop = interface3
 alias l3box = interface3
 alias l3coffins = interface3
-alias l3color = interface3
+alias l3color-base = interface3
+alias l3regex = interface3
 alias l3msg = interface3
 alias l3keys = interface3
 alias l3file = interface3
@@ -386,6 +438,8 @@ alias autofe = ucs
 alias afoot = arabtex-doc
 alias arabicfont = bezos
 alias bibtex = btxdoc
+alias btxdoc-ja = jbtxdoc
+alias btxhak-ja = jbtxhak
 alias changes = changes.english.pdf
 alias cm = cm/README
 alias(5) cmsuper = cm-super/FAQ