summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/texdoc/texdoc.tex
blob: 3a6873891bc1720255e8343006d242fdd1fc9c12 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
% this is texdoc's user manual
% written by Manuel Pégourié-Gonnard in 2008
% licensed under the WTFPL version 2 

\documentclass[a4paper, oneside]{scrartcl}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{fixltx2e}
\usepackage{lmodern}

\usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}

\usepackage[rm, bf]{titlesec}
\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
\titleformat{\subsubsection}[runin]{\itshape}{%
  \makebox[0pt][r]{\thetitle\kern1pc}}{%
  0pt}{}[\maybedot\space --- ]

\usepackage{enumitem}
\newlength\lssep \setlength\lssep{\smallskipamount}
\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}

\usepackage[british]{babel}
\usepackage[babel=true, expansion=false]{microtype}
\usepackage[bookmarks=true]{hyperref}
\hypersetup{%
  bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
  pdftitle=texdoc: finding and viewing TeX documentation,
  pdfauthor=Manuel Pégourié-Gonnard,
  pdfsubject=texdoc's user manual,
  pdfkeywords={texdoc, TeX Live, manual}}

\newcommand\CTAN[1]{%
  \href{http://mirror.ctan.org/tex-archive/#1}{CTAN:#1}}
\newcommand\mailto[1]{%
  \href{mailto:#1}{#1}}
\newcommand\package[1]{%
  \href{http://ctan.org/pkg/#1}{#1}}
\newcommand\http[1]{%
  \href{http://#1}{#1}}

\newcommand\texlive{%
  \TeX{}\thinspace Live\xspace}

\setlength\parindent{\baselineskip}

\let\TeXori\TeX \def\TeX{\TeXori\xspace} % breaks the l2e logo
\lastlinefit=500 % e-TeX powered

\definecolor{links}{named}{violet}
\definecolor{special}{rgb}{0,0.5,0}
\definecolor{code}{rgb}{0,0,0.6}
\definecolor{input}{rgb}{1.0,0,0}
\newcommand\inputcolorname{red}
\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
\newcommand\textpa[1]{% % noms d'extensions (package)
  {\normalfont\color{special}\sffamily #1}}
\newcommand\cofont{% % code
  \color{code}\normalfont\ttfamily}
\newcommand\textco[1]{{\cofont#1}}
\newcommand\textme[1]{% % éléments meta
  {\normalfont\color{special}\itshape #1\/}}
\newcommand\epfont{% % épigraphes
  \normalcolor\usefont{T1}{pzc}{m}{it}}
\newcommand\textlmi[1]{% passage en lmodern italique pour voir
  {\usefont{T1}{lmr}{m}{it}#1}}
\newcommand\textcm[1]{% % passage en cm pour voir
  {\fontencoding{T1}\fontfamily{cmr}\selectfont#1}}
\newcommand\file{\nolinkurl}

% take care of nbsp
\catcode`\ 10\relax

\newcommand\meta[1]{% % variantes à remplacer
  {\color{special}\textlangle\textme{#1}\textrangle}}
\newcommand\commandline[1]{%
  \prompt\space \textcolor{input}{#1}}
\newcommand\prompt{\ding{229}}

\fvset{formatcom=\cofont, defineactive={\makeallfancy}}%
\newcommand\makefancyog{%
  \def«##1»{\meta{##1}}}
{\catcode32\active
\gdef\makefancythorn{%
\defþ ##1 þ{\commandline{##1}}}%
}
\newcommand\makefancypar{%
  \def¶##1¶{\textcolor{input}{##1}}}
\newcommand\makeallfancy{%
  \makefancyog\makefancythorn\makefancypar}

\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
          \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
      \else
        \unexpanded{\normalsize
          \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}

\newenvironment{htcode}{% % code en hors-texte
  \SaveVerbatim[samepage, gobble=2]{verbmat}%
  }{%
  \endSaveVerbatim
  \par\medskip\noindent\hspace*{\parindent}%
  \BUseVerbatim{verbmat}%
  \par\medskip}
\DefineShortVerb{\©}

\setkomafont{title}{}
\setkomafont{subtitle}{\Large}
\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}

\newcommand\texdoc{\textpa{texdoc}\xspace}

\title{\texdoc}
\subtitle{Finding \& viewing \TeX documentation}
\author{\href{mailto:mpg@elzevir.fr}{Manuel Pégourié-Gonnard}\thanks{%
    for the documentation.  The script itself was last updated and revised by
    Manuel Pégourié-Gonnard with contributions from Reinhard Kotucha, based on
    the previous texlua versions by Frank Küster.  Original (bash) shell
    script by Thomas Esser, David Aspinall, and Simon Wilkinson.  Please sent
    comments, bug reports, and feature requests to \mailto{texlive@tug.org}.}}
\date{v0.4---2008/08/01}

\begin{document}
\VerbatimFootnotes

\maketitle

\section{Basic Usage, Modes}\label{s-basics}

\begin{cmdsubsec}{Normal (view) mode}{ss-view}
  texdoc «name»
\end{cmdsubsec}

The simplest way to use \texdoc is just to type\footnote{In a command line.  If
  you don't know how to open one, look for Start$\to$Execute and type ©cmd© on
  Windows, or use the ``terminal'' icon on Mac OS X.  If you are using another
  flavour of Unix, you probably know what to do.} ©texdoc© followed by the
name of the package whose documentation you want to read.  It usually finds
the documentation for you and opens it in the appropriate reader.  That's it:
easy and usually fast.  The rest of this manual describes what to do if
this doesn't work exactly as you like and you want to customise things, and
how to do more extensive searchs.

Before the description of \texdoc's different modes, just a word words about
the typographic conventions in this manual.  Things like ©«name»© in the above
title mean that they should be replaced by what you actually want.  For
example, if you want to read \package{hyperref}'s manual, type
©texdoc hyperref©.  Sometimes there will be complete examples like this:

\begin{htcode}
  þ texdoc -s babelbib þ
  1 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/babelbib.pdf
  2 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/tugboat-babelbib.pdf
  3 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/ChangeLog
  4 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/README
  Please enter the number of the file to view, anything else to skip: ¶2¶
\end{htcode}

In this case, what you actually type is in \textcolor{input}{\inputcolorname},
and the funny symbol \textco{\prompt} represents your shell's prompt, which
can actually be something like ©C:\>© or ©name@host:~%© or funnier.

Now, let's talk about this ©-s© option you've just seen in the previous
example. 

\begin{cmdsubsec}{Search mode}{ss-search}
  texdoc -s «name» 
  texdoc --search «name»
\end{cmdsubsec}

With the two (equivalent) commands above, \texdoc also looks for documentation
for ©«name»©, but using the \emph{search mode}, which differs from the
normal mode (called \emph{view mode}) on two points:
\begin{itemize}
  \item It doesn't start a viewer and offers you a \emph{menu} instead.
  \item It always do a \emph{full search}.
\end{itemize}
The first point is rather straightforward on the example.  The second deserves
more explanation. 

Usually, \texdoc looks for files named ©«name».pdf© or ©«name».html© etc. (see
\ref{cf-ext_list}), where ©«name»© means what you asked for, in \texlive's
documentation directories, and if cannot find such a file, it tries a full
search: it finds all files which have ©«name»© in their name, or in the
directory's name.  In search mode, \texdoc always performs a full search.

Now look carefully at the previous example.  The purpose of search mode is to
allow you to find related documentation, such as the
\href{http://www.tug.org/TUGboat/}{TUGboat} article on \package{babelbib},
which you might want to read, whereas in normal mode \texdoc offers you no
choice and just displays the user manual ©babelbib.pdf©.  On the other hand,
the view mode is much faster when you know exactly what you want to read.

To try and make you happy, \texdoc offers three other modes, introduced below.

\begin{cmdsubsec}{List mode}{ss-list}
  texdoc -l «name»
  texdoc --list «name»
\end{cmdsubsec}

The \emph{list mode} uses a normal search, but forces \texdoc to give you a
menu instead of choosing itself the documentation to display.  It is usefull
when there are many files with the same name but different contents, or many
versions of the same file on your system. 

\begin{htcode}
  þ texdoc -l tex þ
  1 /usr/local/texlive/2008/texmf/doc/man/man1/tex.pdf
  2 /usr/local/texlive/2008/texmf-doc/doc/english/knuth/tex/tex.pdf
  Please enter the number of the file to view, anything else to skip: 
\end{htcode}

Here the first file is the manual page\footnote{converted in pdf.  To allow
  texdoc to find and display real man pages in man format,
  see~\ref{cf-ext_list}.} of the ©tex© command, while the second is \TeX{}'s
documented source code\dots

\begin{cmdsubsec}{Mixed mode}{ss-mixed}
  texdoc -m «name»
  texdoc --mixed «name»
\end{cmdsubsec}

As the name says, \emph{mixed mode} is an attempt to provide you the best of
the normal (view) and list modes, by mixing them in the following way:  If
only one file is found, the \texdoc opens it, and if many are found, it
displays a menu to let you choose.  You may want to make this mode the
default, see~\ref{cf-mode}.

\begin{cmdsubsec}{What's a <name>?}{ss-name}
  texdoc «name1» «name2» «...»
  texdoc «name.ext»
\end{cmdsubsec}

To conclude this section on basics, let us just mention two points concerning
the ©«name»© in all previous sections.  Is is usually a single name without
extension, but you can also use many names at once: then, depending on the
mode, \texdoc will either open all the corresponding documentation or show you
menus for each of the names you mentioned.  For each name, you can also
specifiy the file exention if you want, eg ©texdoc texlive-en.html© lets you
read the \texlive manual in html rather than in pdf format.

\bigskip

You can now stop reading this manual unless you have special needs.  If you
want to understand the curious ©aliased too© messages that you will sometimes
see, and control them, read section~\ref{s-alias}.  If you have problems
viewing certain type of files or want to choose you preferred reader, look at
section~\ref{s-viewer}.  Finally, section~\ref{s-ref} is the full
reference concerning \texdoc configuration: while you probably don't want to
read it all at once, you can consult~\ref{cf-mode} if you want to select your
preferred mode and make it the default.

Finally, be aware of the ©-h© or ©--help© option which provides you a quick
reminder of all available command-line options.

\section{Aliases, or name substitution}\label{s-alias}

\subsection{Basic concept}\label{ss-alias-basics}

The usual search modes of \texdoc assume that the name of the documentation
file is the name of the package, or contains it (at least in the directory
name).  However, this is not always true, due either to the author choosing a
fancy name, or packaging peculiarities.  To try helping the user to find the
doc even in these cases, \texdoc provides an alias mechanism and comes with a
list of circa 200 pre-defined aliases.

\begin{htcode}
  þ texdoc -l geometry þ
  texdoc info: geometry aliased to geometry/manual.pdf
  1 /usr/local/texlive/2008/texmf-dist/doc/latex/geometry/manual.pdf
  Please enter the number of the file to view, anything else to skip: ¶0¶
\end{htcode}

The concept of alias is very\footnote{See~\ref{ss-alias-rem} for why it is
  actually \emph{too} simple.} simple: as you can see of the above example,
when you type and ©geometry© is aliased to ©geometry/manual.pdf©, then
everything happens as if you actually typed ©texdoc geometry/manual.pdf©
(without any further alias substitution), and \texdoc informs you that
something happened so you can understand the results (see~\ref{cf-noise_level}
to get rid of this message):

\begin{cmdsubsec}{Command line options}{ss-alias-cl}
  texdoc -a «options» «name»
  texdoc --alias «options» «name»
  texdoc -A «options» «name»
  texdoc --noalias «options» «name»
\end{cmdsubsec}

By default, aliased are used in view, list and mixed modes, and disabled in
search mode. But you may want to disable it, because the default alias doesn't
do what you want\footnote{In this case, please report it to
  \mailto{texlive@tug.org}.} or for another reason.  In this case, you just
have to add ©-A© or ©--noalias© to the options, like:

\begin{htcode}
  þ texdoc -A -l geometry þ
  1 /usr/local/texlive/2008/texmf-doc/doc/polish/tex-virtual-academy-pl/
  latex2e/macro/geometry.html
  Please enter the number of the file to view, anything else to skip: ¶0¶
\end{htcode}

On the contrary, you can force aliasing in search mode by using the ©-a© or
©--alias© option, though it may not prove very useful.

\subsection{Your own aliases}\label{ss-alias-own}

You can define your own aliases, or override the default ones, in \texdoc's
configuration files. You can get a list of those files by typing ©texdoc -f©.
For personal aliases, it is recommended that you use the second file, marked
by a star (see~\ref{ss-prec} for details). You'll probably need to
create in and one or two of the directories containing it.

Creating an alias is easy: you just insert a line like 
\begin{htcode}
  alias geometry = geometry/manual.pdf
\end{htcode}
in your configuration file, and it's all.  You can have a look at the
configuration file provided (the last one showed by ©texdoc -f©) for examples.
If you want to permanently unalias something, just insert a line
©«name»=«name»©: it will overwrite the previous alias.

\subsection{Remarks on aliases}\label{ss-alias-rem}

Please be aware that this alias feature, or at least its intensive use to try
to find the ``right'' documentation for a given package, should be temporary.
Indeed, one problem is that currently aliases do \emph{hide} other files, while
it is desirable that they just \emph{add} results in some case. However,
defining a coherent behaviour (and how to maintain the needed database)
requires work and time, and is therefore reported to future versions.

In this vein, it would be desirable to have a notion of ``category'', like
user documentation of a package, or man page of a program, or reference manual
of a program, or documented source code of a package or program, or\dots If
you have ideas about desirable categories and ways they should be handled,
feel free to share them at the usual address.

\section{Viewer selection}\label{s-viewer}

A list of default viewers is defined in \texdoc, depending on your platform
(Windows, MacOS X, other Unix). On Windows and MacOS, it uses your file
associations like when you double-click files in the Explorer or the Finder.
On Unix, it tries to find a viewer in the path from a list of ``known'
viewers.

If you want to use another viewer, you have two ways of telling this to
\texdoc: in your configuration file or using environment variables.  If you
hesitate, the configuration file is the recommended way.

To find you configuration file, type ©texdoc -f© and pick the file mark with a
star (unless you are a system administrator or your home is shred between many
machines, see~\ref{ss-prec}); you may need to create the file and a few
directories. Then you can add lines like:

\begin{htcode}
  viewer_pdf = (xpdf %s) &
  viewer_txt = less
\end{htcode}

Here the ©%s© stands for the name of the file to view. The first line sets
©xpdf© as the pdf viewer, and use a bit of shell syntax to force it to run in
the background (the ©()© are here for compatibility with zip support,
see~\ref{s-bugs}). The second line sets ©less© as the text viewer: it doesn't
use ©%s©, which means the filename will be placed at the end of the command.

The default extensions allowed are ©pdf©, ©html©, ©txt©, ©dvi©, ©ps©, and no
extension.  The ©txt© viewer is used for files without extension.
See~\ref{cf-ext_list} for how to allow for more extensions.

The corresponding environment variables are ©PDFVIEWER©, ©BROWSER©, ©PAGER©,
©DVIVIEWER©, ©PSVIEWER©. They follow the same convention as values from the
configuration files, and override them if they are set. Since some of those
variable are shared by other programs, you can override them by adding
©_texdoc© at the end, like in ©BROWSER_texdoc©.

\section{Full reference}\label{s-ref}

The most useful command-line options, configuration values and all
environment variables have been presented.  Here we complete our presentation
and review all in a systematic way.

\subsection{Precedence}\label{ss-prec}

Values for a particular setting can come from several sources. They are treated
in the following order, where 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, read in the following order:
    \begin{enumerate}
      \item ©$TEXMFHOME/texdoc/texdoc-«platform».cnf©
      \item ©$TEXMFHOME/texdoc/texdoc.cnf©
      \item ©$TEXMFLOCAL/texdoc/texdoc-«platform».cnf©
      \item ©$TEXMFLOCAL/texdoc/texdoc.cnf©
      \item ©$TEXMFMAIN/texdoc/texdoc.cnf© %stopzone
    \end{enumerate}
  \item Hard-coded defaults that may depend on the current platform or the
    current value of another setting.
\end{enumerate}

For the configuration files, ©«platform»© stand for the name of the current
platform, with names matching those of the directories in ©TEXLIVEROOT/bin©,
and ©TEXMFHOME© and others are the kpse's values, see the kpathsea and web2c
manuals. The name with ©«platform»© can be used on installation shared between
many machines where, for example, not the same viewers are available. However,
their use is not recommended in other situations.

\subsection{Command-line options}\label{ss-cl}

Most of the command-line options correspond to an option that can be set from
the config files. For them, we refer the reader to the description of the
corresponding configuration option. 

\begin{cmdsubsub}{-h, --help}{cl-h}
  -h, --help
\end{cmdsubsub}

Shows a quick help message (namely a list of command-line options) and exits
successfully.

\begin{cmdsubsub}{-v, --version}{cl-v}
  -v, --version
\end{cmdsubsub}

Show the current version of the program and exits successfully.

\begin{cmdsubsub}{-f, --files}{cl-f}
  -f, --files
\end{cmdsubsub}

Shows the list of the configuration files for the current installation and
platform, with their status (active or not found) and a star marking the
recommended file for user settings.

\begin{cmdsubsub}{-w, -l, -m, -s, -r, --view, --list, --mixed, --search,
    --regex}{cl-mode}
  -w, --view, -l, --list, -m, --mixed, -s, --search, -r, --regex
\end{cmdsubsub}

\leavevmode\par\noindent See \ref{cf-mode}.

\begin{cmdsubsub}{-a, -A, --alias, --noalias}{cl-a}
  -a, --alias, -A, --noalias
\end{cmdsubsub}

See~\ref{s-alias}.

\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
  -i, --interact, -I, --nointeract
\end{cmdsubsub}

See~\ref{cf-interact}.

\begin{cmdsubsub}{-e, --extensions}{cl-e}
  -e=«l», --extensions=«l»
\end{cmdsubsub}

See~\ref{cf-ext_list}.  \emph{But} be aware that on the command line there
should be no space at all, neither in the list (unless quoted according to you
shell's convention) not between the ©-e© or ©--extension© option, the equal
sign, and the list.  Also take care to quote the special value ©*© if
necessary.  The equal sign is optional.

\begin{cmdsubsub}{-n, --noise-level}{cl-n}
  -n=«n», --noise-level=«n»
\end{cmdsubsub}

See~\ref{cf-noise_level} and be aware that you must avoid spaces on the command
line, and the ©=© sign is optional.

\subsection{Environment variables}\label{ss-envvar}

They all correspond to some ©viewer_«ext»© setting, and the reader is referred
to~\ref{s-viewer} and~\ref{cf-viewer_*} for details. Here is the (obvious)
correspondence:

\begin{center}
\begin{tabular}{lll}
  ©PAGER_texdoc©        & ©PAGER©       & ©viewer_html© \\
  ©BROWSER_texdoc©      & ©BROWSER©     & ©viewer_txt©  \\
  ©DVIVIEWER_texdoc©    & ©DVIVIEWER©   & ©viewer_dvi©  \\
  ©PSVIEWER_texdoc©     & ©PSVIEWER©    & ©viewer_ps©   \\
  ©PDFVIEWER_texdoc©    & ©PDFVIEWER©   & ©viewer_pdf©  \\
\end{tabular}
\end{center}

\subsection{Configuration files}\label{ss-conf}

\subsubsection{General structure}\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}
  «config_param» = «value»
  alias «name» = «target»
\end{htcode}

where ©«config_parameter»© consists of only letters, digits or ©-© signs,
©«name»© of letters, digits, ©-© and ©_© signs. ©«value»© and ©«target»© are
free strings (except that not every ©«value»© is valid for every
©«config_param»©, see below) and nothing in it need not be quoted (actually,
quotes will be interpreted as part of the value, not as quotation marks).

Lines which do not obey these rules raise a warning. However, unrecognised
values of ©«config_param»© raise no warning at the moment.

The ©«value»© is usually interpreted as a string, except when ©«config_param»©
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©
    (case-sensitive).
  \item ©_level©, then ©«value»© is a non-negative integer.
\end{enumerate}

\begin{cmdsubsub}{mode}{cf-mode}
  mode = «view, list, mixed, search, regex»
\end{cmdsubsub}
Set the  mode to the given value.  Default is ©view©.  The first three values
©view©, ©list©, ©mixed© use the same searching method: first search a file
whose name is the ©«name»© on the command line and whose extension is in
©ext_list© (see~\ref{cf-ext_list}), and if nothing is found, then do a full
search.  This means that a file matches if ©«name»© is a substring of its
path+name (and its extension is in the list). Here path does not mean the full
path, but only the part below ©TEXMF/doc©. The ©search© mode forces a full
search.

The last mode, ©regex©, looks for ©«name»© in the path+filename as a Lua
regex.  If you don't know Lua regexes you should be aware that the escape
character is ©%© and the ©-© sign is a special character (which means the same
as ©*?© in Perl regexes).  For more details, see the Lua
\href{http://www.lua.org/manual/}{reference manual} or the book
\href{http://www.lua.org/pil/}{\emph{programming in Lua}}.  You might want to
use\footnote{The quotes in the example are just to make the shell happy.}
©-e='*'© if your regex uses the ©$© anchor.%stopzone

\begin{cmdsubsub}{interact}{cf-interact}
  interact_switch = «true, false»
\end{cmdsubsub}

Turn on or of interaction.  Default is on.  Turning interaction off prevents
\texdoc to ask you to choose a file to view when there are multiple choices,
and merely just print the list of files found.

\begin{cmdsubsub}{ext_list}{cf-ext_list}
  ext_list = «list»
\end{cmdsubsub}

Set the list of recognised extensions to ©«list»©.  Default is
\begin{htcode}
  pdf, html, txt, dvi, ps,
\end{htcode}
This list is used to filter and  sort the results (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}

The value of ©ext_list© is overridden on a file per file basis if the given
argument already has an extension: the ©ext_list© is temporarily set to this
extension just for this argument.

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 = 1, 5, pdf, html, txt, dvi, ps,
  viewer_1 = man
  viewer_5 = man
\end{htcode}
(This also makes man pages in man format take precedence over their pdf
versions.)

\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 not ©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
shell construct. 

\begin{cmdsubsub}{alias}{cf-alias}
  alias «name» = «othername»
\end{cmdsubsub}

Everything has already been said in section~\ref{s-alias}.

\begin{cmdsubsub}{noise_level}{cf-noise_level}
  noise_level = «n»
\end{cmdsubsub}

Set the verbosity level to ©«n»©.  This determines whether \texdoc will print
or not errors or debug information (to stderr). Default level is 3. The
numeric codes are as follow:
\begin{enumerate}[start=0]
  \item Print nothing (not recommended).
  \item Print only error messages.
  \item Also print warnings.
  \item Also print information messages.
  \item Also print debug1 information messages.
\end{enumerate}

Currently, the levels 5 and greater are not used, and the only ``debug''
information at level 4 is to print the command used to view a file just before
executing it.

\subsection{Exit codes}\label{ss-exit}

The current exit code are as follow:
\begin{enumerate}[start=0]
  \item Success.
  \item Syntax error.
  \item Documentation not found for at least one argument.
\end{enumerate}

\section{Bugs, warnings}\label{s-bugs}

There is currently no known bug (fingers crossed).  But a few things you should
be warned about.

First of all, \texdoc doesn't always succeed in finding documentation.  Even
with the quite large alias database shipped, it only find documentation for
about 60\% of the name of the packages in \texlive (regardless of the
relevance of the results).  Moreover, it cannot handle very correctly packages
with many relevant documentation files at the moment (see~\ref{ss-alias-rem}).
Ideas about how to improve this are most welcome at the usual address.

Second, support for zipped documentation, which have been ``available'' in
previous versions of \texdoc, is now disabled by default. The reasons are that
this support wasn't portable (didn't work on windows for example), and
moreover we won't ship compressed documentation in \texlive.  However, the
code has not been totally removed and should be easy to activate again. If you
want to use this feature, please:
\begin{enumerate}
  \item Look in \texdoc's code for instructions.
  \item Be aware that the corresponding part of the code has not been well
    tested, and that you are responsible of the unzipping command anyway.
  \item Inform us either at the usual address or \mailto{tldistro@tug.org} if
    you are a Linux, BSD, or whatever, distributor.
\end{enumerate}

Finally, \texdoc is also missing a GUI version (texdoctk has never been the
GUI version of \texdoc, and is unmaintained and probably unmaintainable
anyway).  This is on the list, but the time line is rather unclear at the
moment.

\bigskip
\begin{center}\Large
  Happy \TeX{}ing!
\end{center}

\end{document}