diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texdoc/doc |
Initial commit
Diffstat (limited to 'support/texdoc/doc')
-rw-r--r-- | support/texdoc/doc/texdoc.1 | 177 | ||||
-rw-r--r-- | support/texdoc/doc/texdoc.pdf | bin | 0 -> 76508 bytes | |||
-rw-r--r-- | support/texdoc/doc/texdoc.tex | 867 |
3 files changed, 1044 insertions, 0 deletions
diff --git a/support/texdoc/doc/texdoc.1 b/support/texdoc/doc/texdoc.1 new file mode 100644 index 0000000000..cf072bd5fc --- /dev/null +++ b/support/texdoc/doc/texdoc.1 @@ -0,0 +1,177 @@ +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "TEXDOC" "1" "March 2019" "Texdoc 3.1" "Texdoc manual" +. +.SH "NAME" +\fBtexdoc\fR \- find & view documentation in TeX Live +. +.SH "SYNOPSIS" +\fBtexdoc\fR [OPTION\.\.\.] NAME\.\.\. +. +.br +\fBtexdoc\fR [OPTION\.\.\.] ACTION +. +.SH "DESCRIPTION" +Try to find appropriate TeX documentation for the specified NAME(s)\. Alternatively, perform the given ACTION and exit\. +. +.SH "OPTIONS" +. +.TP +\fB\-w\fR, \fB\-\-view\fR +Use view mode: start a viewer\. \fB(default)\fR +. +.TP +\fB\-m\fR, \fB\-\-mixed\fR +Use mixed mode (view or list)\. +. +.TP +\fB\-l\fR, \fB\-\-list\fR +Use list mode: show a list of results\. +. +.TP +\fB\-s\fR, \fB\-\-showall\fR +Use showall mode: show also "bad" results\. +. +.TP +\fB\-i\fR, \fB\-\-interact\fR +Use interactive menus\. \fB(default)\fR +. +.TP +\fB\-I\fR, \fB\-\-nointeract\fR +Use plain lists, no interaction required\. +. +.TP +\fB\-M\fR, \fB\-\-machine\fR +Machine\-readable output for lists (implies \-I)\. +. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Suppress warnings and most error messages\. +. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +Print additional information (e\.g\., viewer command)\. +. +.TP +\fB\-D\fR, \fB\-\-debug\fR +Activate all debug output (equal to "\-\-debug=all")\. +. +.TP +\fB\-d\fR LIST, \fB\-\-debug\fR=LIST +Activate debug output restricted to the items specified in LIST\. +. +.br +Available items: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\. +. +.TP +\fB\-c\fR NAME=VALUE +Set configuration item NAME to VALUE\. +. +.SH "ACTIONS" +. +.TP +\fB\-h\fR, \fB\-\-help\fR +Print this help message\. +. +.TP +\fB\-V\fR, \fB\-\-version\fR +Print the version number\. +. +.TP +\fB\-f\fR, \fB\-\-files\fR +Print the list of configuration files used\. +. +.TP +\fB\-\-just\-view\fR FILE +Display FILE, given with full path (no searching)\. +. +.SH "ENVIRONMENT" +. +.TP +\fBBROWSER\fR, \fBBROWSER_texdoc\fR +Set the command to be used for HTML documents\. +. +.TP +\fBDVIVIEWER\fR, \fBDVIVIEWER_texdoc\fR +Set the command to be used for DVI documents\. +. +.TP +\fBMDVIEWER\fR, \fBMDVIEWER_texdoc\fR +Set the command to be used for Markdown documents\. +. +.TP +\fBPAGER\fR, \fBPAGER_texdoc\fR +Set the command to be used for text documents\. +. +.TP +\fBPDFVIEWER\fR, \fBPDFVIEWER_texdoc\fR +Set the command to be used for PDF documents\. +. +.TP +\fBPSVIEWER\fR, \fBPSVIEWER_texdoc\fR +Set the command to be used for PS documents\. +. +.TP +\fBLANG\fR, \fBLC_ALL\fR and so on +Set the locale (which will influence on the search results)\. +. +.TP +\fBTEXDOCS\fR +In addition to the documents included in the TeX Live database, Texdoc also searches documentation under TEXMF trees specified by the kpathsea variable \fBTEXDOCS\fR\. +. +.SH "FILES" +\fB<texmf>/texdoc/texdoc\.cnf\fR, see output of the \fB\-\-files\fR option\. +. +.SH "EXIT STATUS" +The \fBtexdoc\fR command exists with one of the following values: +. +.TP +0 +Success\. +. +.TP +1 +Internal error\. +. +.TP +2 +Usage error\. +. +.TP +3 +No documentation found\. +. +.SH "REPORTING BUGS" +Report bugs to \fItexdoc@tug\.org\fR\. +. +.br +Texdoc home page: \fIhttp://tug\.org/texdoc/\fR +. +.br +Source: \fIhttps://github\.com/TeX\-Live/texdoc\fR +. +.SH "COPYRIGHT" +Copyright 2018 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining\. +. +.br +License: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\. +. +.br +This is free software: you are free to change and redistribute it\. +. +.SH "SEE ALSO" +The full documentation is maintained as a PDF manual\. The command +. +.IP "" 4 +. +.nf + +texdoc texdoc +. +.fi +. +.IP "" 0 +. +.P +should give you access to the complete manual\. diff --git a/support/texdoc/doc/texdoc.pdf b/support/texdoc/doc/texdoc.pdf Binary files differnew file mode 100644 index 0000000000..d897017714 --- /dev/null +++ b/support/texdoc/doc/texdoc.pdf diff --git a/support/texdoc/doc/texdoc.tex b/support/texdoc/doc/texdoc.tex new file mode 100644 index 0000000000..37b4460259 --- /dev/null +++ b/support/texdoc/doc/texdoc.tex @@ -0,0 +1,867 @@ +%#!xelatex +% Texdoc user manual +% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura +% distributed under the terms of GPL v3 or later + +\setlength\overfullrule{5pt} + +\documentclass[a4paper,oneside]{scrartcl} +\usepackage{fontspec} +\usepackage{xunicode} + +\defaultfontfeatures{Ligatures=TeX} +\setmainfont{DejaVuSerif} +\setsansfont{DejaVuSans} +\setmonofont{DejaVuSansMono} +\renewcommand\familydefault{\sfdefault} \normalfont +\newcommand\mylangle{$\langle$} +\newcommand\myrangle{$\rangle$} + +\usepackage{xargs,xspace,fancyvrb,xcolor,pifont,calc,ifmtarg,mathstyle} + +\usepackage[sf,bf]{titlesec} +\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}} +\titleformat{\subsubsection}[runin]{\itshape} + {\makebox[0pt][r]{\thetitle\kern1pc}} + {0pt}{}[\maybedot\space --- \kern0pt] +\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt} + +\usepackage{enumitem} +\newlength\lssep \setlength\lssep{\smallskipamount} +\setlist{noitemsep,topsep=\lssep,partopsep=\lssep} + +\usepackage[british]{babel} +\usepackage[bookmarks=true]{hyperref} +\usepackage{bookmark} +\hypersetup{% + bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2, + pdftitle={Texdoc: find and view documentation in TeX Live}, + pdfauthor={Manuel Pégourié-Gonnard, Takuto Asakura}, + pdfsubject={Texdoc's user manual}, + pdfkeywords={Texdoc, TeX Live, manual, documentation}, +} + +\usepackage[yyyymmdd]{datetime} +\renewcommand{\dateseparator}{-} + +\newcommand\texlive{\TeX~Live\xspace} + +\setlength\parindent{\baselineskip} + +\lastlinefit=500 % e-TeX powered + +\definecolor{links}{named}{violet} +\definecolor{special}{rgb}{0,0.5,0} +\definecolor{code}{rgb}{0,0,0.6} +\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links} + +\newcommand\cofont{% code + \color{code}\normalfont\ttfamily} +\newcommand\meta[1]{% meta elements + {\normalfont\color{special}\mylangle\textit{#1}\myrangle}} + +% take care of non-breakable spaces +\catcode`\ 10\relax + +\fvset{% + formatcom=\cofont, + defineactive=\makeallfancy, + codes=\fancyactives, +} +\newcommand\fancyactives{\catcode`\«\active} +\newcommand\makeallfancy{\makefancyog} +\bgroup + \catcode`\«\active + \global\def\makefancyog{\def«##1»{\meta{##1}}} +\egroup + +\newif\ifframed +\newlength\dec +\setlength\dec{\heightof{\cofont{texdoc \meta{name}}}} + +\makeatletter +\newenvironment{commandes}[3]{% + \def\thecmd{\noexpand#1}% + \def\bmtext{#2}% + \def\thelabel{#3}% + \SaveVerbatim[samepage, gobble=2]{verbmat}% +}{% + \endSaveVerbatim + \xdef\sectioncmd{\noexpand\nodotthistime + \thecmd[\bmtext]{% + \ifframed + \unexpanded{\normalsize\normalfont + \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}% + \else + \unexpanded{\normalsize\normalfont + \BUseVerbatim{verbmat}}% + \fi + \noexpand\label{\thelabel}}}% + \aftergroup\sectioncmd +} +\makeatother + +\newcommand\maybedot{.} +\newcommand\nodotthistime{\renewcommand\maybedot{\global\def\maybedot{.}}} + +\newenvironment{cmdsubsec}[2] + {\framedtrue \commandes\subsection{#1}{#2}} + {\endcommandes} + +\newenvironment{cmdsubsub}[2] + {\framedfalse \commandes\subsubsection{#1}{#2}} + {\endcommandes} + +\makeatletter +% code in hors-text +\newenvironment{htcode} + {\SaveVerbatim[samepage, gobble=2]{verbmat}} + { + \endSaveVerbatim + \par\medskip\noindent\hspace*{\parindent}% + \BUseVerbatim{verbmat}% + \par\medskip\@endpetrue + } +\makeatother +\DefineShortVerb{\|} + +\setkomafont{title}{} +\setkomafont{subtitle}{\Large} +\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace} + +\newcommand\tdml{\href{http://lists.tug.org/texdoc}{texdoc mailing list}\xspace} + +\title{Texdoc} +\subtitle{Find \& view documentation in \texlive\\ + \href{https://tug.org/texdoc/}{https://tug.org/texdoc/}} +\author{Manuel Pégourié-Gonnard\and Takuto Asakura} +\date{v3.1\quad \today} + +\begin{document} +\VerbatimFootnotes + +\maketitle + +\section{Quick guide} + +\subsection{Basics} + +Texdoc is a command line tool which find and view documentation in \texlive. +If you type +% +\begin{quote} +|texdoc «name»| +\end{quote} +% +in your command line, the documentation of the |«name»| package will pop up. Of +course, you have to replace |«name»| with the actual name of the package. To +look up the documentation of more than one package at once, just use multiple +|«name»|s as arguments. + +\subsection{Modes}\label{ss-modes} + +Texdoc has different modes that determine how results will be handled. In the +default, ``view'' mode, it opens the first (supposedly the best) result with a +suitable viewer. It is rather handy when you know what you want to read, and +want to access it quickly. On the other hand, there may be other relevant +documents for the given |«name»|, which are ignored in view mode. + +The so-called ``list mode'' makes Texdoc list all relevant documentation and +ask you which one you want to view. It is useful when there another interesting +sources of information besides the package's main documentation. + +There is also a ``mixed'' mode, intended to combine the best of view mode and +list mode: if there is only one relevant result, then Texdoc opens it in a +viewer, else it offers you a menu. + +By default, Texdoc hides the results it considers less relevant (unless it +finds no relevant result at all). In ``showall'' mode, it always shows all +results. + +To select the mode on the command-line, use |texdoc «option» «name»| with one +of the following options: |-w| or |--view| for view mode, |-m| or |--mixed| +for mixed mode, |-l| or |--list| for list mode, |-s| or |--showall| for +showall mode. + +If you always (or mostly) use the same mode, you don't want to keep typing the +same option. The next section describes how to customize Texdoc using +configurations files. + +\subsection{Configuration files}\label{ss-quick-file} + +Use |texdoc --files| to know where to put your personal configuration file; +you'll need to create this file (a possibly some directories) the first time. +(If you want to know the full list of possible configuration files, +see~\ref{ss-prec}.) + +In order to select you favorite mode, just insert a line |mode = «mode»| in +this file, where |«mode»| is one of |view|, |mixed|, |list| or |showall|. To +set your favorite language, use |lang = «2-letter code»|, though it is usually +detected automatically. + +The configuration file can be used to tweak Texdoc in many ways, the most +useful of which is probably the selection of the viewers for various types of +documents, explained in the next section. + +\subsection{Viewers}\label{ss-viewer} + +Texdoc's mechanism for choosing a viewer varies according to your platform. +On Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file +associations like when you double-click files in the Explorer, the Finder or +your default file manager (except for the text viewer, which is always a +pager). Otherwise, it tries to find a viewer in the path from a list of +``known'' viewers. + +You may want to select a different viewer for some kind of file. This is +achieved by setting the various |viewer_«ext»| configuration options, where +|«ext»| is the extension corresponding to the file type. For example, if you +want to set xpdf as your default PDF viewer, and run it in the background, +insert the line |viewer_pdf = xpdf %s &| in your configuration file. Here, +|%s| stands for the name of the file to view. + +\subsection{You can stop reading now} + +Following parts explain Texdoc's mechanisms for finding the best results and +how to customize them. We have been trying hard to optimize the default +configuration values so that you normally don't need to fiddle with that, but +you may be curious or have special needs. + +The final part is a full reference including a few points omitted in the +present and next parts. + +\clearpage + +\section{File search, aliases, score} + +\subsection{An overview of how Texdoc works} + +When you type |texdoc «keyword»|, Texdoc first makes a list of files, from two +sources: +\begin{enumerate} + \item In the trees containing documentation (given by the + \href{https://www.tug.org/kpathsea/} {kpathsea} variable |TEXDOCS|), it + selects all files containing |«keyword»| in their name (including the + directory name); + \item In the \texlive Database, it looks for packages named + |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be + |sty| or |cls|, and selects all the documentation files from this package. +\end{enumerate} +Files are filtered by extension: only files with known extensions may be +selected. In case Texdoc cannot find any documentation here, fuzzy search will +find the closest package name to the |«keyword»| and reselect the files (see +\ref{ss-fuzzy}). + +The selected files are then score according to some simple heuristics. For +example, a file named |«keyword».pdf|, is good, |«keyword»-«lang».pdf| will +score higher if your favorite language |«lang»| is detected or configured, +|«keyword»-doc| will be preferred over |«keyword»whatever|, files in a +directory named exactly |«keyword»| get a bonus, etc. + +Score may also be adjusted base on file extensions or known names (or +subwords): for example, by default, |Makefile|s get a very bad score since +they are almost never documentation.\footnote{They often end up in the doc + tree, since the source of documentation is often in the same directory as + the documentation itself in \texlive. Other source files are discriminated + by extension.} + +Finally, depending on the mode, the file with the highest score is opened in a +viewer, or the list of results is shown. Usually, only results with a positive +score are displayed, except in showall mode. Results with very bad scores +(-100 and below) are never displayed. + +\medskip + +This model for searching and scoring is quite efficient, but is unfortunately +not perfect: Texdoc may sometimes need a hint, either to find a relevant file +or, more likely, to recognize which of the files found is the most relevant. + +For example, assume you are looking for the documentation of the shortvrb +{\LaTeX} package. Texdoc will find |shortvrb.sty| in the |latex| \texlive +package, but since this package contains a lot of documentation files, none of +which contains the string |shortvrb|, it will sort them basically at random. + +Here comes the notion of \emph{alias}: in the default configuration file, +|shortvrb| is aliased to |base/doc|, so that when you type |texdoc shortvrb|, +Texdoc knows it has to look primarily for |base/doc|. Note that Texdoc will +also look for the original name, and that a name can be aliased to more than +one new name. + +\medskip + +We will soon see how you can configure this, but let's start with a few +definitions about how a file can match keyword (all matching is +case-insensitive): +\begin{enumerate} + \item The keyword is a substring of the file name. + \item The keyword is a ``subword'' of the file name; words are defined as + sequences of alphanumeric characters delimited by punctuation characters + (there is no space in file names in \texlive) and a subword is a + substring both ends of which are a word boundary. + \item The keyword matches ``exactly'' the file name: that is, the file + name is the keyword, possibly plus an extension. +\end{enumerate} + +\subsection{Alias directives}\label{ss-alias} + +\begin{htcode} + alias «original keyword» = «name» + alias(«score») «original keyword» = «name» +\end{htcode} + +You can define your own aliases in Texdoc's configuration files +(see~\ref{ss-quick-file} or \ref{ss-prec}). For example, +insert\footnote{Actually, you don't need to do this, the default configuration + file already includes this directive.} +\begin{htcode} + alias shortvrb = base/doc +\end{htcode} +in order to alias |shortvrb| to |base/doc|. Precisely, it means that files in +the doc trees matching exactly |base/doc| will be added to the result list +when you look for |shortvrb|, and get a score of 10 (default score for alias +results). This is greater than the results of heuristic scoring: it means that +results found via aliases will always rank before results associated to the +original keyword. + +If you want the results associated to a particular alias to have a custom +score instead of the default 10, you can use the optional argument to the +alias directive. This can be useful if you associate many aliases to +a keyword and want one of them to show up first. + +Additionally, starting from with v0.80, aliases for |«keyword»-«lang»|, where +|«lang»| is your preferred language's 2-letter code (as detected or +configured, see the |lang| option) are also used for |«keyword»| and get a +|+1| score upgrade. + +You can have a look at the configuration file provided (the last shown by +|texdoc -f|) for examples. If you feel one of the aliases you defined locally +should be added to the default configuration, please share it on the \tdml. + +Aliases are additive: if you define your own aliases for a keyword in your +configuration file, and there are also aliases for the same keyword in the +default configuration, they will add up. To prevent the default aliases +from being applied for a particular keyword, include |stopalias «keyword»| in +your personal configuration file. It will preserve the aliases defined before +this directive (if any) but prevent all further aliasing on this keyword. + +\textit{Remark.} Aliasing is case-insensitive, and doesn't cascade: +only aliases associated to the original keyword are used. + +\textbf{Warning.} Results found from aliases always have the score defined by +the |alias| directive (10 by default), regardless of the adjustments described +in the next subsections. + +\subsection{Score directives}\label{ss-score} + +\begin{htcode} + adjscore «pattern» = «score adjustment» + adjscore(«keyword») «pattern» = «score adjustment» +\end{htcode} + +It is possible to adjust the score of results containing some pattern as a +subword, either globally (for the result of all searches) or only when +searching with a particular keyword. This is done in a configuration file +(\ref{ss-quick-file} or \ref{ss-prec}) using the |adjscore| directive. Here are +a few examples from the default configuration file. + +\begin{htcode} + adjscore /Makefile = -1000 + adjscore /tex-virtual-academy-pl/ = -50 + adjscore(tex) texdoc = -10 +\end{htcode} + +All files named |Makefile| (and also files named |Makefile-foo| if there are +any) are ``killed'' : by adjusting their score with such a large negative +value, their final score will most probably be less than -100, so they will +never be displayed. Files from the |tex-virtual-academy-pl| directory, on the +other hand, are not killed but just get a malus, since they are a common +source of ``fake'' matches which hide better results (even for the lucky ones +who can read polish). + +The third directive gives a malus for results containing |texdoc| only if the +search keyword is |tex|. Otherwise, such results would get a high score +because the heuristic scoring would think |texdoc| is the name of \TeX's +documentation. The value -10 is enough to ensure that those results will have +a negative score, so will not be displayed unless ``showall'' mode is active. + +\textbf{Warning}: Values of scores (like the default score for aliases, the +range of heuristic scoring, etc.) may change in a future version of Texdoc. +So, don't be surprised if you need to adapt your scoring directives after a +future update of Texdoc. This warning will hopefully disappear at some point. + +\subsection{File extensions and names}\label{ss-ext} + +The allowed file extensions are defined by the configuration item |ext_list| +(default: pdf, html, htm, txt, md, ps, dvi, no extension). You can configure it +with a line |ext_list = «your, list»| in a configuration file. Be aware +that it will completely override the default list, not add to it. An empty +string in the list means files without extension (no dot in the name), while a +star means any extension. + +For scoring purposes, there is also a |badext_list| parameter: files whose +extension is ``bad'' according to this list will get a lesser score (currently +0). + +Unfortunately, sometimes what follows a dot in a file name is not a ``real'' +extension. This often happens with readme files, for example |readme.fr| or +|readme.texlive|. So, in addition to his list of known extensions, Texdoc has +a list of known basenames, by default just |readme|. + +The corresponding settings are |basename_list| and |badbasename_list|; both +are similar to |ext_list| and |badext_list|. So, a file will be selected if +either its extension or its base name is known, and get a lesser score if +either is known to be ``bad.'' + +\subsection{Variants}\label{ss-variants} + +The documentation for a given package is often found in a file named like +|«package»-doc|. To handle this properly, Texdoc gives a special score files +named |«package»«suffix»| where |«suffix»| is one element of the list given by +the configuration setting |suffix_list|. + +To customise this list, add a line with |suffix_list = «your, list»| in a +configuration file. Be warned, it will replace the default list, no expand +it. You'll find the default list in the shipped configuration file; feel free +to suggest additions on the \tdml (with a real-life example). + +\subsection{Fuzzy search}\label{ss-fuzzy} + +When the normal search can't find any document in {\texlive}, Texdoc will +execute fuzzy search without user-interactions. The fuzzy search finds the +closest name of package in {\texlive}\footnote{Note that the feature searches +only package names at this point. Other objects such as aliases cannot be found +by the fuzzy search.} to the input |«keyword»|. The results of fuzzy search are +shown by as an informational message (you can see that with option |-v|). + +The default allowance of Levenshtein distance is 5. You can change this default +value by specifying |fuzzy_level| in your |texdoc.cnf| (see +\ref{cf-fuzzy_level}). Results of fuzzy search could be irreproducible if +multiple strings have the same Levenshtein distance. + +\clearpage + +\section{Full reference} + +\subsection{Precedence of configuration sources}\label{ss-prec} + +Values for a particular setting can come from several sources. The sources are +treated in the following order and the first value found is always used: +\begin{enumerate} + \item Command-line options. + \item Environment variables ending with |_texdoc|. + \item Other environment variables. + \item Values from configuration files (see below). + \item Hard-coded defaults that may depend on the current machine. +\end{enumerate} + +The configuration files are found in the directories |TEXMF/texdoc|, where +|TEXMF| is the kpathsea variable, in the order given by this variable. Inside +each directory, three files are recognized, in this order: +\begin{enumerate} + \item |texdoc-«platform».cnf| where |«platform»| is the name of the current + platform (defined as the name of the directories where the \texlive + binaries are located, for example |x86-64-linux|). This may be useful when + an installation is shared across machines with different architectures + needing different settings, for example for viewers. Their use is not + recommended in any other situation. + \item |texdoc.cnf| is the recommended file for normal use. + \item |texdoc-dist.cnf| is useful for installing a newer version of texdoc + (including its default configuration file) in your home while retaining + the use of the previous file for your personal setting; see + \href{https://github.com/TeX-Live/texdoc}{our GitHub repository} for + instructions on running the development version. +\end{enumerate} + +\subsection{Command-line options}\label{ss-cl} + +All command-line options (except the first four below) correspond to +configuration item that can be set in the configuration files: we refer +the reader to the corresponding section for the meaning of this configuration +item. + +\begin{cmdsubsub}{-h, --help}{cl-h} + -h, --help +\end{cmdsubsub} + +Shows a quick help message (namely a list of command-line options) and exit +successfully. + +\begin{cmdsubsub}{-V, --version}{cl-V} + -V, --version +\end{cmdsubsub} + +Shows the current version of the program and exit successfully. + +\begin{cmdsubsub}{-f, --files}{cl-f} + -f, --files +\end{cmdsubsub} + +Shows the list of configuration files for the current installation and +platform, with their status and exit successfully. Normally, only ``active'' +and ``disabled'' files are shown (see~\ref{cf-lastfile_switch}). To show ``not +found'' files as well, you can use |--verbose|. + +\begin{cmdsubsub}{--just-view}{cl-just-view} + --just-view «file» +\end{cmdsubsub} + +Open «file» in the usual viewer. The file should be given with full path, +absolutely no searching is done. This option is not really meant for users, +but rather intended to be used from another program, like a GUI front-end to +Texdoc. + +\begin{cmdsubsub}{-w, -l, -m, -s, --view, --list, --mixed, --showall}{cl-mode} + -w, --view, -l, --list, -m, --mixed, -s, --showall +\end{cmdsubsub} + +Set |mode| to the given value, see~\ref{cf-mode}. + +\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i} + -i, --interact, -I, --nointeract +\end{cmdsubsub} + +Set |interact_switch| to true (or false), see~\ref{cf-interact_switch}. + +\begin{cmdsubsub}{-M, --machine}{cl-M} + -M, --machine +\end{cmdsubsub} + +Set |machine_switch| to true, see~\ref{cf-machine_switch}. + +\begin{cmdsubsub}{-q, --quiet}{cl-q} + -q, --quiet +\end{cmdsubsub} + +Set |verbosity_level| to minimum, see~\ref{cf-verbosity_level}. + +\begin{cmdsubsub}{-v, --verbose}{cl-v} + -v, --verbose +\end{cmdsubsub} + +Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}. + +\begin{cmdsubsub}{-d, -D, --debug}{cl-d} + -d «list», --debug=«list», -D, --debug +\end{cmdsubsub} + +Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug| +without specifying a list, activates all available debug items. + +\begin{cmdsubsub}{-c}{cl-c} + -c «name»=«value» +\end{cmdsubsub} + +Set configuration item |«name»| to |«value»|. This is a general way to access +any configuration items listed in \ref{ss-conf} from command line. + +\subsection{Environment variables}\label{ss-envvar} + +They all correspond to some |viewer_«ext»| setting, and the reader is referred +to~\ref{cf-viewer_*} for details.\footnote{Old names of environment variables, +namely |TEXDOCVIEW_{html,dvi,md,txt,pdf,ps}| and +|TEXDOC_VIEWER_{HTML,DVI,MD,TXT,PDF,PS}|, are deprecated but still work.} You can +append |_texdoc| to every name in the first column: this wins over every other +name. + +\begin{center} +\begin{tabular}{ll} +Environment variables & Configuration items \\ +|BROWSER| & |viewer_html| \\ +|DVIVIEWER| & |viewer_dvi| \\ +|MDVIEWER| & |viewer_md| \\ +|PAGER| & |viewer_txt| \\ +|PDFVIEWER| & |viewer_pdf| \\ +|PSVIEWER| & |viewer_ps| \\ +\end{tabular} +\end{center} + +Also, on Unix systems, locale-related variables such as |LANG| and |LC_ALL| +are used for the default value of |lang|. + +\subsection{Configuration items}\label{ss-conf} + +\subsubsection{Structure of configuration files}\label{sss-sonf-struct} + +Configuration files are line-oriented text files. Comments begin with a |#| +and run to the end of line. Lines containing only space are ignored. Space at +the beginning or end of a line, as well as around an |=| sign, is ignored. +Apart from comments and empty lines, each line must be of one of the following +forms. + +\begin{htcode} + «configuration item» = «value» + alias «original keyword» = «name» + alias(«score») «original keyword» = «name» + stopalias «original keyword» + adjscore «pattern» = «score adjustment» + adjscore(«keyword») «pattern» = «score adjustment» +\end{htcode} + +We will concentrate on the |«configuration item»| part here, since other +directives have already been presented (\ref{ss-alias} and \ref{ss-score}). + +In the above, |«value»| never needs to be quoted: quotes would be interpreted +as part of the value, not as quotation marks (this also holds for the other +directives). + +Lines which do not obey these rules raise a warning, as well as unrecognised +values of |«configuration item»|. The |«value»| can be an arbitrary string, +except when the name of the |«configuration item»| ends with: +\begin{enumerate} + \item |_list|, then |«value»| is a coma-separated list of strings. Space + around commas is ignored. Two consecutive comas or a coma at the beginning + or end of the list means the empty string at the corresponding place. + \item |_switch|, then |«value»| must be either |true| or |false| + (lowercase). + \item |_level|, then |«value»| is an integer. +\end{enumerate} +In these cases, an improper |«value»| will raise a warning too. + +\begin{cmdsubsub}{mode}{cf-mode} + mode = «view, list, mixed, showall» +\end{cmdsubsub} +Set the mode to the given value. Default is |view|. The various modes +have been presented in~\ref{ss-modes}. + +\begin{cmdsubsub}{interact}{cf-interact_switch} + interact_switch = «true, false» +\end{cmdsubsub} + +Turn on or off interaction. Default is on. Turning interaction off prevents +Texdoc from asking you to choose a file to view when there are multiple +choices, so it just prints the list of files found. + +\begin{cmdsubsub}{suffix_list}{cf-suffix_list} + suffix_list = «list» +\end{cmdsubsub} + +Set the list of known suffixes to |«list»| (see~\ref{ss-variants}). Default is +the empty list, but see the shipped configuration file for more. + +\begin{cmdsubsub}{ext_list}{cf-ext_list} + ext_list = «list» +\end{cmdsubsub} + +Set the list of recognised extensions to |«list»|. The default value is: +% +\begin{htcode} + pdf, html, htm, txt, md, dvi, ps, +\end{htcode} +% +This list is used to filter and sort the results that have the same +score (with the default value: pdf first, etc). Two special values are +recognised: +\begin{itemize} + \item \emph{The empty element}. This means files without extensions, or more + precisely without a dot in their name. This is meant for files like + |README|, etc. The file is assumed to be plain text for viewing purpose. + \item |*| means any extension. Of course if it is present in the list, it + can be the only element! +\end{itemize} + +There is a very special case: if the searched |«name»| has |.sty| extension, +Texdoc enters a special search mode for |.sty| files (not located in the same +place as real documentation files) for this |«name»|, independently of the +current value of |ext_list| and |mode|. In an ideal world, this wouldn't be +necessary since every sty file would have a proper documentation in pdf, html +or plain text, but\dots + +For each |«ext»| in |ext_list| there should be a corresponding |viewer_«ext»| +value set. Defaults are defined corresponding to the default |ext_list|, but +you can add values if you want. For example, if you want Texdoc to be able +to find man pages and display them with the |man| command, you can use +\begin{htcode} + ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps, + viewer_1 = man + viewer_5 = man +\end{htcode} + +As a special case, if the extension is |sty|, then the |txt| viewer is used; +similarly, if it is |htm| the |html| viewer is used. Otherwise, the |txt| +viewer is used and a warning is issued. + +\begin{cmdsubsub}{badext_list}{cf-badext_list} + badext_list = «list» +\end{cmdsubsub} + +Set the list of ``bad'' extensions to |«list»|. Default is ``|txt,|''. Files +with those extensions get a malus of |1| on their heuristic score if it was +previously positive. + +\begin{cmdsubsub}{basename_list}{cf-basename_list} + basename_list = «list» +\end{cmdsubsub} + +Set the list of ``known'' base names to |«list»|. Default is ``|readme|''. +Files with those base names are selected regardless of their extension. If the +extension is unknown, the text viewer will be used to view the file. + +\begin{cmdsubsub}{badbasename_list}{cf-badbasename_list} + badbasename_list = «list» +\end{cmdsubsub} + +Set the list of ``bad'' base names to |«list»|. Default is ``|readme|''. Files +with those names get a malus of |1| on their heuristic score if it was +previously positive. + +\begin{cmdsubsub}{viewer_*}{cf-viewer_*} + viewer_«ext» = «cmd» +\end{cmdsubsub} + +Set the viewer command for files with extension |«ext»| to |«cmd»|. For files +without extension, |viewer_txt| is used, and there's no |viewer_| variable. +In |«cmd»|, |%s| can be used as a placeholder for the file name, which is +otherwise inserted at the end of the command. The command can be an arbitrary +shell construct. + +\begin{cmdsubsub}{lang}{cf-lang} + lang = «2-letter code» +\end{cmdsubsub} + +Set you preferred language. Defaults to your system's locale. + +\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level} + verbosity_level = «n» +\end{cmdsubsub} + +Set the verbosity level to |«n»| (default: 2). At level~3, errors, warnings and +informational messages will be printed on stderr; 2 means only errors and +warnings, 1 only errors and 0 nothing except internal errors (obviously not +recommended). + +\begin{cmdsubsub}{debug_list}{cf-debug_list} + debug_list = «list» +\end{cmdsubsub} + +Set the list of activated debug items (default: none). Available debug items +are |config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|, +|view|, and |all| to activate all of these. Implies |--verbose|. Debug +information are printed on standard error. + +\begin{cmdsubsub}{max_line}{cf-max_lines} + max_lines = «number» +\end{cmdsubsub} + +Set the maximum number of results to be printed without confirmation in list, +mixed or showall mode (default: 20). This setting has no effect if interaction +is disabled. + +\begin{cmdsubsub}{machine_switch}{cf-machine_switch} + machine_switch = «true, false» +\end{cmdsubsub} + +Turn on or off machine-readable output (default: off). With this option +active, the value of |interact_switch| is forced to |false|, and each line of +output is +\begin{htcode} + «argument»\t«score»\t«filename» +\end{htcode} +where |«argument»| is the name of the argument to which the results correspond +(mainly useful if there were many arguments), |\t| is the tab (ASCII \#9) +character, and the other entries are pretty self-explanatory. Nothing else is +printed on stdout, except if an internal error occurs (in which case exit code +will be 1). In the future, more tab-separated fields may be added at the end +of the line, but the first 3 fields will remain unchanged. + +Currently, there are two additional fields: a two-letter language code, and an +unstructured description, both taken from the CTAN catalogue (via the \texlive +database). These fields may be empty, and they are not guaranteed to keep the +same meaning in future versions of Texdoc. + +\begin{cmdsubsub}{zipext_list}{cf-zipext_list} + zipext_list = «list» +\end{cmdsubsub} + +List of supported extensions for zipped files (default: empty). Allows +compressed files with names like |foobar.«zip»|, with |«zip»| in the given +|«list»|, to be found and unzipped before the viewer is started (the +temporary file will be destroyed right after). + +\textbf{Warning.} Support for zipped documentation is not meant to work on +windows, a Unix shell is assumed! If you add anything to this list, please make +sure that you also set a corresponding |unzip=«ext»| value for each |«ext»| in +the list. At the same time, make sure you are using blocking (i.e., not +returning immediately) viewers. + +\textit{Remark.} \texlive doesn't ship compressed documentation files, so +this option is mainly useful with re-packaged version of \texlive that do, +for example in Linux distributions. + +\begin{cmdsubsub}{unzip_*}{cf-unzip_star} + unzip_«zipext» = «command» +\end{cmdsubsub} + +The unzipping command for compressed files with extension |«zipext»| (default: +none). Define one for each item in |zipext_list|. The command must print +the result on stdout, like |gzip -d -c| does. + +\begin{cmdsubsub}{rm_file, rm_dir}{cf-rm_star} + rm_file = «command» + rm_dir = «command» +\end{cmdsubsub} + +Commands for removing files (resp. directories) on your system (defaults: +|rm -f| and |rmdir|). Only useful for zipped documents (see |zipext_list|). + +\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch} + lastfile_switch = «true, false» +\end{cmdsubsub} + +If set to true, prevents Texdoc from reading any other configuration file after +this one (they will be reported as ``disabled'' by |texdoc -f|). Mainly useful +for installing a newer version of Texdoc in your home and preventing the +default configuration file from older versions to be used (see the +\href{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do +so). + +\begin{cmdsubsub}{fuzzy_level}{cf-fuzzy_level} + fuzzy_level = «n» +\end{cmdsubsub} + +Set the allowance of Levenshtein distance to |«n»| for the fuzzy search +(default: 5). At level 0, the fuzzy search feature is disabled. + +\subsection{Exit codes}\label{ss-exit} + +The current exit codes are: +\begin{enumerate}[start=0] + \item Success. + \item Internal error. + \item Usage error. + \item No documentation found. +\end{enumerate} + +\section{Licence}\label{s-licence} + +The current version of Texdoc program and its documentation are copyright 2008 +Manuel Pégourié-Gonnard, Takuto Asakura, and the {\texlive} Team. + +They are free software: you can redistribute it and/or modify it under the +terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +This program is distributed in the hope that it will be useful, but +\emph{without any warranty}; without even the implied warranty of +\emph{merchantability} or \emph{fitness for a particular purpose}. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see \url{http://www.gnu.org/licenses/}. + +\bigskip + +Previous work (Texdoc program) in the public domain: +\begin{itemize} + \item Contributions from Reinhard Kotucha (2008). + \item First texlua versions by Frank Küster (2007). + \item Original shell script by Thomas Esser, David Aspinall, and Simon + Wilkinson. +\end{itemize} + +\bigskip +\begin{center}\Large\bfseries + Happy {\TeX}ing! +\end{center} + +\end{document} +% vim: ambiwidth=single spell: |