% this is texdoc's user manual % written by Manuel Pégourié-Gonnard in 2008, 2009 % distributed under the terms of GPL v3 or later \documentclass[a4paper, oneside]{scrartcl} \usepackage[latin1]{inputenc} \usepackage[T1]{fontenc} \usepackage{textcomp} \usepackage{fixltx2e} \usepackage{lmodern} \edef\ttmodern{\ttdefault} \usepackage[osf]{mathpazo} \renewcommand\sfdefault{uop} % optima \renewcommand\ttdefault{lmvtt} % lm tt proportional \renewcommand\familydefault{\sfdefault} \newcommand\otherfamily{\rmfamily} \newcommand\mylangle{\textlangle} \newcommand\myrangle{\textrangle} \usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle} \usepackage[rm, bf]{titlesec} \titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}} \titleformat{\subsubsection}[runin]{\otherfamily\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}\otherfamily #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}\mylangle\textme{#1}\myrangle}} \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\normalfont \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}% \else \unexpanded{\normalsize\normalfont \BUseVerbatim{verbmat}}% \fi \noexpand\label{\thelabel}}}% \aftergroup\sectioncmd} \makeatother \newcommand\maybedot{.} \newcommand\nodotthistime{% \renewcommand\maybedot{% \global\def\maybedot{.}}} \newenvironment{cmdsubsec}[2]{% \framedtrue \commandes\subsection{#1}{#2}% }{% \endcommandes} \newenvironment{cmdsubsub}[2]{% \framedfalse \commandes\subsubsection{#1}{#2}% }{% \endcommandes} \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{\url{http://tug.org/texdoc/}\\ Manuel Pégourié-Gonnard} \date{v0.42---2009/04/09} \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. \bigskip \texdoc's normal mode of operation is to find the more appropriate document for your request and open it. But sometimes it has a weird notion of ``appropriate'', and you'd better look at the list of all results and choose to see oen or more of them. For this, \texdoc offers various modes, like the ``search mode'' illustrated above. \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 two 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, then \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 ?}{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\footnote{It should be an allowed extension, see~\ref{cf-ext_list}, and preferably have a associated viewer defined, see~\ref{cf-viewer_*}.} 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-verbosity_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{texdoc@tug.org}, so that the faulty alias can be updated.} 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 your configuration file, type ©texdoc -f© and pick the file marked with a star (unless you are a system administrator or your home is shared between many machines whith different architectures, 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 just for \texdoc 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 ©TEXMFHOME/texdoc/texdoc-dist.cnf© \item ©TEXMFLOCAL/texdoc/texdoc-«platform».cnf© \item ©TEXMFLOCAL/texdoc/texdoc.cnf© \item ©TEXMFMAIN/texdoc/texdoc.cnf© \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»© stands 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. Finally, the special file ©texdoc-dist.cnf© allows you to install a newer version of \texdoc (including its default config file) in your home: see \href{http://tug.org/texdoc/}{the web page} for instructions on running \texdoc from the SVN. \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} 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}{-v, --verbosity, -d, --debug}{cl-n} -v=«n», --verbosity=«n», -d, --debug \end{cmdsubsub} See~\ref{cf-verbosity_level} and be aware that you must avoid spaces on the command line, and the ©=© sign is optional. The ©--debug© option sets verbosity at the maximum level. \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. Also, environment variables used by older versions of \texdoc are accepted. You can append ©_texdoc© to every name in the first column: this wins over every other name. \begin{center} \begin{tabular}{@{}l*3{@{ }l}@{}} New name & Old name 1 & Old name 2 & Config. param.\\ ©PAGER© & ©TEXDOCVIEW_txt© & ©TEXDOC_VIEWER_TXT© & ©viewer_txt© \\ ©BROWSER© & ©TEXDOCVIEW_html© & ©TEXDOC_VIEWER_HTML© & ©viewer_html© \\ ©DVIVIEWER© & ©TEXDOCVIEW_dvi© & ©TEXDOC_VIEWER_DVI© & ©viewer_dvi© \\ ©PSVIEWER© & ©TEXDOCVIEW_ps© & ©TEXDOC_VIEWER_PS© & ©viewer_ps© \\ ©PDFVIEWER© & ©TEXDOCVIEW_pdf© & ©TEXDOC_VIEWER_PDF© & ©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 off 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} There is a very special case: if the searched ©«name»© has ©.sty© extension, \texdoc enters a special search mode for ©.sty© files (not located in the same place as real documentation files) for this ©«name»©, independantly of the current value of ©ext_list© and ©mode© (unless it is the ©regex© mode). In an ideal world, this wouldn't be necessary since every sty file would have a proper documentation in pdf, html or plain text, but\dots For each ©«ext»© in ©ext_list© there should be a corresponding ©viewer_«ext»© value set. Defaults are defined corresponding to the default ©ext_list©, but you can add values if you want. For example, if you want \texdoc to be able to find man pages and display them with the ©man© command, you can use \begin{htcode} ext_list = 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}{verbosity_level}{cf-verbosity_level} verbosity_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[n] Also print debug(n-3) information messages. \end{enumerate} Currently, debug goes from 1 to 3 : ©debug1© prints the command used to view a file just before executing it, ©debug2© prints information about setting configuration paramters, and ©debug3© about the search paths used. \begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch} lastfile_switch = «true, false» \end{cmdsubsub} Prevents \texdoc from reading any other configuration file after this one. Mainly useful for installing a newer version of \texdoc in your home (see the \href{http://tug.org/texdoc/}{web site} for instructions on how to do so). \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 (or finds so many results that it is not useful). 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. \section{Licence}\label{s-licence} The current \texdoc program and its documentation are copyright 2008, 2009 Manuel Pégourié-Gonnard. They are free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but \emph{without any warranty}; without even the implied warranty of \emph{merchantability} or \emph{fitness for a particular purpose}. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see \url{http://www.gnu.org/licenses/}. \bigskip Previous work (texdoc program) in the public domain: \begin{itemize} \item Contributions from Reinhard Kotucha (2008). \item First texlua versions by Frank Küster (2007). \item Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson. \end{itemize} \bigskip \begin{center}\Large\rmfamily Happy \TeX{}ing! \end{center} \end{document}