1
% this is texdoc's user manual
2
% written by Manuel P�gouri�-Gonnard in 2008
3
% licensed under the WTFPL version 2
5
\documentclass[a4paper, oneside]{scrartcl}
6
\usepackage[latin1]{inputenc}
7
\usepackage[T1]{fontenc}
12
\usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}
14
\usepackage[rm, bf]{titlesec}
15
\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
16
\titleformat{\subsubsection}[runin]{\itshape}{%
17
\makebox[0pt][r]{\thetitle\kern1pc}}{%
18
0pt}{}[\maybedot\space --- ]
21
\newlength\lssep \setlength\lssep{\smallskipamount}
22
\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}
24
\usepackage[british]{babel}
25
\usepackage[babel=true, expansion=false]{microtype}
26
\usepackage[bookmarks=true]{hyperref}
28
bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
29
pdftitle=texdoc: finding and viewing TeX documentation,
30
pdfauthor=Manuel P�gouri�-Gonnard,
31
pdfsubject=texdoc's user manual,
32
pdfkeywords={texdoc, TeX Live, manual}}
35
\href{http://mirror.ctan.org/tex-archive/#1}{CTAN:#1}}
36
\newcommand\mailto[1]{%
38
\newcommand\package[1]{%
39
\href{http://ctan.org/pkg/#1}{#1}}
44
\TeX{}\thinspace Live\xspace}
46
\setlength\parindent{\baselineskip}
48
\let\TeXori\TeX \def\TeX{\TeXori\xspace} % breaks the l2e logo
49
\lastlinefit=500 % e-TeX powered
51
\definecolor{links}{named}{violet}
52
\definecolor{special}{rgb}{0,0.5,0}
53
\definecolor{code}{rgb}{0,0,0.6}
54
\definecolor{input}{rgb}{1.0,0,0}
55
\newcommand\inputcolorname{red}
56
\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
57
\newcommand\textpa[1]{% % noms d'extensions (package)
58
{\normalfont\color{special}\sffamily #1}}
59
\newcommand\cofont{% % code
60
\color{code}\normalfont\ttfamily}
61
\newcommand\textco[1]{{\cofont#1}}
62
\newcommand\textme[1]{% % �l�ments meta
63
{\normalfont\color{special}\itshape #1\/}}
64
\newcommand\epfont{% % �pigraphes
65
\normalcolor\usefont{T1}{pzc}{m}{it}}
66
\newcommand\textlmi[1]{% passage en lmodern italique pour voir
67
{\usefont{T1}{lmr}{m}{it}#1}}
68
\newcommand\textcm[1]{% % passage en cm pour voir
69
{\fontencoding{T1}\fontfamily{cmr}\selectfont#1}}
70
\newcommand\file{\nolinkurl}
75
\newcommand\meta[1]{% % variantes � remplacer
76
{\color{special}\textlangle\textme{#1}\textrangle}}
77
\newcommand\commandline[1]{%
78
\prompt\space \textcolor{input}{#1}}
79
\newcommand\prompt{\ding{229}}
81
\fvset{formatcom=\cofont, defineactive={\makeallfancy}}%
82
\newcommand\makefancyog{%
83
\def�##1�{\meta{##1}}}
85
\gdef\makefancythorn{%
86
\def� ##1 �{\commandline{##1}}}%
88
\newcommand\makefancypar{%
89
\def�##1�{\textcolor{input}{##1}}}
90
\newcommand\makeallfancy{%
91
\makefancyog\makefancythorn\makefancypar}
95
\setlength\dec{\heightof{\cofont{texdoc \meta{name}}}}
98
\newenvironment{commandes}[3]{%
99
\def\thecmd{\noexpand#1}%
102
\SaveVerbatim[samepage, gobble=2]{verbmat}%
105
\xdef\sectioncmd{\noexpand\nodotthistime
108
\unexpanded{\normalsize
109
\fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
111
\unexpanded{\normalsize
112
\BUseVerbatim{verbmat}}%
114
\noexpand\label{\thelabel}}}%
115
\aftergroup\sectioncmd}
118
\newcommand\maybedot{.}
119
\newcommand\nodotthistime{%
120
\renewcommand\maybedot{%
121
\global\def\maybedot{.}}}
123
\newenvironment{cmdsubsec}[2]{%
124
\framedtrue \commandes\subsection{#1}{#2}%
128
\newenvironment{cmdsubsub}[2]{%
129
\framedfalse \commandes\subsubsection{#1}{#2}%
133
\newenvironment{htcode}{% % code en hors-texte
134
\SaveVerbatim[samepage, gobble=2]{verbmat}%
137
\par\medskip\noindent\hspace*{\parindent}%
138
\BUseVerbatim{verbmat}%
142
\setkomafont{title}{}
143
\setkomafont{subtitle}{\Large}
144
\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
146
\newcommand\texdoc{\textpa{texdoc}\xspace}
149
\subtitle{Finding \& viewing \TeX documentation
151
\author{\url{http://tug.org/texdoc/}\\
152
Manuel P�gouri�-Gonnard\thanks{%
153
for the documentation. The script itself was last updated and revised by
154
Manuel P�gouri�-Gonnard with contributions from Reinhard Kotucha, based on
155
the previous texlua versions by Frank K�ster. Original (bash) shell
156
script by Thomas Esser, David Aspinall, and Simon Wilkinson.}
158
\date{v0.4---2008/08/01}
165
\section{Basic Usage, Modes}\label{s-basics}
167
\begin{cmdsubsec}{Normal (view) mode}{ss-view}
171
The simplest way to use \texdoc is just to type\footnote{In a command line. If
172
you don't know how to open one, look for Start$\to$Execute and type �cmd� on
173
Windows, or use the ``terminal'' icon on Mac OS X. If you are using another
174
flavour of Unix, you probably know what to do.} �texdoc� followed by the
175
name of the package whose documentation you want to read. It usually finds
176
the documentation for you and opens it in the appropriate reader. That's it:
177
easy and usually fast. The rest of this manual describes what to do if
178
this doesn't work exactly as you like and you want to customise things, and
179
how to do more extensive searchs.
181
Before the description of \texdoc's different modes, just a word words about
182
the typographic conventions in this manual. Things like ��name�� in the above
183
title mean that they should be replaced by what you actually want. For
184
example, if you want to read \package{hyperref}'s manual, type
185
�texdoc�hyperref�. Sometimes there will be complete examples like this:
188
� texdoc -s babelbib �
189
1 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/babelbib.pdf
190
2 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/tugboat-babelbib.pdf
191
3 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/ChangeLog
192
4 /usr/local/texlive/2008/texmf-dist/doc/latex/babelbib/README
193
Please enter the number of the file to view, anything else to skip: �2�
196
In this case, what you actually type is in \textcolor{input}{\inputcolorname},
197
and the funny symbol \textco{\prompt} represents your shell's prompt, which
198
can actually be something like �C:\>� or �name@host:~%� or funnier.
200
Now, let's talk about this �-s� option you've just seen in the previous
203
\begin{cmdsubsec}{Search mode}{ss-search}
205
texdoc --search �name�
208
With the two (equivalent) commands above, \texdoc also looks for documentation
209
for ��name��, but using the \emph{search mode}, which differs from the
210
normal mode (called \emph{view mode}) on two points:
212
\item It doesn't start a viewer and offers you a \emph{menu} instead.
213
\item It always do a \emph{full search}.
215
The first point is rather straightforward on the example. The second deserves
218
Usually, \texdoc looks for files named ��name�.pdf� or ��name�.html� etc. (see
219
\ref{cf-ext_list}), where ��name�� means what you asked for, in \texlive's
220
documentation directories, and if cannot find such a file, it tries a full
221
search: it finds all files which have ��name�� in their name, or in the
222
directory's name. In search mode, \texdoc always performs a full search.
224
Now look carefully at the previous example. The purpose of search mode is to
225
allow you to find related documentation, such as the
226
\href{http://www.tug.org/TUGboat/}{TUGboat} article on \package{babelbib},
227
which you might want to read, whereas in normal mode \texdoc offers you no
228
choice and just displays the user manual �babelbib.pdf�. On the other hand,
229
the view mode is much faster when you know exactly what you want to read.
231
To try and make you happy, \texdoc offers three other modes, introduced below.
233
\begin{cmdsubsec}{List mode}{ss-list}
238
The \emph{list mode} uses a normal search, but forces \texdoc to give you a
239
menu instead of choosing itself the documentation to display. It is usefull
240
when there are many files with the same name but different contents, or many
241
versions of the same file on your system.
245
1 /usr/local/texlive/2008/texmf/doc/man/man1/tex.pdf
246
2 /usr/local/texlive/2008/texmf-doc/doc/english/knuth/tex/tex.pdf
247
Please enter the number of the file to view, anything else to skip:
250
Here the first file is the manual page\footnote{converted in pdf. To allow
251
texdoc to find and display real man pages in man format,
252
see~\ref{cf-ext_list}.} of the �tex� command, while the second is \TeX{}'s
253
documented source code\dots
255
\begin{cmdsubsec}{Mixed mode}{ss-mixed}
257
texdoc --mixed �name�
260
As the name says, \emph{mixed mode} is an attempt to provide you the best of
261
the normal (view) and list modes, by mixing them in the following way: If
262
only one file is found, the \texdoc opens it, and if many are found, it
263
displays a menu to let you choose. You may want to make this mode the
264
default, see~\ref{cf-mode}.
266
\begin{cmdsubsec}{What's a <name>?}{ss-name}
267
texdoc �name1� �name2� �...�
271
To conclude this section on basics, let us just mention two points concerning
272
the ��name�� in all previous sections. Is is usually a single name without
273
extension, but you can also use many names at once: then, depending on the
274
mode, \texdoc will either open all the corresponding documentation or show you
275
menus for each of the names you mentioned. For each name, you can also
276
specifiy the file exention\footnote{It should be an allowed extension,
277
see~\ref{cf-ext_list}, and preferably have a associated viewer defined,
278
see~\ref{cf-viewer_*}.} if you want, eg �texdoc texlive-en.html� lets you
279
read the \texlive manual in html rather than in pdf format.
283
You can now stop reading this manual unless you have special needs. If you
284
want to understand the curious �aliased too� messages that you will sometimes
285
see, and control them, read section~\ref{s-alias}. If you have problems
286
viewing certain type of files or want to choose you preferred reader, look at
287
section~\ref{s-viewer}. Finally, section~\ref{s-ref} is the full
288
reference concerning \texdoc configuration: while you probably don't want to
289
read it all at once, you can consult~\ref{cf-mode} if you want to select your
290
preferred mode and make it the default.
292
Finally, be aware of the �-h� or �--help� option which provides you a quick
293
reminder of all available command-line options.
295
\section{Aliases, or name substitution}\label{s-alias}
297
\subsection{Basic concept}\label{ss-alias-basics}
299
The usual search modes of \texdoc assume that the name of the documentation
300
file is the name of the package, or contains it (at least in the directory
301
name). However, this is not always true, due either to the author choosing a
302
fancy name, or packaging peculiarities. To try helping the user to find the
303
doc even in these cases, \texdoc provides an alias mechanism and comes with a
304
list of circa 200 pre-defined aliases.
307
� texdoc -l geometry �
308
texdoc info: geometry aliased to geometry/manual.pdf
309
1 /usr/local/texlive/2008/texmf-dist/doc/latex/geometry/manual.pdf
310
Please enter the number of the file to view, anything else to skip: �0�
313
The concept of alias is very\footnote{See~\ref{ss-alias-rem} for why it is
314
actually \emph{too} simple.} simple: as you can see of the above example,
315
when you type and �geometry� is aliased to �geometry/manual.pdf�, then
316
everything happens as if you actually typed �texdoc�geometry/manual.pdf�
317
(without any further alias substitution), and \texdoc informs you that
318
something happened so you can understand the results (see~\ref{cf-noise_level}
319
to get rid of this message):
321
\begin{cmdsubsec}{Command line options}{ss-alias-cl}
322
texdoc -a �options� �name�
323
texdoc --alias �options� �name�
324
texdoc -A �options� �name�
325
texdoc --noalias �options� �name�
328
By default, aliased are used in view, list and mixed modes, and disabled in
329
search mode. But you may want to disable it, because the default alias doesn't
330
do what you want\footnote{In this case, please report it to
331
\mailto{texlive@tug.org}.} or for another reason. In this case, you just
332
have to add �-A� or �--noalias� to the options, like:
335
� texdoc -A -l geometry �
336
1 /usr/local/texlive/2008/texmf-doc/doc/polish/tex-virtual-academy-pl/
337
latex2e/macro/geometry.html
338
Please enter the number of the file to view, anything else to skip: �0�
341
On the contrary, you can force aliasing in search mode by using the �-a� or
342
�--alias� option, though it may not prove very useful.
344
\subsection{Your own aliases}\label{ss-alias-own}
346
You can define your own aliases, or override the default ones, in \texdoc's
347
configuration files. You can get a list of those files by typing �texdoc�-f�.
348
For personal aliases, it is recommended that you use the second file, marked
349
by a star (see~\ref{ss-prec} for details). You'll probably need to
350
create in and one or two of the directories containing it.
352
Creating an alias is easy: you just insert a line like
354
alias geometry = geometry/manual.pdf
356
in your configuration file, and it's all. You can have a look at the
357
configuration file provided (the last one showed by �texdoc�-f�) for examples.
358
If you want to permanently unalias something, just insert a line
359
��name�=�name��: it will overwrite the previous alias.
361
\subsection{Remarks on aliases}\label{ss-alias-rem}
363
Please be aware that this alias feature, or at least its intensive use to try
364
to find the ``right'' documentation for a given package, should be temporary.
365
Indeed, one problem is that currently aliases do \emph{hide} other files, while
366
it is desirable that they just \emph{add} results in some case. However,
367
defining a coherent behaviour (and how to maintain the needed database)
368
requires work and time, and is therefore reported to future versions.
370
In this vein, it would be desirable to have a notion of ``category'', like
371
user documentation of a package, or man page of a program, or reference manual
372
of a program, or documented source code of a package or program, or\dots If
373
you have ideas about desirable categories and ways they should be handled,
374
feel free to share them at the usual address.
376
\section{Viewer selection}\label{s-viewer}
378
A list of default viewers is defined in \texdoc, depending on your platform
379
(Windows, MacOS X, other Unix). On Windows and MacOS, it uses your file
380
associations like when you double-click files in the Explorer or the Finder.
381
On Unix, it tries to find a viewer in the path from a list of ``known'
384
If you want to use another viewer, you have two ways of telling this to
385
\texdoc: in your configuration file or using environment variables. If you
386
hesitate, the configuration file is the recommended way.
388
To find you configuration file, type �texdoc�-f� and pick the file mark with a
389
star (unless you are a system administrator or your home is shred between many
390
machines, see~\ref{ss-prec}); you may need to create the file and a few
391
directories. Then you can add lines like:
394
viewer_pdf = (xpdf %s) &
398
Here the �%s� stands for the name of the file to view. The first line sets
399
�xpdf� as the pdf viewer, and use a bit of shell syntax to force it to run in
400
the background (the �()� are here for compatibility with zip support,
401
see~\ref{s-bugs}). The second line sets �less� as the text viewer: it doesn't
402
use �%s�, which means the filename will be placed at the end of the command.
404
The default extensions allowed are �pdf�, �html�, �txt�, �dvi�, �ps�, and no
405
extension. The �txt� viewer is used for files without extension.
406
See~\ref{cf-ext_list} for how to allow for more extensions.
408
The corresponding environment variables are �PDFVIEWER�, �BROWSER�, �PAGER�,
409
�DVIVIEWER�, �PSVIEWER�. They follow the same convention as values from the
410
configuration files, and override them if they are set. Since some of those
411
variable are shared by other programs, you can override them by adding
412
�_texdoc� at the end, like in �BROWSER_texdoc�.
414
\section{Full reference}\label{s-ref}
416
The most useful command-line options, configuration values and all
417
environment variables have been presented. Here we complete our presentation
418
and review all in a systematic way.
420
\subsection{Precedence}\label{ss-prec}
422
Values for a particular setting can come from several sources. They are treated
423
in the following order, where first value found is always used:
425
\item Command-line options.
426
\item Environment variables ending with �_texdoc�.
427
\item Other environment variables.
428
\item Values from configuration files, read in the following order:
430
\item �$TEXMFHOME/texdoc/texdoc-�platform�.cnf�
431
\item �$TEXMFHOME/texdoc/texdoc.cnf�
432
\item �$TEXMFLOCAL/texdoc/texdoc-�platform�.cnf�
433
\item �$TEXMFLOCAL/texdoc/texdoc.cnf�
434
\item �$TEXMFMAIN/texdoc/texdoc.cnf� %stopzone
436
\item Hard-coded defaults that may depend on the current platform or the
437
current value of another setting.
440
For the configuration files, ��platform�� stand for the name of the current
441
platform, with names matching those of the directories in �TEXLIVEROOT/bin�,
442
and �TEXMFHOME� and others are the kpse's values, see the kpathsea and web2c
443
manuals. The name with ��platform�� can be used on installation shared between
444
many machines where, for example, not the same viewers are available. However,
445
their use is not recommended in other situations.
447
\subsection{Command-line options}\label{ss-cl}
449
Most of the command-line options correspond to an option that can be set from
450
the config files. For them, we refer the reader to the description of the
451
corresponding configuration option.
453
\begin{cmdsubsub}{-h, --help}{cl-h}
457
Shows a quick help message (namely a list of command-line options) and exits
460
\begin{cmdsubsub}{-v, --version}{cl-v}
464
Show the current version of the program and exits successfully.
466
\begin{cmdsubsub}{-f, --files}{cl-f}
470
Shows the list of the configuration files for the current installation and
471
platform, with their status (active or not found) and a star marking the
472
recommended file for user settings.
474
\begin{cmdsubsub}{-w, -l, -m, -s, -r, --view, --list, --mixed, --search,
476
-w, --view, -l, --list, -m, --mixed, -s, --search, -r, --regex
479
\leavevmode\par\noindent See \ref{cf-mode}.
481
\begin{cmdsubsub}{-a, -A, --alias, --noalias}{cl-a}
482
-a, --alias, -A, --noalias
487
\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
488
-i, --interact, -I, --nointeract
491
See~\ref{cf-interact}.
493
\begin{cmdsubsub}{-e, --extensions}{cl-e}
494
-e=�l�, --extensions=�l�
497
See~\ref{cf-ext_list}. \emph{But} be aware that on the command line there
498
should be no space at all, neither in the list (unless quoted according to you
499
shell's convention) not between the �-e� or �--extension� option, the equal
500
sign, and the list. Also take care to quote the special value �*� if
501
necessary. The equal sign is optional.
503
\begin{cmdsubsub}{-n, --noise-level}{cl-n}
504
-n=�n�, --noise-level=�n�
507
See~\ref{cf-noise_level} and be aware that you must avoid spaces on the command
508
line, and the �=� sign is optional.
510
\subsection{Environment variables}\label{ss-envvar}
512
They all correspond to some �viewer_�ext�� setting, and the reader is referred
513
to~\ref{s-viewer} and~\ref{cf-viewer_*} for details. Here is the (obvious)
518
�PAGER_texdoc� & �PAGER� & �viewer_html� \\
519
�BROWSER_texdoc� & �BROWSER� & �viewer_txt� \\
520
�DVIVIEWER_texdoc� & �DVIVIEWER� & �viewer_dvi� \\
521
�PSVIEWER_texdoc� & �PSVIEWER� & �viewer_ps� \\
522
�PDFVIEWER_texdoc� & �PDFVIEWER� & �viewer_pdf� \\
526
\subsection{Configuration files}\label{ss-conf}
528
\subsubsection{General structure}\label{sss-sonf-struct}
530
Configuration files are line-oriented text files. Comments begin with a �#�
531
and run to the end of line. Lines containing only space are ignored. Space at
532
the beginning or end of a line, as well as around an �=� sign, is ignored.
533
Apart from comments and empty lines, each line must be of one of the following
537
�config_param� = �value�
538
alias �name� = �target�
541
where ��config_parameter�� consists of only letters, digits or �-� signs,
542
��name�� of letters, digits, �-� and �_� signs. ��value�� and ��target�� are
543
free strings (except that not every ��value�� is valid for every
544
��config_param��, see below) and nothing in it need not be quoted (actually,
545
quotes will be interpreted as part of the value, not as quotation marks).
547
Lines which do not obey these rules raise a warning. However, unrecognised
548
values of ��config_param�� raise no warning at the moment.
550
The ��value�� is usually interpreted as a string, except when ��config_param��
553
\item �_list�, then ��value�� is a coma-separated list of strings. Space
554
around commas is ignored. Two consecutive comas or a coma at the beginning
555
or end of the list means the empty string at the corresponding place.
556
\item �_switch�, then ��value�� must be either �true� or �false�
558
\item �_level�, then ��value�� is a non-negative integer.
561
\begin{cmdsubsub}{mode}{cf-mode}
562
mode = �view, list, mixed, search, regex�
564
Set the mode to the given value. Default is �view�. The first three values
565
�view�, �list�, �mixed� use the same searching method: first search a file
566
whose name is the ��name�� on the command line and whose extension is in
567
�ext_list� (see~\ref{cf-ext_list}), and if nothing is found, then do a full
568
search. This means that a file matches if ��name�� is a substring of its
569
path+name (and its extension is in the list). Here path does not mean the full
570
path, but only the part below �TEXMF/doc�. The �search� mode forces a full
573
The last mode, �regex�, looks for ��name�� in the path+filename as a Lua
574
regex. If you don't know Lua regexes you should be aware that the escape
575
character is �%� and the �-� sign is a special character (which means the same
576
as �*?� in Perl regexes). For more details, see the Lua
577
\href{http://www.lua.org/manual/}{reference manual} or the book
578
\href{http://www.lua.org/pil/}{\emph{programming in Lua}}. You might want to
579
use\footnote{The quotes in the example are just to make the shell happy.}
580
�-e='*'� if your regex uses the �$� anchor.%stopzone
582
\begin{cmdsubsub}{interact}{cf-interact}
583
interact_switch = �true, false�
586
Turn on or of interaction. Default is on. Turning interaction off prevents
587
\texdoc to ask you to choose a file to view when there are multiple choices,
588
and merely just print the list of files found.
590
\begin{cmdsubsub}{ext_list}{cf-ext_list}
594
Set the list of recognised extensions to ��list��. Default is
596
pdf, html, txt, dvi, ps,
598
This list is used to filter and sort the results (with the default value: pdf
599
first, etc). Two special values are recognised:
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!
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��, independantly of the
611
current value of �ext_list� and �mode� (unless it is the �regex� mode). In an
612
ideal world, this wouldn't be necessary since every sty file would have a
613
proper documentation in pdf, html or plain text, but\dots
615
For each ��ext�� in �ext_list� there should be a corresponding
616
�viewer_�ext�� value set. Defaults are defined corresponding to the default
617
�ext_list�, but you can add values if you want. For example, if you want
618
\texdoc to be able to find man pages and display them with the �man� command,
621
ext_list = 1, 5, pdf, html, txt, dvi, ps,
625
(This also makes man pages in man format take precedence over their pdf
628
\begin{cmdsubsub}{viewer_*}{cf-viewer_*}
632
Set the viewer command for files with extension ��ext�� to ��cmd��. For files
633
without extension, �viewer_txt� is used, and there's not �viewer_� variable.
634
In ��cmd��, �%s� can be used as a placeholder for the file name, which is
635
otherwise inserted at the end of the command. The command can be a arbitrary
638
\begin{cmdsubsub}{alias}{cf-alias}
639
alias �name� = �othername�
642
Everything has already been said in section~\ref{s-alias}.
644
\begin{cmdsubsub}{noise_level}{cf-noise_level}
648
Set the verbosity level to ��n��. This determines whether \texdoc will print
649
or not errors or debug information (to stderr). Default level is 3. The
650
numeric codes are as follow:
651
\begin{enumerate}[start=0]
652
\item Print nothing (not recommended).
653
\item Print only error messages.
654
\item Also print warnings.
655
\item Also print information messages.
656
\item Also print debug1 information messages.
659
Currently, the levels 5 and greater are not used, and the only ``debug''
660
information at level 4 is to print the command used to view a file just before
663
\subsection{Exit codes}\label{ss-exit}
665
The current exit code are as follow:
666
\begin{enumerate}[start=0]
669
\item Documentation not found for at least one argument.
672
\section{Bugs, warnings}\label{s-bugs}
674
There is currently no known bug (fingers crossed). But a few things you should
677
First of all, \texdoc doesn't always succeed in finding documentation (or
678
finds so many results that it is not useful). Moreover, it cannot handle very
679
correctly packages with many relevant documentation files at the moment
680
(see~\ref{ss-alias-rem}). Ideas about how to improve this are most welcome at
683
Second, support for zipped documentation, which have been ``available'' in
684
previous versions of \texdoc, is now disabled by default. The reasons are that
685
this support wasn't portable (didn't work on windows for example), and
686
moreover we won't ship compressed documentation in \texlive. However, the
687
code has not been totally removed and should be easy to activate again. If you
688
want to use this feature, please:
690
\item Look in \texdoc's code for instructions.
691
\item Be aware that the corresponding part of the code has not been well
692
tested, and that you are responsible of the unzipping command anyway.
693
\item Inform us either at the usual address or \mailto{tldistro@tug.org} if
694
you are a Linux, BSD, or whatever, distributor.
697
Finally, \texdoc is also missing a GUI version (texdoctk has never been the
698
GUI version of \texdoc, and is unmaintained and probably unmaintainable
699
anyway). This is on the list, but the time line is rather unclear at the