summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/texdoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-06-06 22:25:01 +0000
committerKarl Berry <karl@freefriends.org>2018-06-06 22:25:01 +0000
commit67a3b03c3f11c14b811b04447baf2b464e157e98 (patch)
treef5f8050ce90286fcd75ee2161c1dad78116bf50d /Master/texmf-dist/doc/texdoc
parent0654b7aef1ec8948c0a7cc81fbaf9fc707782d44 (diff)
texdoc 3.0 from CTAN
git-svn-id: svn://tug.org/texlive/trunk@47946 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/texdoc')
-rw-r--r--Master/texmf-dist/doc/texdoc/News247
-rw-r--r--Master/texmf-dist/doc/texdoc/texdoc.pdfbin110319 -> 0 bytes
-rw-r--r--Master/texmf-dist/doc/texdoc/texdoc.tex837
3 files changed, 0 insertions, 1084 deletions
diff --git a/Master/texmf-dist/doc/texdoc/News b/Master/texmf-dist/doc/texdoc/News
deleted file mode 100644
index 31e4f9cb3a2..00000000000
--- a/Master/texmf-dist/doc/texdoc/News
+++ /dev/null
@@ -1,247 +0,0 @@
-$Id: NEWS 14 2017-05-19 21:22:31Z karl $
-(This file public domain.)
-
-Version 2.017 (TeX Live 2017)
-============================
-- Restore user's LC_CTYPE value if possible (with this year's luatex).
-- Generic system environment variables, such as BROWSER, accept
- a colon-separated list of programs.
-
-Version 0.85
-------------
-Compatibility with LuaTeX 0.74+ (Lua 5.2).
-
-Version 0.84 (TeX Live 2012)
-============================
-Fix -f output when TEXMFHOME contains a list of paths. Bug sort-of reported
-by Matthew Leingang, see http://tex.stackexchange.com/questions/42920/
-
-Version 0.83
-------------
-Minor adjustments in the scoring system.
-
-Version 0.82
-------------
-Fixes to the default viewer/destkop environment detection:
-- try gvfs-open with Gnome
-- always try xdg-open first (usually more up-to-date)
-Thanks to Axel E. Retif for informing me that newer versions of Ubuntu don't
-ship gnome-open by default any more.
-
-Version 0.81 (TeX Live 2011)
-============================
-
-Allow configuration files to be found in all TEXMF trees.
-The default one should now be installed in TEXMFDIST (in upstream TeX Live) or
-in a tree search after TEXMFLOCAL (in downstream distros).
-
-Delay default viewer detection, see:
-http://tug.org/pipermail/tex-live/2011-May/029150.html
-
-Drop long-deprecated things:
-- --search (-> --showall), --verbosity-level and old syntax of -v
-- alias_switch, -a, -A, --alias, --noalias
-- 'regex' mode,
-
-Various internal cleanups and rearrangements.
-
-Version 0.80
-============
-
-New 'lang' configuration option (defaults on system locale): now <name>-de.pdf
-wins over <name>.pdf if German is preferred. Patch kindly provided by Philipp
-Stephani. Also works with aliases (eg koma-de = scrguide wins over koma =
-scrguien).
-
-Document the previously undocumented options from 0.72-tl2010.
-
-Accept htm as a valid extension, synonym for html. Emit less warnings about
-viewers.
-
-Version 0.72 as in TeX Live 2010
---------------------------------
-
-New (undocumented) settings (bad)basenme_list, parallel to (bad)ext_list.
-
-New (undocumented) setting item suffix_list for known documentation suffixes,
-previously hardcoded.
-
-New (undocumented) option --just-view for use by front-end programs.
-
-Version 0.72
-------------
-
-Fix stupid bug introduced in 0.70: texdoc would crash if called without
-arguments. (Reported by Maxime Chupin.)
-
-Version 0.71
-------------
-
-Fix bug introduced in 0.70: some results were duplicated on windows. (Reported
-by Uwe Siart.)
-
-Version 0.70
-============
-
-Use information from the TeX Live package database (some of it coming from the
-CTAN catalogue) to improve search results. Display some of this information.
-
-Show the current settings in --help message.
-
-Misc. internal changes & fixes.
-
-Deprecate -a, --alias, -A, --noalias and alias_switch.
-
-Version 0.66
-------------
-
-Turn the -v=N, --verbosity=N command-line option into a pair of related options
--v, --verbose and -q, --quiet (more standard, Karl's suggestion). Also remove
-uselessly verbose debug items so --debug is usable again.
-
-Rework help text (Karl's suggestion).
-
-Issue a warning about DISPLAY not being set on generic Unix before trying to
-start a viewer.
-
-Small internal clean-ups.
-
-Version 0.65
-------------
-
-Make it easier to change the list of configuration files used (eg for
-downstream distributions).
-
-Version 0.64
-------------
-
-Fix a crash when DISPLAY is unset on Unix by querying xprop more carefully.
-(Bug introduced in 0.61.)
-
-Version 0.63
-------------
-
-Fix a bug on windows which prevented from viewing sty files.
-
-Version 0.62
-------------
-
-Support for zipped documentation is now an official option.
-Please read the warnings before using it!
-
-Version 0.61
-------------
-
-Detect desktop environments (KDE4, KDE, GNOME, XFCE) for viewer selection.
-
-Version 0.60
-============
-
-Changed the search/alias/score logic. See section 2 of the manual for details,
-but here is a primer:
-- alias now /adds/ patterns to be search, it is no more a substitution
-- new scoring system, partially configurable, with improved heuristics
-
-The beginning of the manual has been completely rewritten.
-
-Bugs have been fixed as usual, and probably some others introduced...
-
-Version 0.50
-============
-
-- New option for machine-readable output.
-- Bugfixes (esp. for zipped file support (Unix only)).
-- Hopefully more sensible default viewer selection.
-
-Version 0.49
-------------
-
-Major code rewrite. No big user-visible change, except a few bugs fixed and new
-debugging levels.
-
-Version 0.47 (TeX Live 2009)
-----------------------------
-
-Adapt for man pages named *.man1.pdf instead of *.pdf.
-(Temporary hack, done better since version 0.60.)
-
-Warning: zip support probably broken!
-
-Version 0.46
-------------
-
-Avoid using lfs.currentdir() and lfs.chdir() which are broken on Solaris 10
-in LuaTeX 0.40
-
-Version 0.45
-------------
-
-Fix possible line ending problems on windows with certain versions of LuaTeX
-
-Version 0.44
-------------
-
-- fixing viewer problems on Windows
-- expanding the list of default viewers on generic Unix
-
-
-Version 0.43
-------------
-
-Improve support for zipped documentation and comments about it in the default
-configuration file. (Thank Norbert Preining for his help.)
-
-Various fixes, aliases updates as usual.
-
-Version 0.42
-------------
-
-Improvements to default txt viewer on Windows (thanks to Phil Taylor).
-
-New debugging levels; new names for debugging options.
-
-New configuration file allowing to run the development version more easily.
-
-Changes to the way files are displayed. Results are numbered even when -I is
-used.
-
-Documentation update. Alias additions and fixes as usual. Various bugfixes.
-
-License switched to GPL.
-
-Version 0.4 (TeX Live 2008)
-===========================
-
-Use our own configuration files, not texmf.cnf. Rework the way viewers are
-handled, and add a few configuration options.
-
-Add an 'alias' feature. Filter results in a more restrictive way. Add new search
-modes 'mixed' and 'regex'. Turn result lists into menus.
-
-Add a user manual in pdf.
-
-Development passed from Frank Küster to Manuel Pégourié-Gonnard.
-
-Version 0.3
------------
-
-Various changes including:
-- added changelog
-- better OS detection for default viewer settings
-- removed some debugging code
-- -s now works in dirs without ls-R, too
-
-Version 0.2
------------
-
-Various changes including:
-- implemented reading of configuration from texmf.cnf
-- fixed "-s" option
-
-Version 0.1
------------
-Initial public release of the texlua version by Frank Küster.
-
-Earlier versions
-----------------
-Shell script by Thomas Esser maintained as part of teTeX.
diff --git a/Master/texmf-dist/doc/texdoc/texdoc.pdf b/Master/texmf-dist/doc/texdoc/texdoc.pdf
deleted file mode 100644
index 9de6754f92c..00000000000
--- a/Master/texmf-dist/doc/texdoc/texdoc.pdf
+++ /dev/null
Binary files differ
diff --git a/Master/texmf-dist/doc/texdoc/texdoc.tex b/Master/texmf-dist/doc/texdoc/texdoc.tex
deleted file mode 100644
index 817489f697b..00000000000
--- a/Master/texmf-dist/doc/texdoc/texdoc.tex
+++ /dev/null
@@ -1,837 +0,0 @@
-% this is texdoc's user manual
-% written by Manuel Pégourié-Gonnard in 2008, 2010
-% distributed under the terms of GPL v3 or later
-
-%!TEX encoding=utf-8
-%!TEX program=xelatex
-
-\setlength\overfullrule{5pt}
-
-\documentclass[a4paper, oneside]{scrartcl}
-\usepackage{fontspec}
-\usepackage{xunicode}
-
-\defaultfontfeatures{Ligatures=TeX}
-\setmainfont{DejaVu Serif}
-\setsansfont{DejaVu Sans}
-\setmonofont{DejaVu Sans Mono}
-\renewcommand\familydefault{\sfdefault} \normalfont
-\newcommand\mylangle{$\langle$}
-\newcommand\myrangle{$\rangle$}
-
-\usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle}
-
-\usepackage[sf, bf]{titlesec}
-\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
-\titleformat{\subsubsection}[runin]{\itshape}{%
- \makebox[0pt][r]{\thetitle\kern1pc}}{%
- 0pt}{}[\maybedot\space --- \kern0pt]
-\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt}
-
-\usepackage{enumitem}
-\newlength\lssep \setlength\lssep{\smallskipamount}
-\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}
-
-\usepackage[british]{babel}
-\usepackage[bookmarks=true]{hyperref}
-\usepackage{bookmark}
-\hypersetup{%
- bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
- pdftitle=texdoc: find and view documentation in TeX Live,
- 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}
-\newcommand\tex{\TeX\xspace}
-\newcommand\latex{\LaTeX\xspace}
-
-\setlength\parindent{\baselineskip}
-
-\lastlinefit=500 % e-TeX powered
-
-\definecolor{links}{named}{violet}
-\definecolor{special}{rgb}{0,0.5,0}
-\definecolor{code}{rgb}{0,0,0.6}
-\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
-
-\newcommand\cofont{% % code
- \color{code}\normalfont\ttfamily}
-\newcommand\meta[1]{% % meta elements
- {\normalfont\color{special}\mylangle\textit{#1}\myrangle}}
-
-% take care of non-breakable spaces
-\catcode`\ 10\relax
-
-\fvset{%
- formatcom=\cofont,
- defineactive=\makeallfancy,
- codes=\fancyactives,
- }
-\newcommand\fancyactives{%
- \catcode`\«\active}
-\newcommand\makeallfancy{%
- \makefancyog}
-{\catcode`\«\active
-\global\def\makefancyog{%
- \def«##1»{\meta{##1}}}
-}
-
-\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}
-
-\makeatletter
-\newenvironment{htcode}{% % code en hors-texte
- \SaveVerbatim[samepage, gobble=2]{verbmat}%
- }{%
- \endSaveVerbatim
- \par\medskip\noindent\hspace*{\parindent}%
- \BUseVerbatim{verbmat}%
- \par\medskip\@endpetrue}
-\makeatother
-\DefineShortVerb{\©}
-
-\setkomafont{title}{}
-\setkomafont{subtitle}{\Large}
-\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
-
-\newcommand\tdml{\href{mailto:texdoc@tug.org}{texdoc mailing list}\xspace}
-
-\title{Texdoc}
-\subtitle{Find \& view documentation in \texlive\\
- \href{http://tug.org/texdoc/}{http://tug.org/texdoc/}\\
- \mailto{texdoc@tug.org}}
-\author{Manuel Pégourié-Gonnard\\
- v0.84 2012-06-01}
-\date{}
-
-\begin{document}
-\VerbatimFootnotes
-
-\maketitle
-
-\section{Quick guide (2 pages only)}
-
-\subsection{Basics}
-
-Open a command line\footnote{On Windows, press Win-R and type ©cmd©. On Mac
- OS X, use the ``terminal'' application. If you are using another flavour of
- Unix, you probably know what to do.} and type ©texdoc «name»©: the
-documentation of the ©«name»© package will pop up. Of course, replace ©«name»©
-with the actual name of the package. To look up the documentation of more
-than one package at once, just use many ©«name»©s as arguments.
-
-\subsection{Modes}\label{ss-modes}
-
-Texdoc has different modes that determine how results will be handled. In the
-default, ``view'' mode, it opens the first (supposedly the best) result in a
-viewer. It is rather handy when you know what you want to read, and want to
-access it quickly. On the other hand, there may be other relevant documents
-for the given ©«name»©, which are ignored in view mode.
-
-The so-called ``list mode'' makes texdoc list all relevant documentation and
-ask you which one you want to view. It is useful when there a other
-interesting sources of information besides the package's main documentation.
-
-There is also a ``mixed'' mode, intended to combine the best of view mode and
-list mode: if there is only one relevant result, then texdoc opens it in a
-viewer, else it offers you a menu.
-
-By default, texdoc hides the results it considers less relevant (unless it
-finds no relevant result at all). In ``showall'' mode, it always shows all
-results.
-
-To select the mode on the command-line, use ©texdoc «option» «name»© with one
-of the following options: ©-w© or ©--view© for view mode, ©-m© or ©--mixed©
-for mixed mode, ©-l© or ©--list© for list mode, ©-s© or ©--showall© for
-showall mode.
-
-If you always (or mostly) use the same mode, you don't want to keep typing the
-same option. The next section describes how to customize texdoc using
-configurations files.
-
-\subsection{Configuration files}\label{ss-quick-file}
-
-Use ©texdoc --files© to know where to put your personal configuration file;
-you'll need to create this file (an possibly some directories) the first time.
-(If you want to know the full list of possible configuration files,
-see~\ref{ss-prec}.)
-
-In order to select you favorite mode, just insert a line ©mode = «yourmode»©
-in this file, where ©«yourmode»© is one of ©view©, ©mixed©, ©list© or
-©showall©. To set your favorite language, use ©lang = «2-letter code»©, though
-it is usually detected automatically.
-
-The configuration file can be used to tweak texdoc in many ways, the most
-useful of which is probably the selection of the viewers for various types of
-documents, explained in the next section.
-
-\subsection{Viewers}\label{ss-viewer}
-
-Texdoc's mechanism for choosing a viewer varies according to your platform.
-On Windows, OS X, or Unix with KDE, Gnome or XFCE, it uses your file
-associations like when you double-click files in the Explorer, the Finder or
-your default file manager (except for the text viewer, which is always a
-pager). Otherwise, it tries to find a viewer in the path from a list of
-``known'' viewers.
-
-You may want to select a different viewer for some kind of file. This is
-achieved by setting the various ©viewer_«ext»© configuration options, where
-©«ext»© is the extension corresponding to the file type. For example, if you
-want to set xpdf as your default PDF viewer, and run it in the background,
-insert the line ©viewer_pdf = xpdf %s &© in your configuration file. Here,
-©%s© stands for the name of the file to view.
-
-\subsection{You can stop reading now}
-
-The next part explains texdoc mechanisms for finding the best results and how
-to cutomize them. The default configuration file tries hard to set appropriate
-values so that you normally don't need to fiddle with that, but you may be
-curious or have special needs.
-
-The final part is a full reference including a few points omitted in the
-present and next part.
-
-\clearpage
-
-\section{File search, aliases, score}
-
-\subsection{An overview of how texdoc works}
-
-When you type ©texdoc «keyword»©, texdoc first makes a list of files, from two
-sources:
-\begin{enumerate}
- \item In the trees containing documentation (given by the
- \href{http://www.tug.org/kpathsea/} {kpathsea} variable ©TEXDOCS©), it
- selects all files containing ©«keyword»© in their name (including the
- directory name);
- \item In the \texlive Database, it looks for packages named
- ©«keyword»© or containing a file ©«keyword».«ext»© where ©«ext»© may me
- ©sty© or ©cls©, and selects all the documentation files from this package.
-\end{enumerate}
-Files are filtered by extension: only files with known extensions may be
-selected.
-
-The selected files are then score according to some simple heuristics. For
-example, a file named ©«keyword».pdf©, is good, ©«keyword»-«lang».pdf© will
-score higher if your favorite language ©«lang»© is detected or configured,
-©«keyword»-doc© will be preferred over ©«keyword»whatever©, files in a
-directory named exactly ©«keyword»© get a bonus, etc.
-
-Score may also be adjusted base on file extensions or known names (or
-subwords): for example, by default, ©Makefile©s get a very bad score since
-they are almost never documentation.\footnote{They often end up in the doc
- tree, since the source of documentation is often in the same directory as
- the documentation itself in \texlive. Other source files are discriminated
- by extension.}
-
-Finally, depending on the mode, the file with the highest score is opened in a
-viewer, or the list of results is shown. Usually, only results with a positive
-score are displayed, except in showall mode. Results with very bad scores
-(-100 and below) are never displayed.
-
-\medskip
-
-This model for searching and scoring is quite efficient, but is unfortunately
-not perfect: texdoc may sometimes need a hint, either to find a relevant file
-or, more likely, to recognize which of the files found is the most relevant.
-
-For example, assume you are looking for the documentation of the shortvrb
-\latex package. Texdoc will find ©shortvrb.sty© in the ©latex© \texlive
-package, but since this package contains a lot of documentation files, none of
-which contains the string ©shortverb©, it will sort them basically at random.
-
-Here comes the notion of \emph{alias}: in the default configuration file,
-©shortvrb© is aliased to ©base/doc©, so that when you type ©texdoc shortvrb©,
-texdoc knows it has to look primarily for ©base/doc©. Note that texdoc will
-also look for the original name, and that a name can be aliased to more than
-one new name.
-
-\medskip
-
-We will soon see how you can configure this, but let's start with a few
-definitions about how a file can match keyword (all matching is
-case-insensitive):
-\begin{enumerate}
- \item The keyword is a substring of the file name.
- \item The keyword is a ``subword'' of the file name; words are defined as
- sequences of alphanumeric characters delimited by punctuation characters
- (there is no space in file names in \texlive) and a subword is a
- substring both ends of which are a word boundary.
- \item The keyword matches ``exactly'' the file name: that is, the file
- name is the keyword, possibly plus an extension.
-\end{enumerate}
-
-\subsection{Alias directives}\label{ss-alias}
-
-\begin{htcode}
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
-\end{htcode}
-
-You can define your own aliases in texdoc's configuration files
-(see~\ref{ss-quick-file} or \ref{ss-prec}). For example,
-insert\footnote{Actually, you don't need to do this, the default configuration
- file already includes this directive.}
-\begin{htcode}
- alias shortvrb = base/doc
-\end{htcode}
-in order to alias ©shortvrb© to ©base/doc©. Precisely, it means that files in
-the doc trees matching exactly ©base/doc© will be added to the result list
-when you look for ©shortvrb©, and get a score of 10 (default score for alias
-results). This is greater than the results of heuristic scoring: it means that
-results found via aliases will always rank before results associated to the
-original keyword.
-
-If you want the results associated to a particular alias to have a custom
-score instead of the default 10, you can use the optional argument to the
-alias directive. This can be useful if you associate many aliases to
-a keyword and want one of them to show up first.
-
-Additionally, starting from with v0.80, aliases for ©«keyword»-«lang»©, where
-©«lang»© is your preferred language's 2-letter code (as detected or
-configured, see the ©lang© option) are also used for ©«keyword»© and get a
-©+1© score upgrade.
-
-You can have a look at the configuration file provided (the last shown by
-©texdoc -f©) for examples. If you feel one of the aliases you defined locally
-should be added to the default configuration, please share it on the \tdml.
-
-Aliases are additive: if you define your own aliases for a keyword in your
-configuration file, and there are also aliases for the same keyword in the
-default configuration, they will add up. To prevent the default aliases
-from begin applied for a particular keyword, include ©stopalias «keyword»© in
-your personal configuration file. It will preserve the aliases defined before
-this directive (if any) but prevent all further aliasing on this keyword.
-
-\textit{Remark.} Aliasing is case-insensitive, and doesn't cascade:
-only aliases associated to the original keyword are used.
-
-\textbf{Warning.} Results found from aliases always have the score defined by
-the ©alias© directive (10 by default), regardless of the adjustments described
-in the next subsections.
-
-\subsection{Score directives}\label{ss-score}
-
-\begin{htcode}
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
-\end{htcode}
-
-It is possible to adjust the score of results containing some pattern as a
-subword, either globally (for the result of all searches) or only when
-searching with a particular keyword. This is done in a configuration file
-(\ref{ss-quick-file} or \ref{ss-prec}) using the ©adjustscore© directive. Here
-are a few examples from the default configuration file.
-
-\begin{htcode}
- adjscore /Makefile = -1000
- adjscore /tex-virtual-academy-pl/ = -50
- adjscore(tex) texdoc = -10
-\end{htcode}
-
-All files named ©Makefile© (and also files named ©Makefile-foo© if there are
-any) are ``killed'' : by adjusting their score with such a large negative
-value, their final score will most probably be less than -100, so they will
-never be displayed. Files from the ©tex-virtual-academy-pl© directory, on the
-other hand, are not killed but just get a malus, since they are a common
-source of ``fake'' matches which hide better results (even for the lucky ones
-who can read polish).
-
-The third directive gives a malus for results containing ©texdoc© only if the
-search keyword is ©tex©. Otherwise, such results would get a high score
-because the heuristic scoring would think ©texdoc© is the name of \tex's
-documentation. The value -10 is enough to ensure that those results will have
-a negative score, so wil not be displayed unless ``showall'' mode is active.
-
-\textbf{Warning}: Values of scores (like the default score for aliases, the
-range of heuristic scoring, etc.) may change in a future version of texdoc.
-So, don't be surprised if you need to adapt your scoring directives after a
-future update of texdoc. This warning will hopefully disappear at some point.
-
-\subsection{File extensions and names}\label{ss-ext}
-
-The allowed file extensions are defined by the configuration item ©ext_list©
-(default: pdf, html, htm, txt, ps, dvi, no extension). You can configure it
-with a line ©ext_list = «your, list»© in a configuration file. Be aware
-that it will completely override the default list, not add to it. An empty
-string in the list means files without extension (no dot in the name), while a
-star means any extension.
-
-For scoring purposes, there is also a ©badext_list© parameter: files whose
-extension is ``bad'' according to this list will get a lesser score (currently
-0).
-
-Unfortunately, sometimes what follows a dot in a file name is not a ``real''
-extension. This often happens with readme files, for example ©readme.fr© or
-©readme.texlive©. So, in addition to his list of known extensions, texdoc has
-a list of known basenames, by default just ©readme©.
-
-The corresponding settings are ©basename_list© and ©badbasename_list©; both
-are similar to ©ext_list© and ©badext_list©. So, a file will be selected if
-either its extension or its base name is known, and get a lesser score if
-either is known to be ``bad.''
-
-\subsection{Variants}\label{ss-variants}
-
-The documentation for a given package is often found in a file named like
-©«package»-doc©. To handle this properlr, texdoc gives a special score files
-named ©«package»«suffix»© where ©«suffix»© is one element of the list given by
-the configuration setting ©suffix_list©.
-
-To customise this list, add a line with ©suffix_list = «your, list»© in a
-configuration files. Be warned, it will replace the default list, no expand
-it. You'll find the default list in the shipped configuration file; feel free
-to suggest additions on the \tdml (with a real-life example).
-
-\clearpage
-
-\section{Full reference}
-
-\subsection{Precedence of configuration sources}\label{ss-prec}
-
-Values for a particular setting can come from several sources. The sources are
-treated in the following order and the 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 (see below).
- \item Hard-coded defaults that may depend on the current machine.
-\end{enumerate}
-
-The configuration files are found in the directories ©TEXMF/texdoc©, where
-©TEXMF© is the kpathsea variable, in the order given by this variable. Inside
-each directory, three files are recognized, in this order:
-\begin{enumerate}
- \item ©texdoc-«platform».cnf© where ©«platform»© is the name of the current
- platform (defined as the name of the directories where the \texlive
- binaries are located, for example ©x86-64-linux©). This may be useful when
- an installation is shared across machines with different architectures
- needing different settings, for example for viewers. Their use is not
- recommended in any other situation.
- \item ©texdoc.cnf© is the recommended file for normal use.
- \item ©texdoc-dist.cnf© is useful for installing a newer version of texdoc
- (including its default configuration file) in your home while retaining
- the use of the previous file for your personal setting; see
- \href{http://tug.org/texdoc/dev/}{the web page} for instructions on
- running the development version.
-\end{enumerate}
-
-\subsection{Command-line options}\label{ss-cl}
-
-All command-line options (except the first four below) correspond to
-configuration item that can be set in the configuration files: we refer
-the reader to the corresponding section for the meaning of this configuration
-item.
-
-\begin{cmdsubsub}{-h, --help}{cl-h}
- -h, --help
-\end{cmdsubsub}
-
-Show a quick help message (namely a list of command-line options) and exit
-successfully.
-
-\begin{cmdsubsub}{-V, --version}{cl-V}
- -V, --version
-\end{cmdsubsub}
-
-Show the current version of the program and exit successfully.
-
-\begin{cmdsubsub}{-f, --files}{cl-f}
- -f, --files
-\end{cmdsubsub}
-
-Show the list of configuration files for the current installation and
-platform, with their status (active, not found, or disabled
-(see~\ref{cf-lastfile_switch})) and exit successfully.
-
-\begin{cmdsubsub}{--just-view}{cl-just-view}
- --just-view «file»
-\end{cmdsubsub}
-
-Open «file» in the usual viewer. The file should be given with full path,
-absolutely no searching is done. This option is not really meant for users,
-but rather intended to be used from another program, like a GUI front-end to
-texdoc.
-
-\begin{cmdsubsub}{-w, -l, -m, -s, --view, --list, --mixed, --showall}{cl-mode}
- -w, --view, -l, --list, -m, --mixed, -s, --showall
-\end{cmdsubsub}
-
-Set ©mode© to the given value, see~\ref{cf-mode}.
-
-\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
- -i, --interact, -I, --nointeract
-\end{cmdsubsub}
-
-Set ©interact_switch© to true (resp. false), see~\ref{cf-interact_switch}.
-
-\begin{cmdsubsub}{-M, --machine}{cl-M}
- -M, --machine
-\end{cmdsubsub}
-
-Set ©machine_switch© to true, see~\ref{cf-machine_switch}.
-
-\begin{cmdsubsub}{-q, --quiet}{cl-q}
- -q, --quiet
-\end{cmdsubsub}
-
-Set ©verbosity_level© to minimum, see~\ref{cf-verbosity_level}.
-
-\begin{cmdsubsub}{-v, --verbose}{cl-v}
- -v, --verbose
-\end{cmdsubsub}
-
-Set ©verbosity_level© to maximum, see~\ref{cf-verbosity_level}.
-
-\begin{cmdsubsub}{-d, --debug}{cl-d}
- -d, -d=«list», --debug, --debug=«list»
-\end{cmdsubsub}
-
-Set ©debug_list©, see~\ref{cf-debug_list}. If no list is given, activates all
-available debug items.
-
-\subsection{Environment variables}\label{ss-envvar}
-
-They all correspond to some ©viewer_«ext»© setting, and the reader is referred
-to~\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}{*4l}
- New name & Old name 1 & Old name 2 & Config. item \\
- ©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}
-
-Also, on Unix systems, locale-related variables such as ©LANG© and ©LC_ALL©
-are used for the default value of ©lang©.
-
-\subsection{Configuration items}\label{ss-conf}
-
-\subsubsection{Structure of configuration files}\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}
- «configuration item» = «value»
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
- stopalias «original keyword»
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
-\end{htcode}
-
-We will concentrate on the ©«configuration item»© part here, since other
-directives have already been presented (\ref{ss-alias} and \ref{ss-score}).
-
-In the above, ©«value»© never needs to be quoted: quotes would be interpreted
-as part of the value, not as quotation marks (this also holds for the other
-directives).
-
-Lines which do not obey these rules raise a warning, as well as unrecognised
-values of ©«configuration item»©. The ©«value»© can be an arbitrary string,
-except when the name of the ©«configuration item»© 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©
- (lowercase).
- \item ©_level©, then ©«value»© is an integer.
-\end{enumerate}
-In these cases, an improper ©«value»© will raise a warning too.
-
-\begin{cmdsubsub}{mode}{cf-mode}
- mode = «view, list, mixed, showall»
-\end{cmdsubsub}
-Set the mode to the given value. Default is ©view©. The various modes
-have been presented in~\ref{ss-modes}.
-
-\begin{cmdsubsub}{interact}{cf-interact_switch}
- interact_switch = «true, false»
-\end{cmdsubsub}
-
-Turn on or off interaction. Default is on. Turning interaction off prevents
-texdoc from asking you to choose a file to view when there are multiple
-choices, so it just prints the list of files found.
-
-\begin{cmdsubsub}{suffix_list}{cf-suffix_list}
- suffix_list = «list»
-\end{cmdsubsub}
-
-Set the list of known suffixes to ©«list»© (see~\ref{ss-variants}). Default is
-the empty list, but see the shipped configuration file for more.
-
-\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, htm, txt, dvi, ps,
-\end{htcode}
-This list is used to filter and sort the results that have the same
-score(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»©, independently of the
-current value of ©ext_list© and ©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 = pdf, html, htm, 1, 5, txt, dvi, ps,
- viewer_1 = man
- viewer_5 = man
-\end{htcode}
-
-As a special case, if the extension is ©sty©, then the ©txt© viewer is used;
-similarly, if it is ©htm© the ©html© viewer is used. Otherwise, the ©txt©
-viewer is used and a warning is issued.
-
-\begin{cmdsubsub}{badext_list}{cf-badext_list}
- badext_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``bad'' extensions to ©«list»©. Default is ``©txt,©''. Files
-with those extensions get a malus of ©1© on their heurisitc score if it was
-previously positive.
-
-\begin{cmdsubsub}{basename_list}{cf-basename_list}
- basename_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``known'' base names to ©«list»©. Default is ``©readme©''.
-Files with those base names are selected regardless of their extension. If the
-extension is unknown, the text viewer will be used to view the file.
-
-\begin{cmdsubsub}{badbasename_list}{cf-badbasename_list}
- badbasename_list = «list»
-\end{cmdsubsub}
-
-Set the list of ``bad'' base names to ©«list»©. Default is ``©readme©''. Files
-with those names get a malus of ©1© on their heurisitc score if it was
-previously positive.
-
-\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 no ©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}{lang}{cf-lang}
- lang = «2-letter code»
-\end{cmdsubsub}
-
-Set you preferred language. Defaults to your system's locale.
-
-\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
- verbosity_level = «n»
-\end{cmdsubsub}
-
-Set the verbosity level to ©«n»© (default: 2). At level~3, errors, warnings and
-informational messages will be printed on stderr; 2 means only errors and
-warnings, 1 only errors and 0 nothing except internal errors (obviously not
-recommended).
-
-\begin{cmdsubsub}{debug_list}{cf-debug_list}
- debug_list = «list»
-\end{cmdsubsub}
-
-Set the list of activated debug items (default: none; if the command-line
-option is used without arguments, the list defaults to all known debug items).
-Implies ©--verbose©. Debug information is printed on standard error.
-
-\begin{cmdsubsub}{max_line}{cf-max_lines}
- max_lines = «number»
-\end{cmdsubsub}
-
-Set the maximum number of results to be printed without confirmation in list,
-mixed or showall mode (default: 20). This setting has no effect if interaction
-is disabled.
-
-\begin{cmdsubsub}{machine_switch}{cf-machine_switch}
- machine_switch = «true, false»
-\end{cmdsubsub}
-
-Turn on or off machine-readable output (default: off). With this option
-active, the value of ©interact_switch© is forced to ©false©, and each line of
-output is
-\begin{htcode}
- «argument»\t«score»\t«filename»
-\end{htcode}
-where ©«argument»© is the name of the argument to which the results correspond
-(mainly useful if there were many arguments), ©\t© is the tab (ascii 9)
-character, and the other entries are pretty self-explanatory. Nothing else is
-printed on stdout, except if a internal error occurs (in which case exit code
-will be 1). In the future, more tab-separated fields may be added at the end
-of the line, but the first 3 fields will remain unchanged.
-
-Currently, there are two additional fields: a two-letter language code, and an
-unstructured description, both taken from the CTAN catalogue (via the \texlive
-database). These fields may be empty and they are not guaranteed to keep the
-same meaning in future versions of texdoc.
-
-\begin{cmdsubsub}{zipext_list}{cf-zipext_list}
- zipext_list = «list»
-\end{cmdsubsub}
-
-List of supported extensions for zipped files (default: empty). Allows
-compressed files with names like ©foobar.«zip»©, with ©«zip»© in the given
-©«list»©, to be found and unzipped before the viewer is started (the
-temporary file will be destroyed right after).
-
-\textbf{Warning.} Support for zipped documentation is not meant to work on
-windows, a Unix shell is assumed! If you add anything to this list, please
-make sure that you also set a corresponding ©unzip=«ext»© value for each
-©«ext»© in the list. Also make sure you are using blocking (i.e. not returning
-immediately) viewers.
-
-\textit{Remark.} \texlive doesn't ship compressed documentation files, so
-this option is mainly useful with re-packaged version of \texlive that do,
-for example in Linux distributions.
-
-\begin{cmdsubsub}{unzip_*}{cf-unzip_star}
- unzip_«zipext» = «command»
-\end{cmdsubsub}
-
-The unzipping command for compressed files with extension ©«zipext»© (default:
-none). Define one for each item in ©zipext_list©. The command must print
-the result on stdout, like ©gzip -d -c© does.
-
-\begin{cmdsubsub}{rm_file, rm_dir}{cf-rm_star}
- rm_file = «command»
- rm_dir = «command»
-\end{cmdsubsub}
-
-Commands for removing files (resp. directories) on your system (defaults:
-©rm -f© and ©rmdir©). Only useful for zipped documents (see ©zipext_list©).
-
-\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch}
- lastfile_switch = «true, false»
-\end{cmdsubsub}
-
-If set to true, prevents texdoc from reading any other configuration file
-after this one (they will be reported as ``disabled'' by ©texdoc -f©). Mainly
-useful for installing a newer version of texdoc in your home and preventing
-the default configuration file from older versions to be used (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 codes are:
-\begin{enumerate}[start=0]
- \item Success.
- \item Internal error.
- \item Usage error.
-\end{enumerate}
-
-\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\bfseries
- Happy \tex{}ing!
-\end{center}
-
-\end{document}