summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texdoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-03-28 20:58:51 +0000
committerKarl Berry <karl@freefriends.org>2019-03-28 20:58:51 +0000
commit58f64f141bad7d97ff02df9375bc53453444ba46 (patch)
tree5d6444f973219154f144330bd86f113510bd6910 /Master/texmf-dist/doc/support/texdoc
parentf8c6d58ac3a950c7c156180064a167d575d38576 (diff)
texdoc (28mar19)
git-svn-id: svn://tug.org/texlive/trunk@50627 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/texdoc')
-rw-r--r--Master/texmf-dist/doc/support/texdoc/NEWS8
-rw-r--r--Master/texmf-dist/doc/support/texdoc/README.md29
-rw-r--r--Master/texmf-dist/doc/support/texdoc/texdoc.pdfbin83039 -> 76508 bytes
-rw-r--r--Master/texmf-dist/doc/support/texdoc/texdoc.tex272
4 files changed, 172 insertions, 137 deletions
diff --git a/Master/texmf-dist/doc/support/texdoc/NEWS b/Master/texmf-dist/doc/support/texdoc/NEWS
index 27c1853677d..430c925d24f 100644
--- a/Master/texmf-dist/doc/support/texdoc/NEWS
+++ b/Master/texmf-dist/doc/support/texdoc/NEWS
@@ -2,6 +2,14 @@ NEWS for texdoc
===============
(This file public domain.)
+Version 3.1 (TeX Live 2019)
+===========================
+- New option -c: changing configure temporally
+- New config item `texlive_tlpdb` to specify a path for texlive.tlpdb
+- Fixed an issue that texdoc fails to open gzipped file in GNOME/XFCE
+- Added prefixes to script files not to contaminate kpse search space
+- Many other small improvements and bug fixes
+
Version 3.0 (TeX Live 2018)
===========================
This version has two big features:
diff --git a/Master/texmf-dist/doc/support/texdoc/README.md b/Master/texmf-dist/doc/support/texdoc/README.md
index 19b0208825a..f0da3fc2341 100644
--- a/Master/texmf-dist/doc/support/texdoc/README.md
+++ b/Master/texmf-dist/doc/support/texdoc/README.md
@@ -1,6 +1,7 @@
-# Texdoc (v3.0)
+# Texdoc v3.1 (2019-03-28)
[![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)
Texdoc is a command line program to find and view documentation in TeX Live.
@@ -55,7 +56,7 @@ Many building tasks are defined as [Rake](https://github.com/ruby/rake) tasks:
### Generating all documentation
-This will generate both the PDF and the manpage in `doc/` directory.
+Following will generate both the PDF and the manpage in `doc/` directory.
```
$ rake doc
@@ -63,37 +64,49 @@ $ rake doc
### Generating a pre-hashed cache file
-This will generate a pre-hashed cache file `script/Data.tlpdb.lua`. This task have to be done under a TeX Live setup with tlpdb.
+Following will generate a pre-hashed cache file `script/Data.tlpdb.lua`. This task have to be done under a TeX Live setup with tlpdb.
```
$ rake gen_datafile
```
-### Running all tests
+### Running tests
-This will run all tests in `spec/` directory.
+Following will run all tests in `spec/` directory.
```
$ rake test
```
+Alternatively, you can give spec names with the `--list` (`-l`) option for this task. E.g., following will run only `spec/action/help_spec.rb` and `spec/mode/list_spec.rb`:
+
+```
+$ rake test -- -l action/help,mode/list
+```
+
### Showing all available tasks
-This will show all available tasks with a short discription.
+Following will show all available tasks with a short description.
```
$ rake -T
```
+In addition to that, for options available tasks (e.g., `rake test` and `rake run_texdoc`) you can get options information with `-h` option for each task:
+
+```
+$ rake test -- -h
+```
+
## Further Information
-More specific information (e.g. TODO) can be found in the Wiki of our GitHub repository. Please visit:
+More specific information (e.g., TODO) can be found in the Wiki of our GitHub repository. Please visit:
* <https://github.com/TeX-Live/texdoc/wiki>
## Copyright and License
-Copyright 2008-2018 Manuel Pégourié-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining. All rights reserved.
+Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and 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.pdf b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
index 1606e91d33b..d897017714d 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc.tex b/Master/texmf-dist/doc/support/texdoc/texdoc.tex
index a300236ae67..37b44602591 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.tex
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc.tex
@@ -1,13 +1,11 @@
+%#!xelatex
% Texdoc user manual
-% Copyright 2018 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura
% distributed under the terms of GPL v3 or later
-%!TEX encoding=utf-8
-%!TEX program=xelatex
-
\setlength\overfullrule{5pt}
-\documentclass[a4paper, oneside]{scrartcl}
+\documentclass[a4paper,oneside]{scrartcl}
\usepackage{fontspec}
\usepackage{xunicode}
@@ -19,13 +17,13 @@
\newcommand\mylangle{$\langle$}
\newcommand\myrangle{$\rangle$}
-\usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}
+\usepackage{xargs,xspace,fancyvrb,xcolor,pifont,calc,ifmtarg,mathstyle}
-\usepackage[sf, bf]{titlesec}
+\usepackage[sf,bf]{titlesec}
\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
-\titleformat{\subsubsection}[runin]{\itshape}{%
- \makebox[0pt][r]{\thetitle\kern1pc}}{%
- 0pt}{}[\maybedot\space --- \kern0pt]
+\titleformat{\subsubsection}[runin]{\itshape}
+ {\makebox[0pt][r]{\thetitle\kern1pc}}
+ {0pt}{}[\maybedot\space --- \kern0pt]
\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt}
\usepackage{enumitem}
@@ -40,7 +38,8 @@
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}}
+ pdfkeywords={Texdoc, TeX Live, manual, documentation},
+}
\usepackage[yyyymmdd]{datetime}
\renewcommand{\dateseparator}{-}
@@ -68,15 +67,13 @@
formatcom=\cofont,
defineactive=\makeallfancy,
codes=\fancyactives,
- }
-\newcommand\fancyactives{%
- \catcode`\«\active}
-\newcommand\makeallfancy{%
- \makefancyog}
-{\catcode`\«\active
-\global\def\makefancyog{%
- \def«##1»{\meta{##1}}}
}
+\newcommand\fancyactives{\catcode`\«\active}
+\newcommand\makeallfancy{\makefancyog}
+\bgroup
+ \catcode`\«\active
+ \global\def\makefancyog{\def«##1»{\meta{##1}}}
+\egroup
\newif\ifframed
\newlength\dec
@@ -88,7 +85,7 @@
\def\bmtext{#2}%
\def\thelabel{#3}%
\SaveVerbatim[samepage, gobble=2]{verbmat}%
- }{%
+}{%
\endSaveVerbatim
\xdef\sectioncmd{\noexpand\nodotthistime
\thecmd[\bmtext]{%
@@ -100,32 +97,31 @@
\BUseVerbatim{verbmat}}%
\fi
\noexpand\label{\thelabel}}}%
- \aftergroup\sectioncmd}
+ \aftergroup\sectioncmd
+}
\makeatother
\newcommand\maybedot{.}
-\newcommand\nodotthistime{%
- \renewcommand\maybedot{%
- \global\def\maybedot{.}}}
+\newcommand\nodotthistime{\renewcommand\maybedot{\global\def\maybedot{.}}}
-\newenvironment{cmdsubsec}[2]{%
- \framedtrue \commandes\subsection{#1}{#2}%
- }{%
- \endcommandes}
+\newenvironment{cmdsubsec}[2]
+ {\framedtrue \commandes\subsection{#1}{#2}}
+ {\endcommandes}
-\newenvironment{cmdsubsub}[2]{%
- \framedfalse \commandes\subsubsection{#1}{#2}%
- }{%
- \endcommandes}
+\newenvironment{cmdsubsub}[2]
+ {\framedfalse \commandes\subsubsection{#1}{#2}}
+ {\endcommandes}
\makeatletter
-\newenvironment{htcode}{% % code en hors-texte
- \SaveVerbatim[samepage, gobble=2]{verbmat}%
- }{%
- \endSaveVerbatim
- \par\medskip\noindent\hspace*{\parindent}%
- \BUseVerbatim{verbmat}%
- \par\medskip\@endpetrue}
+% code in hors-text
+\newenvironment{htcode}
+ {\SaveVerbatim[samepage, gobble=2]{verbmat}}
+ {
+ \endSaveVerbatim
+ \par\medskip\noindent\hspace*{\parindent}%
+ \BUseVerbatim{verbmat}%
+ \par\medskip\@endpetrue
+ }
\makeatother
\DefineShortVerb{\|}
@@ -139,7 +135,7 @@
\subtitle{Find \& view documentation in \texlive\\
\href{https://tug.org/texdoc/}{https://tug.org/texdoc/}}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
-\date{v3.0 \today}
+\date{v3.1\quad \today}
\begin{document}
\VerbatimFootnotes
@@ -150,7 +146,7 @@
\subsection{Basics}
-Texdoc is a command line tool which search and view documentations in \texlive.
+Texdoc is a command line tool which find and view documentation in \texlive.
If you type
%
\begin{quote}
@@ -158,21 +154,21 @@ If you type
\end{quote}
%
in your command line, the documentation of the |«name»| package will pop up. Of
-course, 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.
+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 in a
-viewer. It is rather handy when you know what you want to read, and want to
-access it quickly. On the other hand, there may be other relevant documents
-for the given |«name»|, which are ignored in view mode.
+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 a other
-interesting sources of information besides the package's main documentation.
+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
@@ -194,14 +190,14 @@ 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 (an possibly some directories) the first time.
+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 = «yourmode»|
-in this file, where |«yourmode»| is one of |view|, |mixed|, |list| or
-|showall|. To set your favorite language, use |lang = «2-letter code»|, though
-it is usually detected automatically.
+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
@@ -210,7 +206,7 @@ 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
+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
@@ -225,13 +221,13 @@ insert the line |viewer_pdf = xpdf %s &| in your configuration file. Here,
\subsection{You can stop reading now}
-The next part explains Texdoc mechanisms for finding the best results and how
-to cutomize them. The default configuration file tries hard to set appropriate
-values so that you normally don't need to fiddle with that, but you may be
-curious or have special needs.
+Following parts explain Texdoc's mechanisms for finding the best results and
+how to customize them. We have been trying hard to optimize the default
+configuration values so that you normally don't need to fiddle with that, but
+you may be curious or have special needs.
The final part is a full reference including a few points omitted in the
-present and next part.
+present and next parts.
\clearpage
@@ -247,7 +243,7 @@ sources:
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 me
+ |«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
@@ -255,7 +251,7 @@ 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
+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
@@ -282,7 +278,7 @@ 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 |shortverb|, it will sort them basically at random.
+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|,
@@ -337,13 +333,13 @@ 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
+|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 begin applied for a particular keyword, include |stopalias «keyword»| in
+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.
@@ -364,8 +360,8 @@ in the next subsections.
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 |adjustscore| directive. Here
-are a few examples from the default configuration file.
+(\ref{ss-quick-file} or \ref{ss-prec}) using the |adjscore| directive. Here are
+a few examples from the default configuration file.
\begin{htcode}
adjscore /Makefile = -1000
@@ -385,17 +381,17 @@ The third directive gives a malus for results containing |texdoc| only if the
search keyword is |tex|. Otherwise, such results would get a high score
because the heuristic scoring would think |texdoc| is the name of \TeX's
documentation. The value -10 is enough to ensure that those results will have
-a negative score, so wil not be displayed unless ``showall'' mode is active.
+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.
+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, ps, dvi, no extension). You can configure it
+(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
@@ -418,24 +414,28 @@ 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 properlr, Texdoc gives a special score files
+|«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 files. Be warned, it will replace the default list, no expand
+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 results of fuzzy search are shown
-by as an informational message. (you can see that with option |-v|)
+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}).
+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
@@ -482,22 +482,23 @@ item.
-h, --help
\end{cmdsubsub}
-Show a quick help message (namely a list of command-line options) and exit
+Shows a quick help message (namely a list of command-line options) and exit
successfully.
\begin{cmdsubsub}{-V, --version}{cl-V}
-V, --version
\end{cmdsubsub}
-Show the current version of the program and exit successfully.
+Shows the current version of the program and exit successfully.
\begin{cmdsubsub}{-f, --files}{cl-f}
-f, --files
\end{cmdsubsub}
-Show the list of configuration files for the current installation and
-platform, with their status (active, not found, or disabled
-(see~\ref{cf-lastfile_switch})) and exit successfully.
+Shows the list of configuration files for the current installation and
+platform, with their status and exit successfully. Normally, only ``active''
+and ``disabled'' files are shown (see~\ref{cf-lastfile_switch}). To show ``not
+found'' files as well, you can use |--verbose|.
\begin{cmdsubsub}{--just-view}{cl-just-view}
--just-view «file»
@@ -518,7 +519,7 @@ Set |mode| to the given value, see~\ref{cf-mode}.
-i, --interact, -I, --nointeract
\end{cmdsubsub}
-Set |interact_switch| to true (resp. false), see~\ref{cf-interact_switch}.
+Set |interact_switch| to true (or false), see~\ref{cf-interact_switch}.
\begin{cmdsubsub}{-M, --machine}{cl-M}
-M, --machine
@@ -543,25 +544,33 @@ Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}.
\end{cmdsubsub}
Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug|
-without the list, activates all available debug items.
+without specifying a list, activates all available debug items.
+
+\begin{cmdsubsub}{-c}{cl-c}
+ -c «name»=«value»
+\end{cmdsubsub}
+
+Set configuration item |«name»| to |«value»|. This is a general way to access
+any configuration items listed in \ref{ss-conf} from command line.
\subsection{Environment variables}\label{ss-envvar}
They all correspond to some |viewer_«ext»| setting, and the reader is referred
to~\ref{cf-viewer_*} for details.\footnote{Old names of environment variables,
-namely |TEXDOCVIEW_{txt,html,dvi,ps,pdf}| and
-|TEXDOC_VIEWER_{TXT,HTML,DVI,PS,PDF}|, are deprecated but still work.} You can
+namely |TEXDOCVIEW_{html,dvi,md,txt,pdf,ps}| and
+|TEXDOC_VIEWER_{HTML,DVI,MD,TXT,PDF,PS}|, are deprecated but still work.} You can
append |_texdoc| to every name in the first column: this wins over every other
name.
\begin{center}
\begin{tabular}{ll}
Environment variables & Configuration items \\
-|PAGER| & |viewer_txt| \\
|BROWSER| & |viewer_html| \\
|DVIVIEWER| & |viewer_dvi| \\
-|PSVIEWER| & |viewer_ps| \\
+|MDVIEWER| & |viewer_md| \\
+|PAGER| & |viewer_txt| \\
|PDFVIEWER| & |viewer_pdf| \\
+|PSVIEWER| & |viewer_ps| \\
\end{tabular}
\end{center}
@@ -610,14 +619,14 @@ 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
+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
+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.
@@ -632,18 +641,20 @@ the empty list, but see the shipped configuration file for more.
ext_list = «list»
\end{cmdsubsub}
-Set the list of recognised extensions to |«list»|. Default is
+Set the list of recognised extensions to |«list»|. The default value is:
+%
\begin{htcode}
- pdf, html, htm, txt, dvi, ps,
+ 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
+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
+ 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}
@@ -655,11 +666,11 @@ necessary since every sty file would have a proper documentation in pdf, html
or plain text, but\dots
For each |«ext»| in |ext_list| there should be a corresponding |viewer_«ext»|
-value set. Defaults are defined corresponding to the default |ext_list|, but
-you can add values if you want. For example, if you want Texdoc to be able
+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, dvi, ps,
+ ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps,
viewer_1 = man
viewer_5 = man
\end{htcode}
@@ -672,15 +683,15 @@ viewer is used and a warning is issued.
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 heurisitc score if it was
+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|''.
+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.
@@ -688,8 +699,8 @@ extension is unknown, the text viewer will be used to view the file.
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 heurisitc score if it was
+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_*}
@@ -699,7 +710,7 @@ previously positive.
Set the viewer command for files with extension |«ext»| to |«cmd»|. For files
without extension, |viewer_txt| is used, and there's no |viewer_| variable.
In |«cmd»|, |%s| can be used as a placeholder for the file name, which is
-otherwise inserted at the end of the command. The command can be a arbitrary
+otherwise inserted at the end of the command. The command can be an arbitrary
shell construct.
\begin{cmdsubsub}{lang}{cf-lang}
@@ -721,9 +732,10 @@ recommended).
debug_list = «list»
\end{cmdsubsub}
-Set the list of activated debug items (default: none; if the command-line
-option is used without arguments, the list defaults to all known debug items).
-Implies |--verbose|. Debug information is printed on standard error.
+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»
@@ -737,38 +749,38 @@ is disabled.
machine_switch = «true, false»
\end{cmdsubsub}
-Turn on or off machine-readable output (default: off). With this option
+Turn on or off machine-readable output (default: off). With this option
active, the value of |interact_switch| is forced to |false|, and each line of
output is
\begin{htcode}
«argument»\t«score»\t«filename»
\end{htcode}
where |«argument»| is the name of the argument to which the results correspond
-(mainly useful if there were many arguments), |\t| is the tab (ascii 9)
+(mainly useful if there were many arguments), |\t| is the tab (ASCII \#9)
character, and the other entries are pretty self-explanatory. Nothing else is
-printed on stdout, except if a internal error occurs (in which case exit code
+printed on stdout, except if an internal error occurs (in which case exit code
will be 1). In the future, more tab-separated fields may be added at the end
of the line, but the first 3 fields will remain unchanged.
Currently, there are two additional fields: a two-letter language code, and an
unstructured description, both taken from the CTAN catalogue (via the \texlive
-database). These fields may be empty and they are not guaranteed to keep the
+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
+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. Also make sure you are using blocking (i.e. not returning
-immediately) viewers.
+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,
@@ -794,11 +806,12 @@ Commands for removing files (resp. directories) on your system (defaults:
lastfile_switch = «true, false»
\end{cmdsubsub}
-If set to true, prevents Texdoc from reading any other configuration file
-after this one (they will be reported as ``disabled'' by |texdoc -f|). Mainly
-useful for installing a newer version of Texdoc in your home and preventing
-the default configuration file from older versions to be used (see the
-\href{https://tug.org/texdoc/}{web site} for instructions on how to do so).
+If set to true, prevents Texdoc from reading any other configuration file after
+this one (they will be reported as ``disabled'' by |texdoc -f|). Mainly useful
+for installing a newer version of Texdoc in your home and preventing the
+default configuration file from older versions to be used (see the
+\href{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do
+so).
\begin{cmdsubsub}{fuzzy_level}{cf-fuzzy_level}
fuzzy_level = «n»
@@ -814,12 +827,13 @@ The current exit codes are:
\item Success.
\item Internal error.
\item Usage error.
+ \item No documentation found.
\end{enumerate}
\section{Licence}\label{s-licence}
-The current Texdoc program and its documentation are copyright 2008--2018
-Manuel Pégourié-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining.
+The current version of Texdoc program and its documentation are copyright 2008
+Manuel Pégourié-Gonnard, Takuto Asakura, and the {\texlive} Team.
They are free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
@@ -828,11 +842,11 @@ version.
This program is distributed in the hope that it will be useful, but
\emph{without any warranty}; without even the implied warranty of
-\emph{merchantability} or \emph{fitness for a particular purpose}. See the
+\emph{merchantability} or \emph{fitness for a particular purpose}. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
-this program. If not, see \url{http://www.gnu.org/licenses/}.
+this program. If not, see \url{http://www.gnu.org/licenses/}.
\bigskip
@@ -845,7 +859,7 @@ Previous work (Texdoc program) in the public domain:
\end{itemize}
\bigskip
-\begin{center}\Large\rmfamily\bfseries
+\begin{center}\Large\bfseries
Happy {\TeX}ing!
\end{center}