From 325abc59c7257d8d7dc8807273dc6854d7f64b38 Mon Sep 17 00:00:00 2001 From: Peter Breitenlohner Date: Mon, 6 Aug 2012 13:38:57 +0000 Subject: Move some linked scripts from texmf/ to texmf-dist/ git-svn-id: svn://tug.org/texlive/trunk@27321 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf/doc/texdoc/News | 239 ----------- Master/texmf/doc/texdoc/texdoc.pdf | Bin 110319 -> 0 bytes Master/texmf/doc/texdoc/texdoc.tex | 837 ------------------------------------- 3 files changed, 1076 deletions(-) delete mode 100644 Master/texmf/doc/texdoc/News delete mode 100644 Master/texmf/doc/texdoc/texdoc.pdf delete mode 100644 Master/texmf/doc/texdoc/texdoc.tex (limited to 'Master/texmf/doc') diff --git a/Master/texmf/doc/texdoc/News b/Master/texmf/doc/texdoc/News deleted file mode 100644 index caad4f51959..00000000000 --- a/Master/texmf/doc/texdoc/News +++ /dev/null @@ -1,239 +0,0 @@ -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 -de.pdf -wins over .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/doc/texdoc/texdoc.pdf b/Master/texmf/doc/texdoc/texdoc.pdf deleted file mode 100644 index 9de6754f92c..00000000000 Binary files a/Master/texmf/doc/texdoc/texdoc.pdf and /dev/null differ diff --git a/Master/texmf/doc/texdoc/texdoc.tex b/Master/texmf/doc/texdoc/texdoc.tex deleted file mode 100644 index 817489f697b..00000000000 --- a/Master/texmf/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} -- cgit v1.2.3