Debian Codegraph @

texmf-dist/doc/support/texdoc/texdoc.tex

raw
1 %#!texfot xelatex
2 % Texdoc user manual
3 % Copyright 2008-2025 Manuel Pégourié-Gonnard and Takuto Asakura
4 % distributed under the terms of GPL v3 or later
5 \documentclass{texdoc-doc}
6
7 \title{Texdoc}
8 \subtitle{Find \& view documentation in \TL}
9 \pkgurl{https://tug.org/texdoc/}
10 \author{Manuel Pégourié-Gonnard\and Takuto Asakura}
11 \date{v4.1.1\quad \today}
12
13 \begin{document}
14
15 \VerbatimFootnotes
16
17 \maketitle
18
19 \section{Quick Guide}
20
21 Texdoc is a command-line tool to find and view documents in {\TL}. Typing
22 %
23 \begin{htcode}
24 texdoc «name»
25 \end{htcode}
26 %
27 in your command line, you will see a document of the |«name»| package is popped
28 up. Of course, you have to replace |«name»| with the actual name of a package.
29 To look up the documentation of more than one packages at once, just give
30 multiple |«name»|s as arguments.
31
32 \subsection{Modes}
33 \label{sec:modes}
34
35 Texdoc has several modes that determine how results will be returned. The
36 default is \emph{view} mode, which opens the first, that is supposedly the
37 best, result with a suitable viewer. It is rather handy when you know what you
38 want to read. On the other hand, there may be other relevant documents for the
39 given |«name»|, which are ignored in the view mode.
40
41 In the \emph{list} mode, Texdoc lists all relevant documentation and ask you
42 which one you want to view. This mode is useful when there are other
43 interesting sources of information in addition to the main documentation of a
44 package.
45
46 There is also a \emph{mixed} mode, intended to get the best of the view mode
47 and list mode: if there is only one good result, then Texdoc opens it in a
48 viewer, like in the view mode. Otherwise, it offers you a menu, like in the
49 list mode.
50
51 By default, Texdoc hides some results, which expected to be less relevant,
52 unless it cannot find any relevant result. In the \emph{showall} mode, Texdoc
53 always shows all results, including bad ones.
54
55 A couple of command-line options are available for selecting the mode to
56 execute: \sopt{w} (\lopt{view}) for the view mode, \sopt{m} (\lopt{mixed}) for
57 the mixed mode, \sopt{l} (\lopt{list}) for the list mode, and \sopt{s}
58 (\lopt{showall}) for the showall mode.
59
60 If you have your favorite mode and always use it, you may not want to keep
61 typing the same option. The next section describes how to customize Texdoc
62 using its configurations files.
63
64 \subsection{Configuration files}
65 \label{sec:quick-file}
66
67 The configuration file enables you to tweak Texdoc in many ways. You can use
68 the \lopt{files} option to know where to put your personal configuration file;
69 you may need to create this file, possibly with some parent directories. If you
70 want to know the full list of possible configuration files, see
71 Section~\ref{sec:prec}.
72
73 To set your favorite mode, just insert a line |\ci{mode} = «mode»| in your
74 personal configuration file, where |«mode»| is one of |view|, |mixed|, |list|,
75 and |showall|. Though your preferred language is usually detected automatically
76 by getting the system locale, you can set it explicitly with a line
77 |\ci{lang} = «2-letter code»| in the configuration file.
78
79 \subsection{Viewers}
80 \label{sec:viewer}
81
82 The way of Texdoc for choosing a viewer varies according to your platform. On
83 Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
84 associations like when you double-click files in the Explorer, the Finder or
85 your default file manager (except for the text viewer, which is always a
86 pager). Otherwise, it tries to find a viewer in the path from a list of
87 ``known'' viewers.
88
89 You may want to use a different viewer for some types of documents. This can be
90 achieved by setting the various \ci{viewer\_\meta{ext}} configuration items,
91 where |«ext»| is an extension corresponding to a file type. For example, if
92 you want to set \code{xpdf} as your default PDF viewer, and run it in the
93 background, insert the line |viewer_pdf = xpdf %s &| in your configuration
94 file. Herein, |%s| is a place holder for the name of the file to view.
95
96 \subsection*{\underline{You can stop reading now}}
97
98 The following parts explain the mechanisms of Texdoc for finding the best
99 results and how to customize them. We have been trying hard to optimize the
100 default configuration values so that normal users do not need to fiddle with
101 it. Thus, the following parts are useful only when you are curious or have
102 special needs.
103
104 \clearpage
105
106 \section{Controlling Texdoc}
107
108 \subsection{Command-line options}
109 \label{sec:cl}
110
111 The full usage of Texdoc can be summarized as follows:
112 %
113 \begin{htcode}
114 texdoc «names»
115 texdoc «options» «names»
116 texdoc «action»
117 texdoc «options» «action»
118 \end{htcode}
119
120 We have tried to implement a GNU-compatible option parser. Short options, each of
121 which consists of a single letter, must start with a single hyphen |-|.
122 Multiple short options can be specified with a single hyphen, \eg |-vl| is
123 equivalent to |-v -l|. Long options have to be following double hyphens |--|.
124 All options must be specified before the first argument. A String beginning
125 with a hyphen after the first argument will be treated as an argument starting
126 with a hyphen.
127
128 Some options are called action options, which can be used for |«action»| in the
129 above usage. Four actions are available:
130
131 \begin{clopt}{\sopt{h}, \lopt{help}}
132 Shows a quick help message (namely a list of command-line options) and exit
133 successfully.
134 \end{clopt}
135
136 \begin{clopt}{\sopt{V}, \lopt{version}}
137 Shows the current version of the program and exit successfully.
138 \end{clopt}
139
140 \begin{clopt}{\sopt{f}, \lopt{files}}
141 Shows the list of configuration files for the current installation and
142 platform, with their status and exit successfully. Normally, only ``active''
143 and ``disabled'' files are shown (see~\ci{lastfile\_switch}). To show ``not
144 found'' files as well, you can use \lopt{verbose}.
145 \end{clopt}
146
147 \begin{clopt}{\code{\lopt{just-view} \meta{file}}}
148 Open |«file»| in the usual viewer. The file should be given with full path,
149 absolutely no searching is done. This option is not really meant for users,
150 but rather intended to be used from another program, like a GUI front-end to
151 Texdoc.
152 \end{clopt}
153
154 \begin{clopt}{\code{\lopt{print-completion} \meta{shell}}}
155 Print |«shell»| completion. For the time being, it only supports
156 zsh\footnote{Your contributions are welcome!}. See
157 Section~\ref{sec:completion} for the details.
158 \end{clopt}
159
160 Some normal options such as \sopt{v} are effective for some actions but note
161 that you have to specify such options \emph{before} the action option. Options
162 after an action option will be ignored.
163
164 The followings are other normal command-line options:
165
166 \begin{clopt}{\sopt{w}, \lopt{view}}[default]
167 Set \ci{mode} to |view|. Texdoc will open the best results it found by the best
168 application it knows. See Section~\ref{sec:modes}.
169 \end{clopt}
170
171 \begin{clopt}{\sopt{l}, \lopt{list}}
172 Set \ci{mode} to |list|. Texdoc will show the lists of all relevant documents
173 it found and ask you which to open. When used with the \lopt{nointeract}
174 option, Texdoc will just show the lists of documents and exit successfully.
175 \end{clopt}
176
177 \begin{clopt}{\sopt{m}, \lopt{mixed}}
178 Set \ci{mode} to |mixed|. If Texdoc finds only a document for your keyword,
179 then it opens it, and if it finds multiple, then it will behave like in the
180 |list| mode.
181 \end{clopt}
182
183 \begin{clopt}{\sopt{s}, \lopt{showall}}
184 Set \ci{mode} to |showall|. It also behave like in a |list| mode, but show all
185 the documents it found including documents which seem to be not a good result.
186 \end{clopt}
187
188 \begin{clopt}{\sopt{i}, \lopt{interact}}[default]
189 Texdoc may require user reactions, \eg ask you which document to open in the
190 |list| mode. Internally, this sets \ci{interact\_switch} to |true|.
191 \end{clopt}
192
193 \begin{clopt}{\sopt{I}, \lopt{nointeract}}
194 If this is specified, Texdoc will never request any input from users.
195 Internally, this sets \ci{interact\_switch} to |false|.
196 \end{clopt}
197
198 \begin{clopt}{\sopt{M}, \lopt{machine}}
199 This make the result list of Texdoc machine-readable. Only effective for the
200 |list| mode and its friends. This option implies \lopt{nointeract}.
201 Internally, this sets \ci{machine\_switch} to |true|.
202 \end{clopt}
203
204 \begin{clopt}{\sopt{q}, \lopt{quiet}}
205 This suppress warnings and most error messages. Internally, this sets
206 \ci{verbosity\_level} to minimum.
207 \end{clopt}
208
209 \begin{clopt}{\sopt{v}, \lopt{verbose}}
210 Make Texdoc to print additional information such as viewer commands which are
211 invoked by the program. Internally, this sets \ci{verbosity\_level} to maximum.
212 \end{clopt}
213
214 \begin{clopt}{%
215 \code{\sopt{d} \meta{list}}, \code{\lopt{debug}=\meta{list}},
216 \sopt{D}, \lopt{debug}}
217 This sets \ci{debug\_list} to show debugging information in the specified
218 category. You can specify multiple categories with a comma-separated list. If
219 you specify |-D| or |--debug| without specifying a list, it activates all
220 available debug categories.
221 \end{clopt}
222
223 \begin{clopt}{\code{\sopt{c} \meta{name}=\meta{value}}}
224 This enables you to set arbitrary configuration items |«name»| to |«value»|
225 from the command-line. See Section~\ref{sec:conf} for the list of all available
226 configuration items.
227 \end{clopt}
228
229 \subsection{Environment variables}
230 \label{sec:envvar}
231
232 Some environment variables affect the behavior of Texdoc. The environment
233 variables can be roughly categorized into three groups.
234
235 First, as well as other programs in {\TL}, searching path for the Texdoc are
236 determined with the Kpathsea variables like |TEXMF*|. The mechanism of Kpathsea
237 is complex, so please refer to `the {\TL} Guide', which supposed to be open by
238 |texdoc texlive|, and the document of Kpathsea for the details. Usually, Texdoc
239 searches documents for the |TEXMF| trees including |TEXMFDIST|, |TEXMFLOCAL|,
240 and |TEXMFHOME| and trees specified in |TEXDOCS|. It also self-locates its own
241 program using |TEXMF| search path. In addition, Texdoc uses |TEXMFROOT| and
242 |TEXMFVAR| to look for the tlpdb database and the cache respectively.
243
244 Second, the viewers for opening documents can be controlled by some environment
245 variables. They all correspond to some \ci{viewer\_\meta{ext}}
246 setting.\footnote{Old names of environment variables, namely
247 |TEXDOCVIEW_\{html,dvi,md,txt,pdf,ps\}| and
248 |TEXDOC_VIEWER_\{HTML,DVI,MD,TXT,PDF,PS\}|, are deprecated but still work.} You
249 can append |_texdoc| to every name in the first column: this wins over every
250 other name. These variables can be split by colon |:| and the first non-nil
251 occurrence is used. If a viewer command contains colon, please specify it by
252 \ci{viewer\_\meta{ext}}.
253 %
254 \begin{center}
255 \begin{tabular}{lll}
256 Variable & Use for & Configuration item \\ \hline
257 |BROWSER| & HTML files & |viewer_html| \\
258 |DVIVIEWER| & DVI files & |viewer_dvi| \\
259 |MDVIEWER| & Markdown files & |viewer_md| \\
260 |PAGER| & Text files & |viewer_txt| \\
261 |PDFVIEWER| & PDF files & |viewer_pdf| \\
262 |PSVIEWER| & PS files & |viewer_ps| \\
263 \end{tabular}
264 \end{center}
265
266 Third, locale-related variables |LANGUAGE_texdoc|, |LANGUAGE|, |LC_ALL|, and
267 |LANG| are used to set \ci{lang}.
268
269 \subsection{Precedence of configuration sources}
270 \label{sec:prec}
271
272 Values for a particular setting can come from several sources. The sources are
273 looked at in the following order and the first value found is always used:
274 %
275 \begin{enumerate}
276 \item Command-line options.
277 \item Environment variables ending with |_texdoc|.
278 \item Other environment variables.
279 \item Values from configuration files (see below).
280 \item Hard-coded defaults that may depend on the current machine.
281 \end{enumerate}
282
283 The configuration files are found in the directories \path{TEXMF/texdoc}, where
284 \path{TEXMF} is the kpathsea variable, in the order given by this variable.
285 Inside each directory, three files are recognized, in this order:
286 %
287 \begin{enumerate}
288 \item |texdoc-«platform».cnf| where |«platform»| is the name of the current
289 platform (defined as the name of the directories where the {\TL}
290 binaries are located, for example |x86_64-linux|). This may be useful when
291 an installation is shared across machines with different architectures
292 needing different settings, for example for viewers. Their use is not
293 recommended in any other situation.
294 \item |texdoc.cnf| is the recommended file for normal use.
295 \item |texdoc-dist.cnf| is useful for installing a newer version of texdoc
296 (including its default configuration file) in your home while retaining
297 the use of the previous file for your personal setting; see
298 {\TexdocRepo} for instructions on running the development version.
299 \end{enumerate}
300
301 \subsection{Exit codes}
302 \label{sec:exit}
303
304 The status of Texdoc, which is whether or not it was successfully executed and
305 an expected result was delivered, can be grasped by seeing its exit code. This
306 will be useful to manage Texdoc by other programs. The current exit codes of
307 Texdoc are:
308 %
309 \begin{description}[left=2em]
310 \item[\code{0}] Success.
311 \item[\code{1}] Internal error.
312 \item[\code{2}] Usage error.
313 \item[\code{3}] No documentation found.
314 \end{description}
315
316 \section{Customizing the Search Results}
317
318 \subsection{An overview of how Texdoc works}
319
320 When you type |texdoc «keyword»|, first filenames related to the |«keyword»|
321 are collected from the two following sources.
322 %
323 \begin{enumerate}
324 \item the |TEXMF| trees containing documentation that specified by the
325 \href{https://www.tug.org/kpathsea/}{kpathsea} variable |TEXDOCS|: Texdoc
326 collects all files containing |«keyword»| in their filenames or in the names
327 of their parent directories.
328 \item the {\TL} Database (|texlive.tlpdb|): Texdoc searches for packages named
329 |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be |sty|
330 or |cls|, and collects all document files of the found packages.
331 \end{enumerate}
332
333 Second, the collected filenames are filtered by their extensions. After
334 filtering, only files with known extensions (listed in \ci{ext\_list}) remain.
335 If Texdoc cannot find any documentation, the fuzzy search will find the closest
336 package name to the |«keyword»| and it will recollect document files (see
337 Section~\ref{sec:fuzzy}).
338
339 Third, the collected filenames are given numeric scores by using some
340 heuristics. For example, a filename |«keyword».pdf| is good, and thus gets a
341 high score. A name |«keyword»-«lang».pdf| is also good and gets a higher score
342 if the |«lang»| is the preferred language code in your configuration. In
343 addition, there are several rules such as ``a name |«keyword»-doc| always wins
344 over any names |«keyword»whatever|'' and ``files under a directory named
345 exactly |«keyword»| get bonuses''. Scores may also be adjusted based on the
346 extensions and some known names or subwords. For example, by default,
347 |Makefile|s get very low scores because basically they are not
348 documents.\footnote{Nevertheless, they often end up in the |doc| trees,
349 because in {\TL}, sources of documents are usually in the same directory as the
350 documents themselves. Other source files for documents are discriminated by
351 their extensions.}
352
353 Finally, a file with the highest score is opened with a viewer, or the list
354 of results is shown, depending on the current mode. Usually, only results with
355 positive scores are displayed, except in the |showall| mode. Results with very
356 bad scores, that are lower than |-100|, are never displayed.
357
358 This model for searching and scoring is efficient, but unfortunately, it is not
359 perfect: Texdoc may sometimes need a hint, either to find a relevant file or,
360 more likely, to recognize which of the found files is the best. For example,
361 suppose you are looking for a document of the {\LaTeX} package |shortvrb|.
362 Texdoc will successfully find |shortvrb.sty| in the {\TL} package |latex|.
363 However, Texdoc will not be able to sort a number of documents in the |latex|
364 package correctly because none of them contains the string |shortvrb|.
365
366 For such cases, \emph{aliases} are useful: in the default configuration file,
367 |shortvrb| is aliased to |base/doc|, so that Texdoc primarily look for
368 |base/doc| when you type |texdoc shortvrb|. Note that Texdoc will also look for
369 the original keyword, and that a name can be aliased to more than one new
370 name.
371
372 \subsection{Aliases}
373 \label{sec:alias}
374
375 Aliases can be set in configuration files of Texdoc with the following syntax:
376 %
377 \begin{htcode}
378 alias «original keyword» = «name»
379 alias(«score») «original keyword» = «name»
380 \end{htcode}
381 %
382 A number of aliases are already set in the default configuration file. You can
383 also define your own aliases in your personal configuration files (see
384 Section~\ref{sec:quick-file} or \ref{sec:prec} to know where is that). For example,
385 you can add a line
386 %
387 \begin{htcode}
388 alias td = texdoc
389 \end{htcode}
390 %
391 to the file to alias |td| to |texdoc|. Then, files in the doc trees matching
392 exactly with |texdoc|, \ie this document |texdoc.pdf|, will be added to the
393 result list when you search for the keyword |td|.
394
395 By default, files match with the aliased name get a score of |10|. This score
396 is greater than any result of heuristic scoring. It means that results found
397 via aliases will always be ranked higher than results found for the original
398 keyword. If you want the results associated with a particular alias to have a
399 custom score instead of the default score |10|, you can use the optional
400 argument to the |alias| directive. This can be useful if you associate multiple
401 aliases to a keyword and want to specify the priorities for them.
402
403 In addition, aliases for |«keyword»-«lang»|, where |«lang»| is your preferred
404 language's 2-letter code (as detected or configured, see the |lang| option), are
405 also used when searching for |«keyword»|. Files match with these language-based
406 aliases get additional bonus scores so that they win over the results for
407 language-independent aliases.
408
409 For concrete examples, please have a look at the default configuration file,
410 which can be found in the last line of the output for |texdoc -f|. If you think
411 aliases you defined locally should be added to the default configuration,
412 please share the idea to the {\TexdocML} or {\TexdocRepo}.
413
414 Aliases are additive: if you define your own aliases for a keyword in your
415 configuration file, and there are also aliases for the same keyword in the
416 default configuration, they will add up. To prevent the default aliases from
417 being applied for a particular keyword, add a line |stopalias «keyword»| in
418 your personal configuration file. It will preserve the aliases defined before
419 this directive if any, but prevent all further aliasing on this keyword.
420
421 Here are some notes for aliases. First, they are case-insensitive. Second, they
422 do not work recursively: only aliases set to the original keyword are used.
423 Third, results found for aliases always get the score defined by the |alias|
424 directive (|10| by default). The adjustments described in the other subsections
425 are not applied to results for aliases.
426
427 \subsection{Score adjustments}
428 \label{sec:score}
429
430 Scores can be arbitrary adjusted by using the |adjscore| directive in the
431 configuration files. The adjustment can be done either for global, \ie for any
432 keywords, or a particular keyword. The syntax is as follow:
433 %
434 \begin{htcode}
435 adjscore «pattern» = «score adjustment»
436 adjscore(«keyword») «pattern» = «score adjustment»
437 \end{htcode}
438 %
439 When the optional argument |«keyword»| is specified, the adjustment will be
440 applied only when a user searches for the |«keyword»|. Otherwise, the
441 adjustment applied always for the |«pattern»|.
442
443 Here are a few examples from the default configuration file.
444
445 \begin{htcode}
446 adjscore /Makefile = -1000
447 adjscore /tex-virtual-academy-pl/ = -50
448 adjscore(tex) texdoc = -10
449 \end{htcode}
450 %
451 Herein, all files named |Makefile|, and those with suffixes, \eg |Makefile.in|,
452 will be eliminated from results: by adjusting their score with such a large
453 negative value, their final score will be less than |-100|. Which means they
454 will never be displayed. Files from the |tex-virtual-academy-pl| directory, on
455 the other hand, are not eliminated but get a negative adjustment, since they
456 are a common source of ``fake'' matches which hide better results. The third
457 line gives a minus adjustment for results containing |texdoc| only when the
458 searched keyword is |tex|. Otherwise, such results would get high scores
459 because the heuristic scoring would assume |texdoc| is the name of
460 documentation for {\TeX} itself. The adjustment value |-10| is enough to ensure
461 that those results will have a negative score, so the files containing |texdoc|
462 will not be displayed unless |showall| mode is used.
463
464 Note that the values of scores, such as the default score for aliases and the
465 range of heuristic scores, may be changed in a future version of Texdoc.
466 Therefore, you may need to adapt your score adjustments after updating Texdoc
467 in the future.
468
469 \subsection{Extensions and basenames of files}
470 \label{sec:ext}
471
472 File extensions regarded as documents by Texdoc can be specified with the
473 configuration item \ci{ext\_list}. By default, files with extensions |pdf|,
474 |html|, |htm|, |txt|, |dat|, |md|, |ps|, and |dvi| and files without extension
475 are recognized as documents.
476
477 During the scoring process, the configuration item \ci{badext\_list} is also used:
478 files with a ``bad'' extension appearing in this list will get a lesser score.
479
480 In the practical filenames, things which are not actually extensions can follow
481 dots, \eg |readme.fr| and |readme.texlive|. Thus, in addition to the lists of
482 known extensions, Texdoc has lists for known basenames: \ci{basename\_list} and
483 \ci{badbasename\_list}. These configuration items are respectively similar to
484 \ci{ext\_list} and \ci{badext\_list}. In short, a file will be selected if
485 either its extension or its basename is known, and get a lesser score if either
486 is known to be ``bad''.
487
488 \subsection{Common filenames}
489 \label{sec:common-names}
490
491 Document filenames of packages are often in the form of |«package»-doc|.
492 Respecting this culture in the {\TeX} community, Texdoc gives a special score
493 for files named |«package»«suffix»|, where |«suffix»| is an element of the list
494 \ci{suffix\_list}. Please refer to the shipped configuration file for the
495 default setting. Also, feel free to suggest additional elements for the list to
496 the {\TexdocML} with a real-life example.
497
498 \subsection{Fuzzy search}
499 \label{sec:fuzzy}
500
501 When the normal search cannot find any document in {\TL}, Texdoc will execute a
502 fuzzy search. The fuzzy search tries to find the closest name of a package in
503 {\TL}\footnote{Note that the feature searches only package names at this point.
504 Other objects such as aliases cannot be found by the fuzzy search.} to the
505 input |«keyword»|. The results of the fuzzy search are shown in an info
506 message, which can be seen by using the command-line option |-v|.
507
508 The default allowance of Levenshtein distance is |3|. You can change this
509 allowance by using the configuration item \ci{fuzzy\_level}. Results of fuzzy
510 search could be different among executions if multiple package names have the
511 same Levenshtein distance to the input.
512
513 \subsection{Online Search}
514 \label{sec:online}
515
516 If Texdoc cannot find any good matches for a document, it may sometimes prompt
517 you to search online.
518
519 If you use the |view| option, there are no ``good'' matches (|score|${}\ge{}$0),
520 but you have some local documentation installed, Texdoc will show you the three
521 best locally-installed documents while also prompting you to search online.
522
523 If you use the |view| option when you have no local documentation installed,
524 Texdoc will skip showing any fuzzy matches, and will instead prompt you to
525 search online immediately.
526
527 Texdoc checks to see if the |kpathsea| documentation as a heuristic for if
528 \emph{any} documentation is installed. If the documentation for Texdoc is
529 installed, but no other documentation is installed, the online search prompt
530 may produce unexpected results.
531
532 \section{Configuration items}
533 \label{sec:conf}
534
535 Configuration files are line-oriented text files. Comments begin with a |#|
536 and run to the end of line. Lines containing only space are ignored. Space at
537 the beginning or end of a line, as well as around an |=| sign, is ignored.
538 Apart from comments and empty lines, each line must be of one of the following
539 forms:
540 %
541 \begin{htcode}
542 «configuration item» = «value»
543 alias «original keyword» = «name»
544 alias(«score») «original keyword» = «name»
545 stopalias «original keyword»
546 adjscore «pattern» = «score adjustment»
547 adjscore(«keyword») «pattern» = «score adjustment»
548 \end{htcode}
549 %
550 You can put a backslash (\code{\char`\\}) at the end of a line to indicate that
551 the line is continued on the following line.
552
553 We will concentrate on the |«configuration item»| part here, since other
554 directives have already been presented (Section~\ref{sec:alias} and
555 \ref{sec:score}).
556
557 In the above, |«value»| never needs to be quoted: quotes would be interpreted
558 as part of the value, not as quotation marks (this also holds for the other
559 directives).
560
561 Lines which do not obey these rules raise a warning, as well as unrecognised
562 values of |«configuration item»|. The |«value»| can be an arbitrary string,
563 except when the name of the |«configuration item»| ends with:
564 %
565 \begin{enumerate}
566 \item |_list|, then |«value»| is a coma-separated list of strings. Spaces
567 around commas are ignored. Two consecutive comas or a coma at the beginning
568 or end of the list means the empty string at the corresponding place.
569 \item |_switch|, then |«value»| must be either |true| or |false|
570 (lowercase).
571 \item |_level| and |_lines|, then |«value»| is an integer.
572 \end{enumerate}
573 %
574 In these cases, an improper |«value»| will raise a warning too.
575
576 \begin{confitem}{mode}
577 {\choice{view, list, mixed, showall}}[default: \code{view}]
578 Set the mode to the given value. The various modes have been described
579 in Section~\ref{sec:modes}.
580 \end{confitem}
581
582 \begin{confitem}{interact\_switch}{\choice{true, false}}[default: \code{true}]
583 Turn on or off interaction. Turning interaction off prevents Texdoc from asking
584 you to choose a file to view when there are multiple choices, so it just prints
585 the list of files found.
586 \end{confitem}
587
588 \begin{confitem}{suffix\_list}{\meta{list}}[default: empty]
589 Set the list of known suffixes to |«list»| (see
590 Section~\ref{sec:common-names}). Default is the empty list, but see the
591 shipped configuration file for more.
592 \end{confitem}
593
594 \begin{confitem}{ext\_list}
595 {\meta{list}}[default: \code{pdf, html, htm, txt, dat, md, dvi, ps,}]
596 Set the list of recognised extensions to |«list»|. This list is used to filter
597 and sort the results that have the same score (with the default value: pdf
598 first, etc). Two special values are recognised:
599 %
600 \begin{itemize}
601 \item \emph{The empty element}. This means files without extensions, or more
602 precisely without a dot in their name. This is meant for files like
603 |README|, etc. The file is assumed to be plain text for viewing purpose.
604 \item |*| means any extension. Of course if it is present in the list, it
605 can be the only element!
606 \end{itemize}
607
608 There is a very special case: if the searched |«name»| has |.sty| extension,
609 Texdoc enters a special search mode for |.sty| files (not located in the same
610 place as real documentation files) for this |«name»|, independently of the
611 current value of |ext_list| and |mode|. In an ideal world, this wouldn't be
612 necessary since every sty file would have a proper documentation in pdf, html
613 or plain text, but\dots
614
615 For each |«ext»| in |ext_list| there should be a corresponding |viewer_«ext»|
616 value set. Defaults are defined corresponding to the default |ext_list|, but
617 you can add values if you want. For example, if you want Texdoc to be able
618 to find man pages and display them with the |man| command, you can use
619 %
620 \begin{htcode}
621 ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps,
622 viewer_1 = man
623 viewer_5 = man
624 \end{htcode}
625
626 As a special case, if the extension is |sty|, then the |txt| viewer is used;
627 similarly, if it is |htm| the |html| viewer is used. Otherwise, the |txt|
628 viewer is used and a warning is issued.
629 \end{confitem}
630
631 \begin{confitem}{badext\_list}{\meta{list}}[default: \code{txt, dat,}]
632 Set the list of ``bad'' extensions to |«list»|. Files with those extensions get
633 a malus of |1| on their heuristic score if it was previously positive.
634 \end{confitem}
635
636 \begin{confitem}{basename\_list}
637 {\meta{list}}[default: \code{readme, 00readme}]
638 Set the list of ``known'' basenames to |«list»|. Files with those basenames
639 are selected regardless of their extension. If the extension is unknown, the
640 text viewer will be used to view the file.
641 \end{confitem}
642
643 \begin{confitem}{badbasename\_list}
644 {\meta{list}}[default: \code{readme, 00readme}]
645
646 Set the list of ``bad'' basenames to |«list»|. Files with those names get a
647 malus of |1| on their heuristic score if it was previously positive.
648 \end{confitem}
649
650 \begin{confitem}{viewer\_\meta{ext}}{\meta{command}}
651 Set the viewer command for files with extension |«ext»| to |«command»|. For
652 files without an extension, |viewer_txt| is used. Note that there is no
653 |viewer_| variable. In |«command»|, |%s| can be used as a placeholder for the
654 filename, which is otherwise inserted at the end of the command. The command
655 can be an arbitrary shell construct.
656 \end{confitem}
657
658 \begin{confitem}{lang}{\meta{2-letter code}}
659 Set your preferred language. By default, it reflects your system's locale.
660 \end{confitem}
661
662 \begin{confitem}{verbosity\_level}{\meta{number}}[default: \code{2}]
663 Set the verbosity level to |«number»|. At level~|3|, errors, warnings and
664 informational messages will be printed on stderr; |2| means only errors and
665 warnings, |1| only errors and |0| nothing except internal errors (obviously not
666 recommended).
667 \end{confitem}
668
669 \begin{confitem}{debug\_list}{\meta{list}}[default: empty]
670 Set the list of activated debug categories. Available debug categories are
671 |config|, |files|, |search|, |docfile|, |score|, |texdocs|, |tlpdb|, |version|,
672 |view|, and |all| to activate all of these. Implies |--verbose|. Debug
673 information are printed on standard error.
674 \end{confitem}
675
676 \begin{confitem}{max\_lines}{\meta{number}}[default: \code{10}]
677 Set the maximum number of results to be printed without confirmation in list,
678 mixed or showall mode. This setting has no effect if interaction is disabled.
679 \end{confitem}
680
681 \begin{confitem}{machine\_switch}{\choice{true, false}}[default: \code{false}]
682 Turn on or off machine-readable output. With this option active, the value of
683 |interact_switch| is forced to |false|, and each line of output is
684 %
685 \begin{htcode}
686 «argument»\metatab«score»\metatab«filename»
687 \end{htcode}
688 %
689 where |«argument»| is the name of the argument to which the results correspond
690 (mainly useful if there were many arguments), {\metatab} is the tab (ASCII \#9)
691 character, and the other entries are pretty self-explanatory. Nothing else is
692 printed on stdout, except if an internal error occurs (in which case exit code
693 will be |1|). In the future, more tab-separated fields may be added at the end
694 of the line, but the first 3 fields will remain unchanged.
695
696 Currently, there are two additional fields: a two-letter language code, and an
697 unstructured description, both taken from the CTAN catalogue (via the {\TL}
698 database). These fields may be empty, and they are not guaranteed to keep the
699 same meaning in future versions of Texdoc.
700 \end{confitem}
701
702 \begin{confitem}{zipext\_list}{\meta{list}}[default: empty]
703 List of supported extensions for zipped files. Allows compressed files with
704 names like |foobar.«zipext»|, where |«zipext»| is an element in the given
705 |«list»|, to be found and unzipped before the viewer is started (the temporary
706 file will be destroyed right after).
707
708 Warning: Support for zipped documentation is not meant to work on windows, a
709 Unix shell is assumed! If you add anything to this list, please make sure that
710 you also set the corresponding \ci{unzip\_\meta{zipext}} item for each
711 |«zipext»| in the list. At the same time, make sure you are using blocking
712 (i.e., not returning immediately) viewers.
713
714 Remark: {\TL} does not ship any compressed documentation file, so this option
715 is mainly useful with re-packaged versions of {\TL} that do, for example one in
716 Linux distributions.
717 \end{confitem}
718
719 \begin{confitem}{unzip\_\meta{zipext}}{\meta{command}}[no default]
720 The unzipping command for compressed files with extension |«zipext»|. You
721 should set one for each item in the \ci{zipext\_list}. The command must print
722 the result on stdout, like |gzip -d -c| does.
723 \end{confitem}
724
725 \begin{confitem}{rm\_file}{\meta{command}}[default: \code{rm -f}]
726 Commands for removing files on your system. Only useful for zipped documents
727 (see \ci{zipext\_list}).
728 \end{confitem}
729
730 \begin{confitem}{rm\_dir}{\meta{command}}[default: \code{rmdir}]
731 Commands for removing directories on your system. Also only useful for zipped
732 documents (see \ci{zipext\_list}).
733 \end{confitem}
734
735 \begin{confitem}{lastfile\_switch}{\choice{true, false}}[default: \code{false}]
736 If set to true, prevents Texdoc from reading any other configuration file after
737 this one (they will be reported as ``disabled'' by |texdoc -f|). Mainly useful
738 for installing a newer version of Texdoc in your home and preventing the
739 default configuration file from older versions to be used (see the
740 \href{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do
741 so).
742 \end{confitem}
743
744 \begin{confitem}{fuzzy\_level}{\meta{number}}[default: \code{3}]
745 Set the allowance of Levenshtein distance to |«number»| for fuzzy search. At
746 level~|0|, the fuzzy search feature is disabled.
747 \end{confitem}
748
749 \begin{confitem}{texlive\_tlpdb}{\meta{path}}[no default]
750 This enables you to specify the |«path»| for the database |texlive.tlpdb| which
751 Texdoc uses for searching documents. By default, Texdoc uses
752 \path{TEXMFROOT/tlpkg/texlive.tlpdb}. Usually, you don't have to (or should
753 not) set this configuration item. This is only useful when you want to use
754 Texdoc within a {\TL}-based {\TeX} distribution which does not ship
755 |texlive.tlpdb|.
756 \end{confitem}
757
758 \begin{confitem}{online\_url}{\meta{url}}
759 [default: \code{https://texdoc.org/serve/PKGNAME/0}]
760 Sets the \meta{url} to use for online documentation. Texdoc will replace
761 |PKGNAME| with the name of the package to search for.
762 \end{confitem}
763
764 \section{Shell Completion}
765 \label{sec:completion}
766
767 Shell completion can be used to receive assistance in entering command-line
768 options and arguments (typically package names) for the |texdoc| command.
769 Texdoc can provide shell completion functions via the \lopt{print-completion}
770 action. Configuring the appropriate per-shell setting described below can
771 enable this shell completion function.
772
773 %\subsection{Bash}
774
775 \subsection{Zsh}
776
777 To enable completion for zsh, you need to put
778 %
779 \begin{htcode}
780 autoload -Uz compinit && compinit
781 \end{htcode}
782 %
783 in your zsh configuration file (such as \code{\$HOME/.zshrc}). You can install
784 our completion function with either of the following two ways:
785 %
786 \begin{itemize}
787 \item adding \code{eval "\$(texdoc \lopt{print-completion} zsh)"} to your
788 zsh configuration file.
789
790 \item creating a file named \code{\_texdoc} in \code{\$fpath} whose content is
791 the output of \code{texdoc \lopt{print-completion} zsh}.
792 \end{itemize}
793
794 \section{Licence}
795 \label{sec:licence}
796
797 The current version of Texdoc program and its documentation are copyright
798 2008--2025 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} Team.
799
800 They are free software: you can redistribute it and/or modify it under the
801 terms of the GNU General Public License as published by the Free Software
802 Foundation, either version 3 of the License, or (at your option) any later
803 version.
804
805 This program is distributed in the hope that it will be useful, but
806 \emph{without any warranty}; without even the implied warranty of
807 \emph{merchantability} or \emph{fitness for a particular purpose}. See the
808 GNU General Public License for more details.
809
810 You should have received a copy of the GNU General Public License along with
811 this program. If not, see \url{http://www.gnu.org/licenses/}.
812
813 \bigskip
814
815 Previous work (Texdoc program) in the public domain:
816 %
817 \begin{itemize}
818 \item Contributions from Reinhard Kotucha (2008).
819 \item First texlua versions by Frank K\"uster (2007).
820 \item Original shell script version by Thomas Esser, David Aspinall, and Simon
821 Wilkinson.
822 \end{itemize}
823
824 \bigskip
825
826 \begin{center}
827 \Large\bfseries
828 Happy {\TeX}ing!
829 \end{center}
830
831 \end{document}
832 % vim: set ambiwidth=single spell: