summaryrefslogtreecommitdiff
path: root/Master/texmf
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2009-04-08 22:28:28 +0000
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2009-04-08 22:28:28 +0000
commit1b797180357c6ea612d9552c864074cdc3fa6f00 (patch)
tree8e67e45d6c5a068860d8af852042b0d44bf8b123 /Master/texmf
parent6ab0ac0df20a714049b1846058a9210682e19d89 (diff)
Texdoc version 0.42.
git-svn-id: svn://tug.org/texlive/trunk@12669 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf')
-rw-r--r--Master/texmf/doc/man/man1/texdoc.125
-rw-r--r--Master/texmf/doc/man/man1/texdoc.pdfbin4493 -> 5275 bytes
-rw-r--r--Master/texmf/doc/texdoc/texdoc.pdfbin357772 -> 189970 bytes
-rw-r--r--Master/texmf/doc/texdoc/texdoc.tex173
-rwxr-xr-xMaster/texmf/scripts/texdoc/texdoc.tlu672
-rw-r--r--Master/texmf/texdoc/texdoc.cnf13
6 files changed, 530 insertions, 353 deletions
diff --git a/Master/texmf/doc/man/man1/texdoc.1 b/Master/texmf/doc/man/man1/texdoc.1
index e814337e00c..96ab325f496 100644
--- a/Master/texmf/doc/man/man1/texdoc.1
+++ b/Master/texmf/doc/man/man1/texdoc.1
@@ -1,17 +1,14 @@
.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.36.
-.TH TEXDOC "1" "September 2008" "texdoc version: 0.4" "User Commands"
+.TH TEXDOC "1" "April 2009" "texdoc 0.42" "User Commands"
.SH NAME
-texdoc \- manual page for texdoc version: 0.4
+texdoc \- finding & viewing TeX documentation
.SH SYNOPSIS
.B texdoc
-\fI-h, --help | -v, --version | -f, --files | \fR[\fIoption(s)\fR] \fIname(s)\fR
+[\fIOPTIONS\fR]... [\fINAME\fR]...
.SH DESCRIPTION
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show this short help.
-.TP
-\fB\-v\fR, \fB\-\-version\fR
-Print the version of the program.
+texdoc tries to find appropriate TeX documentation for the specified NAME(s).
+With no NAME, it can print configuration information (\fB\-f\fR, \fB\-\-files\fR);
+the usual \fB\-\-help\fR and \fB\-\-version\fR options are also accepted.
.TP
\fB\-f\fR, \fB\-\-files\fR
Print the name of the config files being used.
@@ -46,8 +43,11 @@ Use interactive menus.
\fB\-I\fR, \fB\-\-nointeract\fR
Use plain lists, no interaction required.
.TP
-\fB\-n\fR, \fB\-\-noise\-level\fR=\fIN\fR
+\fB\-v\fR, \fB\-\-verbosity\fR=\fIN\fR
Set verbosity level to N.
+.TP
+\fB\-d\fR, \fB\-\-debug\fR
+Set verbosity level to maximum.
.SS "Environment:"
.IP
PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
@@ -57,5 +57,6 @@ PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
.SS "Homepage:"
.IP
http://tug.org/texdoc/
-.PP
-The full manual is accessed via `texdoc texdoc'.
+.SS "Manual:"
+.IP
+displayed by `texdoc texdoc'.
diff --git a/Master/texmf/doc/man/man1/texdoc.pdf b/Master/texmf/doc/man/man1/texdoc.pdf
index 92222ab40c4..996ff813ef8 100644
--- a/Master/texmf/doc/man/man1/texdoc.pdf
+++ b/Master/texmf/doc/man/man1/texdoc.pdf
Binary files differ
diff --git a/Master/texmf/doc/texdoc/texdoc.pdf b/Master/texmf/doc/texdoc/texdoc.pdf
index 101d08f5ac9..60543cbda06 100644
--- a/Master/texmf/doc/texdoc/texdoc.pdf
+++ b/Master/texmf/doc/texdoc/texdoc.pdf
Binary files differ
diff --git a/Master/texmf/doc/texdoc/texdoc.tex b/Master/texmf/doc/texdoc/texdoc.tex
index c83ed8bebc3..ed521cf88ba 100644
--- a/Master/texmf/doc/texdoc/texdoc.tex
+++ b/Master/texmf/doc/texdoc/texdoc.tex
@@ -1,19 +1,27 @@
% this is texdoc's user manual
-% written by Manuel Pégourié-Gonnard in 2008
-% licensed under the WTFPL version 2
+% 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}
+
+\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]{\itshape}{%
+\titleformat{\subsubsection}[runin]{\otherfamily\itshape}{%
\makebox[0pt][r]{\thetitle\kern1pc}}{%
0pt}{}[\maybedot\space --- ]
@@ -55,7 +63,7 @@
\newcommand\inputcolorname{red}
\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
\newcommand\textpa[1]{% % noms d'extensions (package)
- {\normalfont\color{special}\sffamily #1}}
+ {\normalfont\color{special}\otherfamily #1}}
\newcommand\cofont{% % code
\color{code}\normalfont\ttfamily}
\newcommand\textco[1]{{\cofont#1}}
@@ -73,7 +81,7 @@
\catcode`\ 10\relax
\newcommand\meta[1]{% % variantes à remplacer
- {\color{special}\textlangle\textme{#1}\textrangle}}
+ {\color{special}\mylangle\textme{#1}\myrangle}}
\newcommand\commandline[1]{%
\prompt\space \textcolor{input}{#1}}
\newcommand\prompt{\ding{229}}
@@ -105,10 +113,10 @@
\xdef\sectioncmd{\noexpand\nodotthistime
\thecmd[\bmtext]{%
\ifframed
- \unexpanded{\normalsize
+ \unexpanded{\normalsize\normalfont
\fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
\else
- \unexpanded{\normalsize
+ \unexpanded{\normalsize\normalfont
\BUseVerbatim{verbmat}}%
\fi
\noexpand\label{\thelabel}}}%
@@ -149,13 +157,8 @@
\subtitle{Finding \& viewing \TeX documentation
}
\author{\url{http://tug.org/texdoc/}\\
- 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.}
- }
-\date{v0.4---2008/08/01}
+ Manuel Pégourié-Gonnard}
+\date{v0.42---2009/04/09}
\begin{document}
\VerbatimFootnotes
@@ -197,8 +200,13 @@ 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.
+\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»
@@ -228,7 +236,7 @@ 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.
+To try and make you happy, \texdoc offers two other modes, introduced below.
\begin{cmdsubsec}{List mode}{ss-list}
texdoc -l «name»
@@ -259,7 +267,7 @@ documented source code\dots
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
+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}.
@@ -315,8 +323,8 @@ The concept of alias is very\footnote{See~\ref{ss-alias-rem} for why it is
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):
+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»
@@ -328,8 +336,9 @@ to get rid of this message):
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:
+ \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 þ
@@ -385,10 +394,11 @@ 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:
+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) &
@@ -408,8 +418,8 @@ 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©.
+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}
@@ -427,22 +437,26 @@ in the following order, where first value found is always used:
\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
+ \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»© stand for the name of the current
+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.
+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}
@@ -457,8 +471,8 @@ corresponding configuration option.
Shows a quick help message (namely a list of command-line options) and exits
successfully.
-\begin{cmdsubsub}{-v, --version}{cl-v}
- -v, --version
+\begin{cmdsubsub}{-V, --version}{cl-v}
+ -V, --version
\end{cmdsubsub}
Show the current version of the program and exits successfully.
@@ -476,7 +490,7 @@ recommended file for user settings.
-w, --view, -l, --list, -m, --mixed, -s, --search, -r, --regex
\end{cmdsubsub}
-\leavevmode\par\noindent See \ref{cf-mode}.
+See~\ref{cf-mode}.
\begin{cmdsubsub}{-a, -A, --alias, --noalias}{cl-a}
-a, --alias, -A, --noalias
@@ -500,27 +514,30 @@ 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»
+\begin{cmdsubsub}{-v, --verbosity, -d, --debug}{cl-n}
+ -v=«n», --verbosity=«n», -d, --debug
\end{cmdsubsub}
-See~\ref{cf-noise_level} and be aware that you must avoid spaces on the command
-line, and the ©=© sign is optional.
+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. Here is the (obvious)
-correspondence:
+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}{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}
+ \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}
@@ -583,7 +600,7 @@ use\footnote{The quotes in the example are just to make the shell happy.}
interact_switch = «true, false»
\end{cmdsubsub}
-Turn on or of interaction. Default is on. Turning interaction off prevents
+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.
@@ -641,8 +658,8 @@ shell construct.
Everything has already been said in section~\ref{s-alias}.
-\begin{cmdsubsub}{noise_level}{cf-noise_level}
- noise_level = «n»
+\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
+ verbosity_level = «n»
\end{cmdsubsub}
Set the verbosity level to ©«n»©. This determines whether \texdoc will print
@@ -653,12 +670,20 @@ numeric codes are as follow:
\item Print only error messages.
\item Also print warnings.
\item Also print information messages.
- \item Also print debug1 information messages.
+ \item[n] Also print debug(n-3) 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.
+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}
@@ -699,8 +724,36 @@ 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
+\begin{center}\Large\rmfamily
Happy \TeX{}ing!
\end{center}
diff --git a/Master/texmf/scripts/texdoc/texdoc.tlu b/Master/texmf/scripts/texdoc/texdoc.tlu
index defad83abb8..2f5969af8ed 100755
--- a/Master/texmf/scripts/texdoc/texdoc.tlu
+++ b/Master/texmf/scripts/texdoc/texdoc.tlu
@@ -1,89 +1,109 @@
#!/usr/bin/env texlua
-- $Id$ -*-Lua-*-
---[[Revised 2008 by Manuel Pégourié-Gonnard
- with contributions from Reinhard Kotucha.
- First texlua versions by Frank Küster (2007).
- Origial shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
- Public domain.]]
---[[ Changelog
- 0.4 2008-07
- - moved configuration from texmf.cnf to texdoc.cnf
- - added an 'alias' feature
- - new modes 'mixed' and 'regex'
- - file lists are now menus (select number to view results)
- - changed the search modes to get only the more relevant results (hopefully)
- - /!\ zip support disabled by default (not portable) (see comments below)
-
- 0.3 2007-06-28
- - added changelog
- - better OS detection for default viewer settings
- - removed some debugging code
- - -s now works in dirs without ls-R, too
-
- 0.2 2007-06-28
- - implemented reading of configuration from texmf.cnf
- - fixed "-s" option
-
- 0.1
- - initial public release
-]]
-
--- some constants
+--[[
+Copyright 2008, 2009 Manuel Pégourié-Gonnard.
+
+This program is 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 WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or 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 <http://www.gnu.org/licenses/>.
+
+Previous work in the public domain:
+- Contributions from Reinhard Kotucha (2008).
+- First texlua versions by Frank Küster (2007).
+- Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.
+--]]
+
+--------------------------------------------------------------------------------
+------------------ global constants and general functions ------------------
+--------------------------------------------------------------------------------
+
+----------------------------- global constants -----------------------------
+
+-- progname and version
progname = 'texdoc'
-version = '0.4'
--- make sure to update setup_config_from_cl() accordingly
+version = '0.42'
+if string.sub(version, -1) == '+' then
+ local svnrev = string.match('$Rev: 44 $', '%$Rev:%s*(%d*)%s*%$');
+ version = version..' svn r'..svnrev
+end
+
+-- make sure to update setup_config_from_cl() accordingly
-- and set a default value in setup_config_from_defaults() if relevant
usage_msg = [[
-Usage: texdoc -h, --help | -v, --version | -f, --files | [option(s)] name(s)
- -h, --help Show this short help.
- -v, --version Print the version of the program.
- -f, --files Print the name of the config files being used.
- -e, --extensions=L Require file extensions to be in the list L.
- -w, --view Use view mode: start a viewer.
- -m, --mixed Use mixed mode (view or list).
- -l, --list Use list mode: don't start a viewer.
- -s, --search Search for name as a substring.
- -r, --regex Search for name as a lua regex.
- -a, --alias Use the alias table.
- -A, --noalias Don't use the alias table.
- -i, --interact Use interactive menus.
- -I, --nointeract Use plain lists, no interaction required.
- -n, --noise-level=N Set verbosity level to N.
-Environment:
- PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
-Files:
- <texmf>/texdoc/texdoc.cnf files, see the -f option.
-Homepage:
- http://tug.org/texdoc/
-The full manual is accessed via `texdoc texdoc'.]]
+texdoc tries to find appropriate TeX documentation for the specified NAME(s).
+With no NAME, it can print configuration information (-f, --files);
+the usual --help and --version options are also accepted.
+Usage: texdoc [OPTIONS]... [NAME]...
+ -f, --files Print the name of the config files being used.
+ -e, --extensions=L Require file extensions to be in the list L.
+ -w, --view Use view mode: start a viewer.
+ -m, --mixed Use mixed mode (view or list).
+ -l, --list Use list mode: don't start a viewer.
+ -s, --search Search for name as a substring.
+ -r, --regex Search for name as a lua regex.
+ -a, --alias Use the alias table.
+ -A, --noalias Don't use the alias table.
+ -i, --interact Use interactive menus.
+ -I, --nointeract Use plain lists, no interaction required.
+ -v, --verbosity=N Set verbosity level to N.
+ -d, --debug Set verbosity level to maximum.
+Environment: PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER.
+Files: <texmf>/texdoc/texdoc.cnf files, see the -f option.
+Homepage: http://tug.org/texdoc/
+Manual: displayed by `texdoc texdoc'.]]
+
+error_msg = [[
+Try `texdoc --help' for a short help, `texdoc texdoc' for the user manual.]]
notfound_msg = [[
Sorry, no documentation found for PKGNAME.
If you are unsure about the name, try searching CTAN's TeX catalogue at
http://ctan.org/search.html#byDescription.]]
-place_holder = '%%s' -- used for viewer commands
+
+known_options = {
+ 'viewer_.*',
+ 'mode',
+ 'interact_switch', 'alias_switch',
+ 'ext_list',
+ 'verbosity_level',
+ 'lastfile_switch',
+}
+
err_priority = {
error = 1,
warning = 2,
info = 3,
debug1 = 4,
+ debug2 = 5,
+ debug3 = 6,
}
+err_max = 6
+
+place_holder = '%%s' -- used for viewer commands
-- zip/gz support
--
-- optionally, texdoc can support compressed documentation, but this is
-- system-dependant (commands for unzipping, temporary files, etc).
-- Since TeX Live doesn't ship compressed doc, downstream distributors who
--- want to ship zipped should change support_zipped to true *and* make sure
+-- want to ship zipped doc should change support_zipped to true *and* make sure
-- everything works for them (look for support_zipped in the code).
-- If you use this feature, please let us know: if nobody uses it,
-- we'll drop it at some point.
support_zipped = false
+-------------------------- general-use functions ---------------------------
--- BEGIN function definitions (till the 'END' mark)
----=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
--- a general-use function
+-- Remark: we always assume our tables have no hole (that is, no nil value
+-- followed by a non-nil value). So we use the simple iterator below, and
+-- the # operator sometimes (a bit faster than table.getn).
function list (t)
local i = 0
return function ()
@@ -92,66 +112,81 @@ function list (t)
end
end
--- Remark: we always assume our tables have no hole (that is, no nil value
--- followed by a non-nil value). So we use the simple iterator above, and
--- the # operator sometimes (bit faster than table.getn).
+-- remove the 'abc/../' components in a path
+function simplify_path (path)
+ local res = string.gsub (path, '/[^/]+/%.%./', '/')
+ return res -- get rid of gsub's 2nd return value
+end
--- functions for the search options
------------------------------------
+-- change '/' to '\' on windows, removine 'abc/../' components first
+if os.type == "windows" then
+ function win32_hook (path)
+ local res = string.gsub (simplify_path(path), '/', '\\')
+ return res -- get rid of gsub's 2nd return value
+ end
+else
+ function win32_hook (path)
+ return simplify_path(path)
+ end
+end
+
+--------------------------------------------------------------------------------
+-------------------------- functions for searching -------------------------
+--------------------------------------------------------------------------------
+
+------------------ exploring trees (kpse-style functions) ------------------
--- BEGIN kpse-like
+-- global variables:
+-- texdocs: a Lua table version of $TEXDOCS
+-- do_recurse: do_recurse[i] = 1 iff texdocs[i] ends with // in $TEXDOCS
+-- must_have_lsr: must_have_lsr[i] = 1 iff texdocs[i] starts with !! in $TEXDOCS
+-- exact_docfiles: list of "exact matches"
+-- rel_docfiles: list of "non-exact matches"
--- get global texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
+-- set texdocs, do_recurse and must_have_lsr lists from kpse's $TEXDOCS
function get_texdocs ()
local sep = (os.type == 'windows') and ';' or ':'
texdocs = kpse.expand_var ("$TEXDOCS")
-- expand the path and turn it into a lua list
texdocs = string.explode (kpse.expand_braces (texdocs), sep)
do_recurse, must_have_lsr = {}, {} -- global
+ err_print('Search paths:', 'debug3')
for i, dir in ipairs (texdocs) do
local n
dir, n = string.gsub (dir, '//$', '')
do_recurse[i] = (n == 1)
texdocs[i], n = string.gsub (dir, '^!!', '')
must_have_lsr[i] = (n == 1)
+ err_print(string.format('%s (do_recurse=%s, must_have_lsr=%s)',
+ texdocs[i],
+ do_recurse[i] and 'true' or 'false',
+ must_have_lsr[i] and 'true' or 'false'), 'debug3')
end
end
--- says if ext is 'good' according to ext_list
-function is_good_ext (ext)
- for e in list (config.ext_list) do
- if e == '*' then
- return true
- elseif (e == '') and (not ext) then
- return true
- elseif ext == e then
- return true
- end
- end
- return false
-end
+-- once get_texdocs() is done, roots are represented by their index in texdocs
+-- usefull to avoid fake matches and also for the sort routine
+-- the next two functions do the conversions
--- include a file in the lists if it should be
-function process_file (file, pathfile, code, pattern)
- local base, ext = string.match(file, '^(.*)%.(.*)$')
- if string.find(pathfile, pattern, 1, no_regex) and is_good_ext (ext)
- then
- if (base == pattern) or (file == pattern) then
- table.insert(exact_docfiles, code_path (code, pathfile))
- else
- table.insert(rel_docfiles, code_path (code, pathfile))
- end
- end
-end
-
--- encodes the base path on two digits and concatenate with filename
--- see real_path() for decoding
+-- encode the base path on two digits and concatenate with filename
function code_path (code, file)
local padding = (code > 9) and '' or '0'
return padding..code..':'..file
end
--- scan a tree
+-- decode a path as given in *_docfiles into a real path
+function real_path (fake)
+ local code, file = string.match (fake, '^(.-):(.*)$')
+ code = tonumber (code)
+ return win32_hook (texdocs[code]..'/'..file)
+end
+
+-- merge two components of a path, taking care of empty components
+function merge_path (a, b)
+ return ((a == '') or (b == '')) and a..b or a..'/'..b
+end
+
+-- scan a tree without ls-R file
function scan_tree (code, path, pattern, recurse)
for file in lfs.dir(path) do
if file ~= '.' and file ~= '..' then
@@ -165,7 +200,7 @@ function scan_tree (code, path, pattern, recurse)
end
end
--- finds a root with ls-R above path and return it or nil
+-- finds a ls-R file in a parent directory an return it or nil
function lsr_root (path)
if not lfs.isdir (path) then return end
local root, shift = path, ''
@@ -181,11 +216,6 @@ function lsr_root (path)
end
end
--- merge two components of a path, taking care of empty components
-function merge_path (a, b)
- return ((a == '') or (b == '')) and a..b or a..'/'..b
-end
-
-- scan a ls-R file
function scan_lsr (code, shift, pattern)
local isdoc = false
@@ -215,8 +245,18 @@ function scan_lsr (code, shift, pattern)
lsr:close()
end
--- find dirfiles according to pattern
+-- remove directories from a list
+function rmdirs (files)
+ local res = {}
+ for f in list (files) do
+ if not is_dir[f] then table.insert(res, f) end
+ end
+ return res
+end
+
+-- find docfiles "matching" pattern
function populate_docfiles (pattern)
+ pattern = normalize_pattern(pattern)
if not texdocs then get_texdocs() end
rel_docfiles, exact_docfiles = {}, {} -- global
is_dir = {} -- global; is_dir[path] = true iff path is a dir, see scan_lsr
@@ -236,8 +276,6 @@ function populate_docfiles (pattern)
rel_docfiles = rmdirs (rel_docfiles)
end
--- END kpse-like
-
-- like populate_docfiles, but rel replaces exact if exact is empty
function mixed_populate_docfiles (pattern)
populate_docfiles (pattern)
@@ -249,99 +287,149 @@ function mixed_populate_docfiles (pattern)
end
end
--- translate a path as given by populate_docfiles into a real path
--- should never be called before get_texdocs()
-function real_path (fake)
- local code, file = string.match (fake, '^(.-):(.*)$')
- code = tonumber (code)
- return win32_hook (texdocs[code]..'/'..file)
+-- for sty files, we obviously don't want to look in TEXDOCS...
+-- and we don't need a list since those are not duplicated (ahem...)
+function populate_docfiles_sty (styname)
+ exact_docfiles = { kpse.find_file (styname) }
+ rel_docfiles = {}
end
--- now a special function that does nothing on Unix
-if os.type == "windows" then
- function win32_hook (path)
- local res = string.gsub (path, '/', '\\')
- return res -- get rid of gsub's 2nd arg
- end
-else
- function win32_hook (path)
- return path
+---------------------------- selecting results -----------------------------
+
+-- says if ext is 'good' according to ext_list
+function is_good_ext (ext)
+ for e in list (config.ext_list) do
+ if e == '*' then
+ return true
+ elseif (e == '') and (not ext) then
+ return true
+ elseif ext == e then
+ return true
+ end
end
+ return false
end
--- remove directories from the files list
-function rmdirs (files)
- local res = {}
- for f in list (files) do
- if not is_dir[f] then table.insert(res, f) end
+-- include a file in the *_docfiles lists if it "matches"
+function process_file (file, pathfile, code, pattern)
+ local base, ext = string.match(string.lower(file), '^(.*)%.(.*)$')
+ if string.find(string.lower(pathfile), pattern, 1, no_regex)
+ and is_good_ext (ext) then
+ if (base == pattern) or (file == pattern) then
+ table.insert(exact_docfiles, code_path (code, pathfile))
+ else
+ table.insert(rel_docfiles, code_path (code, pathfile))
+ end
end
- return res
end
--- for sty files, we obviously don't want to look in TEXDOCS...
--- and we don't need a list since those are not duplicated (ahem...)
-function populate_docfiles_sty (styname)
- exact_docfiles = { kpse.find_file (styname) }
- rel_docfiles = {}
+-- for now, just make lowercase, but may do more later
+function normalize_pattern (pattern)
+ return string.lower(pattern)
+end
+
+----------------------------- sorting results ------------------------------
+
+-- compare two filenames with the following rule:
+-- 1. extensions are ordered as in ext_list first,
+-- 2. then filenames lexicographically.
+function file_order (a, b)
+ local ext_a = string.match (a, '^.*%.(.*)$')
+ local ext_b = string.match (b, '^.*%.(.*)$')
+ ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
+ ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
+ if ext_pos_a < ext_pos_b then
+ return true
+ elseif ext_pos_a > ext_pos_b then
+ return false
+ else
+ return (a < b)
+ end
end
+--------------------------------------------------------------------------------
+---------------- functions to set config values and aliases ----------------
+--------------------------------------------------------------------------------
--- functions to set config values and aliases
----------------------------------------------
+---------------------------- general functions -----------------------------
--- set a value without overwriting if already set and
--- using to special types: *_list and *_switch
-function set_config_element (key, value, file, line)
- if config[key] == nil then -- must explicitly test for nil, not false
- if string.match(key, '_list$') then
- -- this is actually a coma-separated list of values
- local values = string.explode(value, ',')
- local inverse = {}
- for i, j in ipairs(values) do
- values[i] = string.gsub(j, '%s*$', '')
- values[i] = string.gsub(j, '^%s*', '')
- inverse[j] = i
- end
- config[key] = values
- config[key..'_inv'] = inverse
- config[key..'_max'] = #values
- elseif string.find (key, '_switch$') then
- if value == 'true' then
- config[key] = true
- elseif value == 'false' then
- config[key] = false
- else
- config_warn (key, value, file, line)
- end
- elseif string.find (key, '_level$') then
- local val = tonumber (value)
- if val then
- config[key] = val
- else
- config_warn (key, value, file, line)
- end
+-- set a config parameter, but don't overwrite it if already set
+-- three special types: *_list (list), *_switch (boolean), *_level (number)
+function set_config_element (key, value, context)
+ local is_known = false -- is key a valid option?
+ for option in list(known_options) do
+ if string.match(key, option) then is_known = true break end
+ end
+ -- warn and exit if key is not a known option
+ if not is_known then config_warn(key, nil, context) return end
+ -- exit if key is already set (/!\ must test for nil, not false)
+ if not (config[key] == nil) then return nil end
+ if string.match(key, '_list$') then -- coma-separated list
+ local values = string.explode(value, ',')
+ local inverse = {}
+ for i, j in ipairs(values) do -- sanitize values...
+ values[i] = string.gsub(j, '%s*$', '')
+ values[i] = string.gsub(j, '^%s*', '')
+ inverse[j] = i -- ... and build inverse mapping on the way
+ end
+ config[key] = values
+ config[key..'_inv'] = inverse
+ config[key..'_max'] = #values
+ elseif string.find (key, '_switch$') then -- boolean
+ if value == 'true' then
+ config[key] = true
+ elseif value == 'false' then
+ config[key] = false
+ else
+ config_warn (key, value, context)
+ end
+ elseif string.find (key, '_level$') then -- integer
+ local val = tonumber (value)
+ if val then
+ config[key] = val
else
- config[key] = value
+ config_warn (key, value, context)
end
+ else -- string
+ config[key] = value
+ end
+ -- special case: if we just set verbosity_level, print version info now
+ if key == 'verbosity_level' then
+ err_print(arg[0]..' version '..version, 'debug1')
end
+ -- now tell what we have just done, for debugging
+ err_print('Setting "'..key..'='..value..'" '
+ ..context_to_string(context)..'.', 'debug2')
end
-- a helper function for warning messages in the above
-function config_warn (key, value, file, line)
- local begin = 'illegal value '..value..' for key '..key
+function config_warn (key, value, context)
+ local begin = value and 'Illegal value "'..value..'" for option "'..key..'"'
+ or 'Unkown option "'..key..'"'
local ending = '. Skipping.'
- if file and line then
- err_print (begin..'\nin '..file..' line '..line..ending, 'warning')
+ err_print (begin..'\n '..context_to_string(context)..ending, 'warning')
+end
+
+-- interpreting 'context' for the previous functions
+function context_to_string(context)
+ if not context then return '(no context)' end
+ if context.src == 'cl' then
+ return 'from command line option "'..context.name..'"'
+ elseif context.src == 'env' then
+ return 'from environment variable "'..context.name..'"'
+ elseif context.src == 'file' then
+ return 'in file "'..context.file..'" on line '..context.line
+ elseif context.src == 'def' then
+ return 'from built-in defaults'
else
- err_print (begin..ending, 'warning')
+ return 'from unkown source (should not happen, please report)'
end
end
-
-- set a whole list, also whithout overwriting
-function set_config_list (conf)
+function set_config_list (conf, context)
for key, value in pairs(conf) do
- set_config_element (key, value)
+ set_config_element (key, value, context)
end
end
@@ -352,89 +440,96 @@ function set_alias (key, value)
end
end
+------------------------ options from command line -------------------------
+
-- set config from the command line
-- Please make sure to update usage_msg accordingly
-- and set a default value in setup_config_from_defaults() if relevant.
+-- TODO: should use some getopt_long()-like mechanism some day
function setup_config_from_cl ()
+ local curr_arg
+ local function set_config_elt(key, val)
+ set_config_element(key, val, {src='cl', name=curr_arg})
+ end
while arg[1] and string.match(arg[1],'^%-') do
curr_arg = table.remove(arg,1)
if (curr_arg == '-h') or (curr_arg == '--help') then
print (usage_msg)
os.exit(0)
- elseif (curr_arg == '-v') or (curr_arg == '--version') then
- print (progname .. ' version: ' .. version )
+ elseif (curr_arg == '-V') or (curr_arg == '--version') then
+ print (progname .. ' ' .. version )
os.exit(0)
elseif (curr_arg == '-f') or (curr_arg == '--files') then
- print_config_files ()
+ print (progname .. ' ' .. version )
+ setup_config_from_files ()
+ show_config_files (print, true)
os.exit(0)
elseif (curr_arg == '-w') or (curr_arg == '--view') then
- set_config_element('mode', 'view')
+ set_config_elt('mode', 'view')
elseif (curr_arg == '-m') or (curr_arg == '--mixed') then
- set_config_element('mode', 'mixed')
+ set_config_elt('mode', 'mixed')
elseif (curr_arg == '-l') or (curr_arg == '--list') then
- set_config_element('mode', 'list')
+ set_config_elt('mode', 'list')
elseif (curr_arg == '-s') or (curr_arg == '--search') then
- set_config_element ('mode', 'search')
+ set_config_element ('mode', 'search', {src='cl', name=curr_arg})
elseif (curr_arg == '-r') or (curr_arg == '--regex') then
- set_config_element ('mode', 'regex')
+ set_config_element ('mode', 'regex', {src='cl', name=curr_arg})
elseif (curr_arg == '-I') or (curr_arg == '--nointeract') then
- set_config_element('interact_switch', 'false')
+ set_config_elt('interact_switch', 'false')
elseif (curr_arg == '-i') or (curr_arg == '--interact') then
- set_config_element('interact_switch', 'true')
+ set_config_elt('interact_switch', 'true')
elseif (curr_arg == '-A') or (curr_arg == '--noalias') then
- set_config_element('alias_switch', 'false')
+ set_config_elt('alias_switch', 'false')
elseif (curr_arg == '-a') or (curr_arg == '--alias') then
- set_config_element('alias_switch', 'true')
- elseif string.match(curr_arg, '^%-n') then
- set_config_element('noise_level',
- string.gsub(curr_arg, '^%-n=?', ''))
- elseif string.match(curr_arg, '^%-%-noise%-level') then
- set_config_element('noise_level',
- string.gsub(curr_arg, '^%-%-noise%-level=?', ''))
+ set_config_elt('alias_switch', 'true')
+ elseif (curr_arg == '-d') or (curr_arg == '--debug') then
+ set_config_elt('verbosity_level', err_max)
+ elseif string.match(curr_arg, '^%-v') then
+ local value = string.gsub(curr_arg, '^%-v=?', '')
+ set_config_elt('verbosity_level', value)
+ elseif string.match(curr_arg, '^%-%-verbosity') then
+ local value = string.gsub(curr_arg, '^%-%-verbosity=?', '')
+ set_config_elt('verbosity_level', value)
elseif string.match(curr_arg, '^%-e') then
- set_config_element('ext_list',
- string.gsub(curr_arg, '^%-e=?', ''))
+ local value = string.gsub(curr_arg, '^%-e=?', '')
+ set_config_elt('ext_list', value)
elseif string.match(curr_arg, '^%-%-extensions') then
- set_config_element('ext_list',
- string.gsub(curr_arg, '^%-%-extensions=?', ''))
+ local value = string.gsub(curr_arg, '^%-%-extensions=?', '')
+ set_config_elt('ext_list', value)
else
- err_print ("unknow option: "..curr_arg, "error")
- print (usage_msg)
+ err_print ("unknown option: "..curr_arg, "error")
+ print (error_msg)
os.exit(1)
end
end
end
--- the default value af config.alias_switch depends on the mode as follows
-function alias_from_mode (mode)
- if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then
- return 'true'
- else
- return 'false'
- end
-end
+------------------------- config from environment --------------------------
-- set config from environment if available
function setup_config_from_env ()
- set_config_list {
- viewer_pdf = os.getenv ("PDFVIEWER_texdoc")
- or os.getenv ("TEXDOCVIEW_pdf") or os.getenv ("TEXDOC_VIEWER_PDF")
- or os.getenv ("PDFVIEWER"),
- viewer_ps = os.getenv ("PSVIEWER_texdoc")
- or os.getenv ("TEXDOCVIEW_ps") or os.getenv ("TEXDOC_VIEWER_PS")
- or os.getenv ("PSVIEWER"),
- viewer_dvi = os.getenv ("DVIVIEWER_texdoc")
- or os.getenv ("TEXDOCVIEW_dvi") or os.getenv ("TEXDOC_VIEWER_DVI")
- or os.getenv ("DVIVIEWER"),
- viewer_html = os.getenv ("BROWSER_texdoc")
- or os.getenv ("TEXDOCVIEW_html") or os.getenv ("TEXDOC_VIEWER_HTML")
- or os.getenv ("BROWSER"),
- viewer_txt = os.getenv ("PAGER_texdoc")
- or os.getenv ("TEXDOCVIEW_txt") or os.getenv ("TEXDOC_VIEWER_TXT")
- or os.getenv ("PAGER"),
- }
+ local function set_config_elt_from_vars(key, vars)
+ for var in list(vars) do
+ local value = os.getenv(var)
+ if value then
+ set_config_element(key, value, {src='env', name=var})
+ end
+ end
+ end
+ set_config_elt_from_vars('viewer_pdf',
+ {"PDFVIEWER_texdoc", "TEXDOCVIEW_pdf", "TEXDOC_VIEWER_PDF", "PDFVIEWER"})
+ set_config_elt_from_vars('viewer_ps',
+ {"PSVIEWER_texdoc", "TEXDOCVIEW_ps", "TEXDOC_VIEWER_PS", "PSVIEWER"})
+ set_config_elt_from_vars('viewer_dvi',
+ {"DVIVIEWER_texdoc", "TEXDOCVIEW_dvi", "TEXDOC_VIEWER_DVI", "DVIVIEWER"})
+ set_config_elt_from_vars('viewer_html',
+ {"BROWSER_texdoc", "TEXDOCVIEW_html", "TEXDOC_VIEWER_HTML", "BROWSER"})
+ set_config_elt_from_vars('viewer_txt',
+ {"PAGER_texdoc", "TEXDOCVIEW_txt", "TEXDOC_VIEWER_TXT", "PAGER"})
end
+---------------------- options and aliases from files ----------------------
+
-- set config+aliases from a particular config file assumed to exist
function read_config_file(configfile)
local cnf = assert(io.open(configfile, 'r'))
@@ -449,7 +544,8 @@ function read_config_file(configfile)
line = string.gsub(line, '^%s*', '') -- remove leading spaces
key, val = string.match(line, '^([%a%d_]+)%s*=%s*(.+)')
if key and val then
- set_config_element(key, val, configfile, lineno)
+ set_config_element(key, val, {
+ src='file', file=configfile, line=lineno})
else
key, val = string.match(line, '^alias%s+([%a%d_-]+)%s*=%s*(.+)')
if key and val then
@@ -471,33 +567,54 @@ function get_config_files ()
local TEXMFHOME = kpse.var_value ('TEXMFHOME')
local TEXMFLOCAL = kpse.var_value ('TEXMFLOCAL')
local TEXMFMAIN = kpse.var_value ('TEXMFMAIN')
- local config_files = {}
return {
TEXMFHOME .. '/texdoc/texdoc-'..platform..'.cnf',
TEXMFHOME .. '/texdoc/texdoc.cnf',
+ TEXMFHOME .. '/texdoc/texdoc-dist.cnf',
TEXMFLOCAL .. '/texdoc/texdoc-'..platform..'.cnf',
TEXMFLOCAL .. '/texdoc/texdoc.cnf',
TEXMFMAIN .. '/texdoc/texdoc.cnf'
}
end
+-- the config_files table is shared by the next two functions
+do
+local config_files = {}
+
-- set config/aliases from all config files
function setup_config_from_files ()
- for file in list (get_config_files ()) do
- if lfs.isfile(file) then read_config_file (file) end
+ for i, file in ipairs (get_config_files ()) do
+ local found = lfs.isfile(file)
+ config_files[i] = {
+ path = file,
+ status = found and (config.lastfile_switch
+ and 'disabled' or 'active') or 'absent',
+ }
+ if config_files[i].status == 'active' then
+ read_config_file (file)
+ end
end
end
-- now a special information function (see -f,--file option)
-function print_config_files ()
- print "Configuration files are:"
- for i, file in ipairs (get_config_files ()) do
- local found = lfs.isfile(file) and "(active)" or "(not found)"
- local home = (i==2) and "* " or "" -- home conffile is the 2nd
- print (home..found, win32_hook(file))
+function show_config_files (print_fun, prefix)
+ print_fun("Configuration files are:")
+ for i, file in ipairs (config_files) do
+ local home = prefix and
+ ((i==2) and "(*) " or " ") -- home conffile is the 2nd
+ or ''
+ print_fun (home..file.status..'\t'..win32_hook(file.path))
+ end
+ if prefix then
+ print("(*) This is the recommended configuration file "
+ .. "for your personal preferences.")
end
end
+end -- scope of config_files
+
+---------------------- options from built-in defaults ----------------------
+
-- for default viewer on general Unix, we have a list; the following two
-- functions are used to check in the path which program is available
@@ -521,19 +638,23 @@ end
-- set some fall-back default values if no previous value is set
function setup_config_from_defaults()
+ local function set_config_ls(ls) set_config_list(ls, {src='def'}) end
+ local function set_config_elt(key, val)
+ set_config_element(key, val, {src='def'})
+ end
if (os.type == "windows") then
-- probably Windows (or OS/2)
-- which commands should we use for unzipping?
- set_config_list {
+ set_config_ls {
viewer_dvi = 'start ""',
viewer_html = 'start ""',
viewer_pdf = 'start ""',
viewer_ps = 'start ""',
- viewer_txt = 'start ""',
+ viewer_txt = 'start cmd /k more',
}
else -- since we don't support msdos, if os.type is not windows, it's unix
if (os.name == 'macosx') then
- set_config_list {
+ set_config_ls {
viewer_dvi = 'open',
viewer_html = 'open',
viewer_pdf = 'open',
@@ -541,7 +662,7 @@ function setup_config_from_defaults()
viewer_txt = 'less',
}
else
- set_config_list {
+ set_config_ls {
viewer_dvi = first_in_path {
{'evince', '(evince %s) &'},
{'okular', '(okular %s) &'},
@@ -583,33 +704,45 @@ function setup_config_from_defaults()
end
end
-- then various stuff
- set_config_list {
+ set_config_ls {
mode = 'view',
- interact_switch = 'true',
- noise_level = '3',
+ interact_switch = 'true',
+ verbosity_level = '3',
}
-- must be set after mode!
- set_config_element ('alias_switch', alias_from_mode(config.mode))
+ set_config_elt ('alias_switch', alias_from_mode(config.mode))
-- now a particular case for config.ext_list and zip-related stuff
-- Note: removed texdoc_formats/zip_formats, gives simpler & generic code
if support_zipped then
- set_config_element('ext_list',
+ set_config_elt('ext_list',
'pdf,pdf.gz,pdf.bz2, html,html.gz,html.bz2, txt,txt.gz,txt.bz2,'..
'dvi,dvi.gz,dvi.bz2, ps,ps.gz,ps.bz2, ,gz,bz2')
- set_config_list {
+ set_config_ls {
unzip_gz = 'gzip -d -c ',
unzip_bz2 = 'bzip -d -c ',
rm_file = 'rm -f',
rm_dir = 'rmdir'
}
else
- set_config_element('ext_list', 'pdf, html, txt, dvi, ps, ')
+ set_config_elt('ext_list', 'pdf, html, txt, dvi, ps, ')
+ end
+end
+
+-- the default value of config.alias_switch depends on the mode as follows
+function alias_from_mode (mode) -- /!\ returns a string!
+ if (mode == 'view') or (mode == 'mixed') or (mode == 'list') then
+ return 'true'
+ else
+ return 'false'
end
+
end
+--------------------------------------------------------------------------------
+--------------- functions for viewing/displaying the results ---------------
+--------------------------------------------------------------------------------
--- functions for viewing/displaying the results
------------------------------------------------
+--------------------------------- viewing ----------------------------------
-- prepare for viewing: set viewer_replacement and viewer_ext
-- may uncompress if support_zipped is set (giving the complete filename on the
@@ -640,7 +773,7 @@ function how_to_view (filename)
-- files without extension are assumed to be text
viewext = string.match(filename,'.*%.(.*)$') or 'txt'
if not config['viewer_'..viewext] then
- err_print (": cannot determine type of file\n\t"
+ err_print ("cannot determine type of file\n\t"
..filename.."Assuming text. Set the `viewer_"..viewext..
"' variable in texdoc.cnf to avoid this.", "warning")
viewext = 'txt'
@@ -674,22 +807,7 @@ function try_viewing (view_command, viewer_replacement)
return view_result
end
--- compare two filenames with the following rule:
--- 1. extensions are ordered as in ext_list first,
--- 2. then filenames lexicograhpicaly.
-function file_order (a, b)
- local ext_a = string.match (a, '^.*%.(.*)$')
- local ext_b = string.match (b, '^.*%.(.*)$')
- ext_pos_a = config.ext_list_inv[ext_a] or (config.ext_list_max+1)
- ext_pos_b = config.ext_list_inv[ext_b] or (config.ext_list_max+1)
- if ext_pos_a < ext_pos_b then
- return true
- elseif ext_pos_a > ext_pos_b then
- return false
- else
- return (a < b)
- end
-end
+-------------------------------- displaying --------------------------------
-- display a table, sorted, numbered with given offset (0 by default),
-- with real path
@@ -697,11 +815,7 @@ function display_table (t, offset)
offset = offset or 0
table.sort(t, file_order)
for i, val in ipairs (t) do
- if config.interact_switch then
- print (i+offset, real_path(val))
- else
- print (real_path(val))
- end
+ print(string.format('%2d %s', i+offset, real_path(val)))
end
end
@@ -732,8 +846,9 @@ function print_menu (files, comp)
end
end
--- error handling
------------------
+--------------------------------------------------------------------------------
+----------------------- functions for error handling -----------------------
+--------------------------------------------------------------------------------
-- exit codes (probably make sense only with a single argument)
-- 0 OK
@@ -764,19 +879,18 @@ end
-- generic error display function (see the error_priority constant)
function err_print (msg, lvl)
- -- be careful: maybe config.noise_level is not set yet
- local noise_level = config.noise_level or 10000
- if err_priority[lvl] <= noise_level then
+ -- be careful: maybe config.verbosity_level is not set yet
+ local verbosity_level = config.verbosity_level or 2
+ if err_priority[lvl] <= verbosity_level then
io.stderr:write ("texdoc "..lvl..": "..msg.."\n")
end
end
+--------------------------------------------------------------------------------
+--------------------------- main code execution ----------------------------
+--------------------------------------------------------------------------------
--- END of function definitions: here starts the execution
---=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
-
--- initialisations
-------------------
+----------------------------- initialisations ------------------------------
-- initialize kpathsea
kpse.set_program_name(arg[-1], "texdoc")
@@ -791,8 +905,10 @@ setup_config_from_env ()
setup_config_from_files ()
setup_config_from_defaults ()
--- the main loop over the args
-------------------------------
+-- now that verbosity_level is known...
+show_config_files(function(s) err_print(s, 'debug1') end)
+
+------------------------ looping over the arguments ------------------------
-- initialising and saving a few values
exit_code = 0
diff --git a/Master/texmf/texdoc/texdoc.cnf b/Master/texmf/texdoc/texdoc.cnf
index b121e1e7318..a0ec73aae51 100644
--- a/Master/texmf/texdoc/texdoc.cnf
+++ b/Master/texmf/texdoc/texdoc.cnf
@@ -37,7 +37,7 @@
# interact_switch = true
# alias_switch = true # but false if mode is 'regex'
# ext_list = pdf, html, txt, ps , # note the empty string at end
-# noise_level = 3
+# verbosity_level = 3
### Aliases ###
@@ -51,8 +51,6 @@ alias latex = latex-doc-ptr
## various stuff
# a few useful general documents
-alias mathmode = Mathmode
-alias visualfaq = visualFAQ
alias symbols = symbols-a4
alias faq-en = newfaq
alias faq = newfaq
@@ -82,6 +80,7 @@ alias lshort-vi = lshort-vi # vietnamese
# *TeX engines reference manuals, man pages and related
+alias e-tex-ref = etex_man
alias etex-ref = etex_man
alias pdftex-ref = pdftex-a
alias xetex-ref = XeTeX-reference
@@ -92,6 +91,7 @@ alias pdftex-man = man1/pdftex
alias luatex-pkg = oberdiek/luatex.pdf
# by default, <engine> = <engine>-ref (duplicated: no alias cascading)
+alias e-tex = etex_man
alias etex = etex_man
alias pdftex = pdftex-a
alias xetex = XeTeX-reference
@@ -145,6 +145,7 @@ alias metapost = mpman
alias iso = isoman
alias pstricks = pstricks-doc
alias extramarks = fancyhdr
+alias fonttable = fonttable/fonttable
## a few easy patterns
@@ -454,4 +455,10 @@ alias vrbexin = vrbexin.sty
alias vruler = vruler.sty
alias wrapfig = wrapfig.sty
+# the next line has no effect when this file is installed as
+# TEXMFMAIN/texdoc/texdoc.cnf but is useful when it is installed as
+# TEXMFHOME/texdoc/texdoc-dist.cnf for the purpose of installing a newer
+# version of texdoc in one's home (eg, running texdoc from SVN)
+lastfile_switch = true
+
# vim: ts=8 noexpandtab: