diff options
-rw-r--r-- | Master/texmf-dist/texdoc/texdoc.cnf | 6 | ||||
-rw-r--r-- | Master/texmf/doc/man/man1/texdoc.1 | 37 | ||||
-rw-r--r-- | Master/texmf/doc/man/man1/texdoc.man1.pdf | bin | 5359 -> 5976 bytes | |||
-rw-r--r-- | Master/texmf/doc/texdoc/News | 16 | ||||
-rw-r--r-- | Master/texmf/doc/texdoc/texdoc.pdf | bin | 170889 -> 110315 bytes | |||
-rw-r--r-- | Master/texmf/doc/texdoc/texdoc.tex | 703 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/alias.tlu | 31 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/config.tlu | 218 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/constants.tlu | 70 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/functions.tlu | 48 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/main.tlu | 93 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/score.tlu | 40 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/search.tlu | 47 | ||||
-rwxr-xr-x | Master/texmf/scripts/texdoc/texdoc.tlu | 95 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/texdoclib.tlu | 90 | ||||
-rw-r--r-- | Master/texmf/scripts/texdoc/view.tlu | 32 |
16 files changed, 728 insertions, 798 deletions
diff --git a/Master/texmf-dist/texdoc/texdoc.cnf b/Master/texmf-dist/texdoc/texdoc.cnf index 5c3feb95eca..f4f33462b04 100644 --- a/Master/texmf-dist/texdoc/texdoc.cnf +++ b/Master/texmf-dist/texdoc/texdoc.cnf @@ -204,7 +204,7 @@ alias latex = latex-doc-ptr adjscore(lshort) /lshort-english/ = +0.5 # original alias lshort-de = l2kurz # german alias lshort-pl = lshort-polish/lshort2e # polish -alias lshort-pt = ptlshort # portuguese +alias lshort-pt = pt-lshort # portuguese alias lshort-sk = slshorte # slovak alias lshort-es = lshort-spanish/lshort # spanish @@ -360,7 +360,6 @@ alias mychemistry-de = mychemistry_de ## a few easy patterns # egrep 'manual\.pdf\>' -alias t-angles = t-manual alias tree-dvips = tree-manual # egrep 'user\.pdf\>' @@ -369,13 +368,10 @@ alias cweb-latex = cweb-user # egrep 'doc\.pdf\>' alias barcode = eandoc.pdf alias enctex-cz = encdoc -alias german = gerdoc alias ngerman = gerdoc alias jurabib-de = jbgerdoc alias ofs-cz = ofsdoc alias ofs = ofsdoc-e -alias pst-eucl-fr = pst-eucl/euclide -alias pst-eucl = pst-eucl/euclide_english alias pst-geo = pst-map3d-doc ## aliases basically borrowed from texdoctk.dat with some adaptations diff --git a/Master/texmf/doc/man/man1/texdoc.1 b/Master/texmf/doc/man/man1/texdoc.1 index 778e624eb9f..23715f0249a 100644 --- a/Master/texmf/doc/man/man1/texdoc.1 +++ b/Master/texmf/doc/man/man1/texdoc.1 @@ -1,13 +1,17 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.39.4. -.TH TEXDOC "1" "June 2011" "texdoc 0.80" "User Commands" +.TH TEXDOC "1" "June 2011" "texdoc 0.81" "User Commands" .SH NAME texdoc \- find & view documentation in TeX Live .SH SYNOPSIS .B texdoc -[\fIOPTION\fR]... [\fINAME\fR]... +[\fIOPTION\fR]... \fINAME\fR... +.br +.B texdoc +\fIACTION\fR .SH DESCRIPTION Try to find appropriate TeX documentation for the specified NAME(s). -With no NAME, print information about texdoc (\fB\-\-help\fR, \fB\-\-version\fR, \fB\-\-files\fR). +Alternatively, perform the given ACTION and exit. +.SS "Actions:" .TP \fB\-h\fR, \fB\-\-help\fR Print this help message. @@ -18,6 +22,10 @@ Print the version number. \fB\-f\fR, \fB\-\-files\fR Print the list of configuration files used. .TP +\fB\-\-just\-view\fR file +Display file, given with full path (no searching). +.SH OPTIONS +.TP \fB\-w\fR, \fB\-\-view\fR Use view mode: start a viewer. (default) .TP @@ -46,16 +54,27 @@ Suppress warnings and most error messages. Print additional information (eg, viewer command). .TP \fB\-d\fR, \fB\-\-debug\fR[=\fIlist\fR] -Print debug info for selected items (default: all). +Activate debug output (restricted to list). .SH ENVIRONMENT .IP PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER. .SH FILES .IP <texmf>/texdoc/texdoc.cnf, see output of the \fB\-\-files\fR option. -.SS "Homepage:" -.IP -http://tug.org/texdoc/ -.SS "Manual:" +.SH "REPORTING BUGS" +Report bugs to <texdoc@tug.org>. +.br +Texdoc home page: <http://tug.org/texdoc/> +.br +Source: <https://github.com/mpg/texdoc> +.SH COPYRIGHT +Copyright \(co 2008\-2011 Manuel P'egouri'e\-Gonnard. +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +.SH "SEE ALSO" +The full documentation is maintained as a PDF manual. The command .IP -displayed by `texdoc texdoc'. +.B texdoc texdoc +.PP +should give you access to the complete manual. diff --git a/Master/texmf/doc/man/man1/texdoc.man1.pdf b/Master/texmf/doc/man/man1/texdoc.man1.pdf Binary files differindex 5d7d8542de0..803a0b12583 100644 --- a/Master/texmf/doc/man/man1/texdoc.man1.pdf +++ b/Master/texmf/doc/man/man1/texdoc.man1.pdf diff --git a/Master/texmf/doc/texdoc/News b/Master/texmf/doc/texdoc/News index eed70d3aedb..75e9ffbb4c2 100644 --- a/Master/texmf/doc/texdoc/News +++ b/Master/texmf/doc/texdoc/News @@ -1,3 +1,19 @@ +Version 0.81 +------------ + +Allow configuration files to be found in all TEXMF trees. +The default one should now be installed in TEXMFDIST. + +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 ============ diff --git a/Master/texmf/doc/texdoc/texdoc.pdf b/Master/texmf/doc/texdoc/texdoc.pdf Binary files differindex 7f0a95ea405..4b0335da850 100644 --- a/Master/texmf/doc/texdoc/texdoc.pdf +++ b/Master/texmf/doc/texdoc/texdoc.pdf diff --git a/Master/texmf/doc/texdoc/texdoc.tex b/Master/texmf/doc/texdoc/texdoc.tex index 016f964b38b..4d05cde786a 100644 --- a/Master/texmf/doc/texdoc/texdoc.tex +++ b/Master/texmf/doc/texdoc/texdoc.tex @@ -1,31 +1,29 @@ % this is texdoc's user manual -% written by Manuel Pégourié-Gonnard in 2008, 2010 +% written by Manuel Pégourié-Gonnard in 2008, 2010 % distributed under the terms of GPL v3 or later -%!TEX encoding=latin1 -%!TEX program=pdflatex +%!TEX encoding=utf-8 +%!TEX program=xelatex \setlength\overfullrule{5pt} \documentclass[a4paper, oneside]{scrartcl} -\usepackage[latin1]{inputenc} -\usepackage[T1]{fontenc} -\usepackage{textcomp} -\usepackage{fixltx2e} - -\usepackage{tgbonum} -\usepackage{tgheros} -\usepackage[scaled=1.10]{inconsolata} +\usepackage{fontspec} +\usepackage{xunicode} + +\defaultfontfeatures{Ligatures=TeX} +\setmainfont{DejaVu Serif} +\setsansfont{DejaVu Sans} +\setmonofont{DejaVu Sans Mono} \renewcommand\familydefault{\sfdefault} \normalfont -\newcommand\otherfamily{\rmfamily} \newcommand\mylangle{$\langle$} \newcommand\myrangle{$\rangle$} \usepackage{xargs, xspace, fancyvrb, xcolor, pifont, calc, ifmtarg, mathstyle} -\usepackage[rm, bf]{titlesec} +\usepackage[sf, bf]{titlesec} \titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}} -\titleformat{\subsubsection}[runin]{\otherfamily\itshape}{% +\titleformat{\subsubsection}[runin]{\itshape}{% \makebox[0pt][r]{\thetitle\kern1pc}}{% 0pt}{}[\maybedot\space --- \kern0pt] \titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt} @@ -35,12 +33,11 @@ \setlist{noitemsep,topsep=\lssep,partopsep=\lssep} \usepackage[british]{babel} -\usepackage[babel=true, expansion=false]{microtype} \usepackage[bookmarks=true]{hyperref} \hypersetup{% bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2, pdftitle=texdoc: find and view documentation in TeX Live, - pdfauthor=Manuel Pégourié-Gonnard, + pdfauthor=Manuel Pégourié-Gonnard, pdfsubject=texdoc's user manual, pdfkeywords={texdoc, TeX Live, manual}} @@ -54,52 +51,40 @@ \href{http://#1}{#1}} \newcommand\texlive{% - \TeX{}\thinspace Live\xspace} + \TeX\thinspace Live\xspace} +\newcommand\tex{\TeX\xspace} +\newcommand\latex{\LaTeX\xspace} \setlength\parindent{\baselineskip} -\let\TeXori\TeX \def\TeX{\TeXori\xspace} % breaks the l2e logo \lastlinefit=500 % e-TeX powered \definecolor{links}{named}{violet} \definecolor{special}{rgb}{0,0.5,0} \definecolor{code}{rgb}{0,0,0.6} -\definecolor{input}{rgb}{1.0,0,0} -\newcommand\inputcolorname{red} \hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links} + \newcommand\cofont{% % code \color{code}\normalfont\ttfamily} -\newcommand\textco[1]{{\cofont#1}} -\newcommand\textme[1]{% % éléments meta - {\normalfont\color{special}\itshape #1\/}} -\newcommand\epfont{% % épigraphes - \normalcolor\usefont{T1}{pzc}{m}{it}} -\newcommand\textlmi[1]{% passage en lmodern italique pour voir - {\usefont{T1}{lmr}{m}{it}#1}} -\newcommand\textcm[1]{% % passage en cm pour voir - {\fontencoding{T1}\fontfamily{cmr}\selectfont#1}} -\newcommand\file{\nolinkurl} - -% take care of nbsp +\newcommand\meta[1]{% % meta elements + {\normalfont\color{special}\mylangle\textit{#1}\myrangle}} + +% take care of non-breakable spaces \catcode`\ 10\relax -\newcommand\meta[1]{% % variantes à remplacer - {\color{special}\mylangle\textme{#1}\myrangle}} -\newcommand\commandline[1]{% - \prompt\space \textcolor{input}{#1}} -\newcommand\prompt{\ding{229}} - -\fvset{formatcom=\cofont, defineactive={\makeallfancy}}% -\newcommand\makefancyog{% - \def«##1»{\meta{##1}}} -{\catcode32\active -\gdef\makefancythorn{% -\defþ ##1 þ{\commandline{##1}}}% -} -\newcommand\makefancypar{% - \def¶##1¶{\textcolor{input}{##1}}} +\fvset{% + formatcom=\cofont, + defineactive=\makeallfancy, + codes=\fancyactives, + } +\newcommand\fancyactives{% + \catcode`\«\active} \newcommand\makeallfancy{% - \makefancyog\makefancythorn\makefancypar} + \makefancyog} +{\catcode`\«\active +\global\def\makefancyog{% + \def«##1»{\meta{##1}}} +} \newif\ifframed \newlength\dec @@ -150,20 +135,21 @@ \BUseVerbatim{verbmat}% \par\medskip\@endpetrue} \makeatother -\DefineShortVerb{\©} +\DefineShortVerb{\©} \setkomafont{title}{} \setkomafont{subtitle}{\Large} \deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace} -\newcommand\texdoc{texdoc\xspace} \newcommand\tdml{\href{mailto:texdoc@tug.org}{texdoc mailing list}\xspace} -\title{\texdoc} -\subtitle{Find \& view documentation in \TeX\ Live} -\author{\url{http://tug.org/texdoc/}\\ - Manuel Pégourié-Gonnard} -\date{v0.80 2011-05-18} +\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.80 2011-05-18} +\date{} \begin{document} \VerbatimFootnotes @@ -174,94 +160,83 @@ \subsection{Basics} -Open a command line\footnote{On windows, use ``Execute'' from the Start menu - and type ©cmd©. On Mac OS X, use the ``terminal'' icon. 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 you want to learn -about. You can also look for the documentation of more than one package at -once: just give many names as arguments. - -The rest of this section describes the most usual options, like how to -see all documentation related to a package or use a different viewer. +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 +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. +for the given ©«name»©, which are ignored in view mode. -The so-called ``list mode'' makes \texdoc list all relevant documentation and +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 +list mode: if there is only one relevant result, then texdoc opens it in a viewer, else it offers you a menu. -Usually, \texdoc shows only the results it considers relevant. If there are no -``good'' results, it falls back to less relevant results. You can force -it to show you also ``bad'' results even when there are good ones by -using the ``showall'' mode. (This implies using a menu rather than starting a -viewer.) +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. -You can select the mode with command-line options: 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. +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, it is probably easier to -select it in a configuration file than to always use the command-line -option. +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} -\texdoc uses various configuration files, which you can see using the ©-f© or -©--files© options. The entry marked with a star ©(*)© -is the file you should use for your personal preferences as a user; you may -need to create it (and the parents directories). - -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©. +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}.) -You can also set your favorite language with ©lang = «2-letter code»© here, -though it is usually detected automatically. +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 files can be used to tweak \texdoc in many ways, the most +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. +documents, explained in the next section. -\subsection{Viewers} +\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 +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 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. +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{Conclusion} +\subsection{You can stop reading now} -We have now covered the most common needs. The next part explains how \texdoc -proceeds to find and sort results. The default configuration file tries hard -to set appropriate values so that you have a good out-of-the-box experience, -but you may want to understand the underlying mechanisms and adapt them to -your needs. The final part is a full reference for configuration options, -including points omitted in the present part. +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. -Your feedback is very welcome of the \tdml. Feel free to post comments, bug -reports, suggestions for improvements (inc. new aliases), even without -subscribing. +The final part is a full reference including a few points omitted in the +present and next part. \clearpage @@ -269,53 +244,54 @@ subscribing. \subsection{An overview of how texdoc works} -When you type ©texdoc «keyword»©, texdoc browses the trees containing -documentation (given by the \href{http://www.tug.org/kpathsea/} {kpathsea} -variable ©TEXDOCS©), lists all files containing ©«keyword»© in their name -(including the directory name) and give them a score based on 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. - -There is also some filtering based on extensions: only files with known -extensions are listed, and some extensions get a lesser score. Also, there is -some score adjustments based on keywords; 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 \TeX\ Live. Other source files are - discriminated by extension.} - -Then, depending on the mode, the file with the highest score is opened in a +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. Result with very bad score (-100 -and below) are never displayed. +score are displayed, except in showall mode. Results with very bad scores +(-100 and below) are never displayed. \medskip -However, this model works only if the documentation for ©«keyword»© has -©«keyword»© in its name, which is not always true. The documentation of the -memoir class is in ©memman.pdf©, for example, but it will be found anyway -since it is in a directory named memoir. But there are more complicated cases: -the documentation for mathptmx is in ©psnfss2e.pdf©; how can \texdoc guess -that? It looks for ©mathptmx.sty© in the \texlive package database and finds -it in the ©psnfss© package, and then adds the documentation files for this -package to the results. There are two PDF files: ©psfonts.pdf© and -©psnfss2e.pdf©, but only the second has a comment from the CTAN -catalogue\footnote{\url{http://texcatalogue.sarovar.org/} --- most relevant - information from the catalogue is included in the \texlive package - database.} so it is considered better. - -However, sometimes even this doesn't work. For example, suppose you're looking -for documentation about the standard ©article© \LaTeX\ class. Unfortunately, -the only file name ©article.pdf© is completely unrelated and the name of the -real file, ©classes.pdf©, is hard to guess (there are plenty of other -documentation files in the base ©latex© package). Here comes the notion of -\emph{alias}: in the default configuration file, article is aliased to -classes, so that when you type ©texdoc article©, texdoc knows it has to look -also for classes. Note that texdoc will also look for the original name, and -that a name can be aliased to more than one new name (since version 0.60). +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 @@ -324,9 +300,9 @@ 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 a - sequence of alphanumeric characters delimited by punctuation characters - (there is no space in file names in \TeX\ Live) and a subword is a + \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. @@ -335,59 +311,64 @@ case-insensitive): \subsection{Alias directives}\label{ss-alias} \begin{htcode} - alias «original keyword» = «name» - alias(«score») «original keyword» = «name» + alias «original keyword» = «name» + alias(«score») «original keyword» = «name» \end{htcode} -You can define your own aliases in \texdoc's configuration files +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 article = classes + alias shortvrb = base/doc \end{htcode} -in order to alias article to classes. Precisely, it means that files -matching exactly classes be added to the result list when you look for -article, 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. +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 +©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. -Please note than aliasing is case-insensitive, and the aliases don't cascade: -only aliases associated to the original keyword are used. 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. You can prevent the default aliases -from begin applied for a particular keyword by saying ©stopalias «keyword»© in -your personal configuration file. It will keep the aliases defined before -this directive (if any) and prevent all further aliasing on this keyword. +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. -Additionally, starting from version 0.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. +\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» + 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 the -configuration file (\ref{ss-quick-file} or \ref{ss-prec}) using the -©adjustscore© directive. Here are a few examples from the default -configuration file. +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 @@ -395,44 +376,59 @@ configuration file. adjscore(tex) texdoc = -10 \end{htcode} -All files named ©Makefile© (and also files names ©Makefile-foo© if there are -any): are ``killed'' : by adjusting their score with such a large negative +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 +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 +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. -Scoring is quite new and may need some adjustments. So, don't be surprised if -you need to adapt your scoring directives after a future update of texdoc. -This warning should disappear at some point. +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 base names} +\subsection{File extensions and names}\label{ss-ext} -The allowed file extensions are defined by the configuration item ©ext_list© +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 ©ext_list = «your, list»© in a configuration file. Be aware +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 +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). This only affect heuristic scoring (results found from the original -keyword, not from aliases). +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©. -Similarly, there are ©basename_list© and ©badbasename_list© parameters: a file -is selected only if its extension is in ©ext_list© or its base name in -©basename_list©. This is for ©readme.«stuff»© files where ©«stuff»© doesn't -mean anything about the file type. +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 @@ -440,32 +436,37 @@ mean anything about the file type. \subsection{Precedence of configuration sources}\label{ss-prec} -Values for a particular setting can come from several sources. They are treated -in the following order, where first value found is always used: +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 Environment variables ending with ©_texdoc©. \item Other environment variables. - \item Values from configuration files, read in the same order as they are - printed by ©texdoc --files©. - \item Hard-coded defaults that may depend on the current platform or the - current value of another setting. + \item Values from configuration files (see below). + \item Hard-coded defaults that may depend on the current machine. \end{enumerate} -The list of configuration files may include entries which depend on the -current platform, like ©texdoc-x86-64-linux.cnf© for instance. Those files are -meant to be used in when a single \texlive installation is shared across -machines with different architectures needing different settings. Their use is -not recommended in any other situation. - -Finally, the special file ©texdoc-dist.cnf© allows you to install a newer -version of \texdoc (including its default configuration file) in your home: -see \href{http://tug.org/texdoc/dev/}{the web page} for instructions on -running the development version. +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 three below) correspond to +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. @@ -487,143 +488,142 @@ Show the current version of the program and exit successfully. -f, --files \end{cmdsubsub} -Show the list of the configuration files for the current installation and +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}. +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}. +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}. +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}. +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}. +Set ©verbosity_level© to maximum, see~\ref{cf-verbosity_level}. \begin{cmdsubsub}{-d, --debug}{cl-d} - -d, -d=«list», --debug, --debug=«list» + -d, -d=«list», --debug, --debug=«list» \end{cmdsubsub} -Set ©debug_list©, see~\ref{cf-debug_list}. If not list is given, activates all +Set ©debug_list©, see~\ref{cf-debug_list}. If no list is given, activates all available debug items. -\begin{cmdsubsub}{--just-view}{cl-just-view} - --just-view -\end{cmdsubsub} - -This is a very special switch: when it is used, texdoc accepts only one -argument which must be the a file name with full path (absolute or relative to -current directory) and starts a viewer for this file according to its usual -viewer rules. Absolutely no search is done. It is unlikely you'll want to use -this option directly; it may however be useful when texdoc is used as a -back-end by other programs (such as texdoctk). - \subsection{Environment variables}\label{ss-envvar} -They all correspond to some ©viewer_«ext»© setting, and the reader is referred +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 +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© \\ + 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©. +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 ©#© +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. +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» + «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 +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 +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: +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 + \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© + \item ©_switch©, then ©«value»© must be either ©true© or ©false© (lowercase). - \item ©_level©, then ©«value»© is an integer. + \item ©_level©, then ©«value»© is an integer. \end{enumerate} -In these cases, an improper ©«value»© will raise a warning too. +In these cases, an improper ©«value»© will raise a warning too. \begin{cmdsubsub}{mode}{cf-mode} - mode = «view, list, mixed, showall» + mode = «view, list, mixed, showall» \end{cmdsubsub} -Set the mode to the given value. Default is ©view©. The various modes +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» + interact_switch = «true, false» \end{cmdsubsub} Turn on or off interaction. Default is on. Turning interaction off prevents -\texdoc to ask you to choose a file to view when there are multiple choices, -so it just prints the list of files found. +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}{alias}{cf-alias_switch} - alias_switch = «true, false» +\begin{cmdsubsub}{suffix_list}{cf-suffix_list} + suffix_list = «list» \end{cmdsubsub} -Turn on or off aliasing. Default is on. +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» + ext_list = «list» \end{cmdsubsub} -Set the list of recognised extensions to ©«list»©. Default is +Set the list of recognised extensions to ©«list»©. Default is \begin{htcode} pdf, html, htm, txt, dvi, ps, \end{htcode} @@ -633,108 +633,91 @@ 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 + ©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 +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 +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© +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» + 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 +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» + basename_list = «list» \end{cmdsubsub} -Set the list of allowed base names. Default is ©readme©. +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» + 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 +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}{suffix_list}{cf-suffix_list} - suffix_list = «list» -\end{cmdsubsub} - -Set the list of know documentation suffixes to ©«list»©. Default is -\begin{Verbatim} - doc, -doc, _doc, .doc, /doc, manual, /manual, -manual, userguide, - /user_guide, -guide, -user, -man, notes - \end{Verbatim} -When searching for ©«keyword»©, results (found directly with ©«keyword»© as -opposed to aliases) are scored in this order (from worse to best): -\begin{enumerate} - \item Substring match for ©«keyword»©. - \item Substring match for ©«keyword»«suffix»© for a listed ©«suffix»©. - \item Exact match for ©«keyword»«suffix»© for a listed ©«suffix»©. - \item Exact match for ©«keyword»©. -\end{enumerate} -(Adjustements may be done later based on other informations and settings.) - \begin{cmdsubsub}{viewer_*}{cf-viewer_*} - viewer_«ext» = «cmd» + 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 +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. +shell construct. \begin{cmdsubsub}{lang}{cf-lang} - lang = «2-letter code» + 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» + verbosity_level = «n» \end{cmdsubsub} -Set the verbosity level to ©«n»© (default: 2). 3 means errors, warnings and -informational messages will be printed (on stderr); 2 means only errors and +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» + debug_list = «list» \end{cmdsubsub} -Set the list of activated debug items (default: none; if the option is used -without arguments, the list defaults to all known debug items). Implies -©--verbose©. Debug information is printed on standard error. +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» + max_lines = «number» \end{cmdsubsub} Set the maximum number of results to be printed without confirmation in list, @@ -742,69 +725,69 @@ 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» + 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 +active, the value of ©interact_switch© is forced to ©false©, and each line of output is \begin{htcode} - «argument»\t«score»\t«filename» + «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) +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 TeX -Live database). These fields may be empty and they are not guaranteed to keep -the same meaning in future versions of \texdoc. +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» + 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 launched (the +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 +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.} \TeX\ Live doesn't ship compressed documentation files, so -this option is mainly useful with re-packaged version of \TeX\ Live that do, +\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» + unzip_«zipext» = «command» \end{cmdsubsub} -The unzipping command for zipped files with extension ©«zipext»© (default: no -default). Define one for each item in ©zipext_list©. The command must print -the result on stdout, like ©gzip -d -c© does. +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» + 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©). +©rm -f© and ©rmdir©). Only useful for zipped documents (see ©zipext_list©). \begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch} - lastfile_switch = «true, false» + 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 +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). @@ -819,8 +802,8 @@ The current exit codes are: \section{Licence}\label{s-licence} -The current \texdoc program and its documentation are copyright 2008, 2009 -Manuel Pégourié-Gonnard. +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 @@ -840,14 +823,14 @@ this program. If not, see \url{http://www.gnu.org/licenses/}. 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 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! + Happy \tex{}ing! \end{center} \end{document} diff --git a/Master/texmf/scripts/texdoc/alias.tlu b/Master/texmf/scripts/texdoc/alias.tlu index a99a8b51058..1ae150b5b1c 100644 --- a/Master/texmf/scripts/texdoc/alias.tlu +++ b/Master/texmf/scripts/texdoc/alias.tlu @@ -1,15 +1,6 @@ --- configuration handling for texdoc ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'config', -}) +-- alias.tlu: configuration handling for texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details --[[ structure of the alias table @@ -53,7 +44,7 @@ function add_alias(key, value, score) table.insert(alias[k], make_alias(value, score)) end --- prevent a key from begin further aliased +-- prevent a key from being further aliased function stop_alias(key) local k = string.lower(key) alias[k] = alias[k] or {} @@ -65,8 +56,7 @@ function get_patterns(name, no_alias) local n = string.lower(name) -- get normal aliases local res - if config.mode ~= 'regex' and config.alias_switch - and not no_alias and alias[n] then + if alias[n] and not no_alias then res = alias[n] else res = { make_alias(name, false) } @@ -119,9 +109,8 @@ function aliased_names() end end --- finally export a few symbols -export_symbols(L, { - 'confline_to_alias', - 'get_patterns', - 'aliased_names', -}) +return { + confline_to_alias = confline_to_alias, + get_patterns = get_patterns, + aliased_names = aliased_names, +} diff --git a/Master/texmf/scripts/texdoc/config.tlu b/Master/texmf/scripts/texdoc/config.tlu index 1e6aa7110b3..7681425e9bb 100644 --- a/Master/texmf/scripts/texdoc/config.tlu +++ b/Master/texmf/scripts/texdoc/config.tlu @@ -1,17 +1,6 @@ --- configuration handling for texdoc ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'os', 'kpse', 'lfs', 'io', 'setmetatable', 'print', - 'w32_path', 'confline_to_alias', 'confline_to_score', 'print_usage', - 'config', -}) +-- config.tlu: configuration handling for texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details -------------------------- hide the config table --------------------------- @@ -44,7 +33,13 @@ function set_config_element (key, value, context) -- warn and exit if key is not a known option if not is_known then config_warn(key, nil, context, true) return end -- exit if key is already set (/!\ must test for nil, not false) - if not (config[key] == nil) then return nil end + if not (config[key] == nil) then + if context.src ~= 'def' then + deb_print('config', "Ignoring '"..key.."="..value.."' " + ..context_to_string(context)..'.') + end + return nil + end -- record the source of the setting real_set_config(key..'_src', context.src) -- detect the type of the key @@ -86,17 +81,6 @@ function set_config_element (key, value, context) else -- string real_set_config(key, value) end - -- alias_switch is depecated - if key == 'alias_switch' and context.src ~= 'def' then - err_print('warning', - 'Command-line options -a, --alias, -A, --noalias, as well as') - err_print('warning', - 'configuration item alias_switch, are deprecated') - err_print('warning', - 'and will soon be removed.') - err_print('warning', - 'Please protest on the texdoc mailing list if you need it.') - end -- special case: if we just set debug_list, print version info now if key == 'debug_list' then deb_print('version', C.fullname..' version '..C.version) @@ -152,22 +136,8 @@ function setup_config_from_cl(arg) end while arg[1] and string.match(arg[1],'^%-') do curr_arg = table.remove(arg,1) - -- special options - if (curr_arg == '-h') or (curr_arg == '--help') then - setup_config_from_files() - setup_config_from_defaults() - print_usage() - os.exit(C.exit_ok) - elseif (curr_arg == '-V') or (curr_arg == '--version') then - print (C.progname .. ' ' .. C.version ) - os.exit(C.exit_ok) - elseif (curr_arg == '-f') or (curr_arg == '--files') then - print (C.progname .. ' ' .. C.version ) - setup_config_from_files () - show_config_files (print, true) - os.exit(C.exit_ok) - -- options related to mode - elseif (curr_arg == '-w') or (curr_arg == '--view') then + -- mode + if (curr_arg == '-w') or (curr_arg == '--view') then set_config_elt('mode', 'view') elseif (curr_arg == '-m') or (curr_arg == '--mixed') then set_config_elt('mode', 'mixed') @@ -175,12 +145,6 @@ function setup_config_from_cl(arg) set_config_elt('mode', 'list') elseif (curr_arg == '-s') or (curr_arg == '--showall') then set_config_elt ('mode', 'showall') - elseif (curr_arg == '--search') then - set_config_elt ('mode', 'showall') - err_print('warning', '--search has been renamed to --showall') - err_print('warning', 'Please use the new name.') - elseif (curr_arg == '-r') or (curr_arg == '--regex') then - set_config_elt ('mode', 'regex') -- interaction elseif (curr_arg == '-I') or (curr_arg == '--nointeract') then set_config_elt('interact_switch', 'false') @@ -189,11 +153,6 @@ function setup_config_from_cl(arg) -- output format elseif (curr_arg == '-M') or (curr_arg == '--machine') then set_config_elt('machine_switch', 'true') - -- alias - elseif (curr_arg == '-A') or (curr_arg == '--noalias') then - set_config_elt('alias_switch', 'false') - elseif (curr_arg == '-a') or (curr_arg == '--alias') then - set_config_elt('alias_switch', 'true') -- debug elseif (curr_arg == '-d') or (curr_arg == '--debug') then set_config_elt('debug_list', 'all') @@ -203,60 +162,19 @@ function setup_config_from_cl(arg) elseif string.match(curr_arg, '^%-%-debug=') then local value = string.gsub(curr_arg, '^%-%-debug=', '') set_config_elt('debug_list', value) - -- quiet + -- verbosity elseif (curr_arg == '-q') or (curr_arg == '--quiet') then set_config_elt('verbosity_level', C.min_verbosity) - -- verbose - elseif string.match(curr_arg, '^%-%-verbose') then + elseif (curr_arg == '-v') or (curr_arg == '--verbose') then set_config_elt('verbosity_level', C.max_verbosity) - elseif string.match(curr_arg, '^%-v') then - local value = string.gsub(curr_arg, '^%-v=?', '') - if value == '' then - set_config_elt('verbosity_level', C.max_verbosity) - else -- compatibility syntax - err_print('warning', - 'The -v option does not accept arguments any more.') - err_print('warning', - 'Please use the new syntax -v, --verbose (without argument).') - set_config_elt('verbosity_level', value) - end - elseif string.match(curr_arg, '^%-%-verbosity') then - -- compatibility syntax - local value = string.gsub(curr_arg, '^%-%-verbosity=?', '') - err_print('warning', - '--verbosity is deprecated and will be removed soon.') - err_print('warning', - 'Please use the new syntax -v, --verbose (without argument).') - set_config_elt('verbosity_level', value) - -- extensions list (deprecated) - elseif string.match(curr_arg, '^%-e') then - local value = string.gsub(curr_arg, '^%-e=?', '') - set_config_elt('ext_list', value) - err_print('warning', - '-e is deprecated and will likely be removed soon.') - err_print('warning', - 'ext_list should be set in a configuration file instead.') - err_print('warning', - 'Please protest on the texdoc mailing list if you need this.') - elseif string.match(curr_arg, '^%-%-extensions') then - local value = string.gsub(curr_arg, '^%-%-extensions=?', '') - set_config_elt('ext_list', value) - err_print('warning', - '--extensions is deprecated and will likely be removed soon.') - err_print('warning', - 'ext_list should be set in a configuration file instead.') - err_print('warning', - 'Please protest on the texdoc mailing list if you need this.') - -- just view (undocumented option fur use with texdoctk) - elseif curr_arg == '--just-view' then - real_set_config('just_view', true) -- problem else err_print('error', "unknown option: "..curr_arg) err_print('error', C.error_msg) - os.exit(C.exit_usage) + return false end end + return true end ------------------------- config from environment -------------------------- @@ -320,20 +238,30 @@ function confline_to_config(line, file, pos) return false end --- return the list of configuration files and the index of the recommended file +-- return the list of configuration files function get_config_files () + -- get names local platform = string.match (kpse.var_value ('SELFAUTOLOC'), '.*/(.*)$') - local TEXMFHOME = kpse.var_value ('TEXMFHOME') - local TEXMFLOCAL = kpse.var_value ('TEXMFLOCAL') - local TEXMFMAIN = kpse.var_value ('TEXMFMAIN') - 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', - }, 2 + local names = { + 'texdoc-'..platform..'.cnf', + 'texdoc.cnf', + 'texdoc-dist.cnf', + } + -- get dirs + local sep = (os.type == 'windows') and ';' or ':' + local texmf_texdoc = kpse.expand_path('$TEXMF/texdoc') + local dirs = texmf_texdoc:explode(sep) + -- merge them + local ret = {} + for _, dir in ipairs(dirs) do + for _, name in ipairs(names) do + local pathname = dir .. '/' .. name + if lfs.isfile(pathname) then + table.insert(ret, pathname) + end + end + end + return ret end -- the config_files table is shared by the next two functions @@ -342,15 +270,12 @@ local config_files = {} -- set config/aliases from all config files function setup_config_from_files () - local file_list, good_index = get_config_files() + local file_list = get_config_files() for i, file in ipairs (file_list) do - local found = lfs.isfile(file) - local status = found and (config.lastfile_switch - and 'disabled' or 'active') or 'absent' + local status = config.lastfile_switch and 'disabled' or 'active' config_files[i] = { path = file, status = status, - good = (i == good_index), } if status == 'active' then read_config_file (file) @@ -359,17 +284,16 @@ function setup_config_from_files () end -- now a special information function (see -f,--file option) -function show_config_files (print_fun, prefix) +function show_config_files (print_fun, verbose) + local pref = verbose and ' ' or '' print_fun("Configuration files are:") for i, file in ipairs (config_files) do - local home = prefix - and (file.good and "(*) " or " ") - or '' - print_fun (home..file.status..'\t'..w32_path(file.path)) + print_fun(pref..file.status..'\t'..w32_path(file.path)) end - if prefix then - print("(*) This is the recommended configuration file " - .. "for your personal preferences.") + if verbose then + local texmfhome = kpse.var_value('TEXMFHOME') + print_fun('Recommended file for personal settings:') + print_fun(pref..texmfhome..'/texdoc/texdoc.cnf') end end @@ -444,12 +368,9 @@ function desktop_environment_viewer() end end --- set some fall-back default values if no previous value is set -function setup_config_from_defaults() +-- set viewers from defaults (done only if necessary) +function get_default_viewers() 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 set_config_ls { -- Use 'start' to get file associations. @@ -525,7 +446,15 @@ function setup_config_from_defaults() } } end - -- then various, platform independant, stuff +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 + -- various, platform independant, stuff set_config_ls { mode = 'view', interact_switch = 'true', @@ -539,8 +468,6 @@ function setup_config_from_defaults() debug_list = '', max_lines = '20', } - -- must be set after mode! - set_config_elt ('alias_switch', alias_from_mode(config.mode)) -- zip-related options set_config_ls { zipext_list = '', @@ -549,32 +476,16 @@ function setup_config_from_defaults() } end --- the default value of config.alias_switch depends on the mode as follows -function alias_from_mode (mode) -- /!\ returns a string! - if (mode == 'regex') then - return 'false' - else - return 'true' - end -end - -------------------------- set all configuration --------------------------- -- populate the config and alias arrays function setup_config_and_alias(arg) -- setup config from all sources - setup_config_from_cl(arg) + local ret = setup_config_from_cl(arg) setup_config_from_env() setup_config_from_files() setup_config_from_locale() setup_config_from_defaults() - -- regex mode is deprecated - if config.mode == 'regex' then - err_print('warning', - 'Regex mode is deprecated and will likely be removed soon.') - err_print('warning', - 'Please protest on the texdoc mailing list if you need this.') - end -- machine mode implies no interaction if config.machine_switch == true then real_set_config('interact_switch', false) @@ -585,9 +496,12 @@ function setup_config_and_alias(arg) end -- we were waiting for config.debug_list to be known to do this show_config_files(function(s) deb_print('files', s) end) + -- propagated return value of _from_cl() + return ret end --- finally export a few symbols -export_symbols(L, { - 'setup_config_and_alias', -}) +return { + setup_config_and_alias = setup_config_and_alias, + get_default_viewers = get_default_viewers, + show_config_files = show_config_files, +} diff --git a/Master/texmf/scripts/texdoc/constants.tlu b/Master/texmf/scripts/texdoc/constants.tlu index a8c107034cc..0a24aded4bd 100644 --- a/Master/texmf/scripts/texdoc/constants.tlu +++ b/Master/texmf/scripts/texdoc/constants.tlu @@ -1,36 +1,34 @@ --- Global "constants" for texdoc. ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment. --- A name 'foo' defined here will be globally visible as 'C.foo', see EOF. -local L = {} -load_env(L, { - 'setmetatable', 'arg', -}) +-- constants.tlu: global "constants" for texdoc. +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details + +-- use an empty environment that will become texdoc_env.C (see EOF) +local constants = {} +local kpse = kpse +local setfenv = setfenv +local texdoc_env = getfenv() +setfenv(1, constants) + +-- BEGIN constants -- progname and version -fullname = arg[0] +fullname = kpse.find_file('texdoc/texdoclib', 'lua') progname = 'texdoc' -version = '0.80' +version = '0.81' -- 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 [OPTION]... [NAME]... +Usage: texdoc [OPTION]... NAME... + or: texdoc ACTION Try to find appropriate TeX documentation for the specified NAME(s). -With no NAME, print information about texdoc (--help, --version, --files). +Alternatively, perform the given ACTION and exit. Current settings: - -h, --help Print this help message. - -V, --version Print the version number. - -f, --files Print the list of configuration files used. - +Actions: +Options: -w, --view Use view mode: start a viewer. (default) -m, --mixed Use mixed mode (view or list). -l, --list Use list mode: show a list of results. @@ -42,12 +40,19 @@ Current settings: -q, --quiet Suppress warnings and most error messages. -v, --verbose Print additional information (eg, viewer command). - -d, --debug[=list] Print debug info for selected items (default: all). + -d, --debug[=list] Activate debug output (restricted to list). Environment: PAGER, BROWSER, PDFVIEWER, PSVIEWER, DVIVIEWER. Files: <texmf>/texdoc/texdoc.cnf, see output of the --files option. -Homepage: http://tug.org/texdoc/ -Manual: displayed by `texdoc texdoc'.]] +Report bugs to <texdoc@tug.org>. +Full manual available via `texdoc texdoc'.]] + +copyright_msg = [[ +Copyright (C) 2008-2011 Manuel P'egouri'e-Gonnard. +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. +This is free software: you are free to change and redistribute it.]] + +actions_ph = 'Actions:\n' usage_settings_ph = 'Current settings:' -- keep ../doc/texdoc wrapper in sync! usage_settings = { @@ -62,7 +67,6 @@ known_options = { 'mode', 'interact_switch', 'machine_switch', - 'alias_switch', 'ext_list', 'basename_list', 'badext_list', @@ -96,10 +100,6 @@ min_verbosity='0' max_verbosity='3' def_verbosity='2' -exit_ok = 0 -exit_error = 1 -- apparently hard-coded in Lua -exit_usage = 2 - known_debugs = { version = {}, files = {}, @@ -112,18 +112,22 @@ known_debugs = { -- various cache or non-cache files cache_name = 'texdoc/cache-tlpdb.lua' -- relative to TEXMFVAR -data_meta_name = 'Data.meta.lua' -data_tlpdb_name = 'Data.tlpdb.lua' +data_tlpdb_name = 'texdoc/Data.tlpdb.lua' place_holder = '%%s' -- used for viewer commands --- Make global C a read-only proxy to the local environment. +-- END constants + +-- get our previous environment back +setfenv(1, texdoc_env) + +-- Make global C a read-only proxy to the local <constants>. -- Note this is not deep read-only: C.known_debugs is read-only, but -- C.known_debugs.version isn't, for instance. assert(next(C) == nil, 'Internal error: table of constants should be empty at this point') setmetatable(C, { - __index = L, + __index = constants, __newindew = function () error('Internal error: attempt to modify a constant.') end diff --git a/Master/texmf/scripts/texdoc/functions.tlu b/Master/texmf/scripts/texdoc/functions.tlu index 4167b4563a9..f1ff54eca0b 100644 --- a/Master/texmf/scripts/texdoc/functions.tlu +++ b/Master/texmf/scripts/texdoc/functions.tlu @@ -1,16 +1,6 @@ --- General use functions for texdoc ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'io', 'os', 'print', - 'config', -}) +-- functions.tlu: general-use functions for texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details -- change '/' to '\' on windows -- Use: internal representation of files always use forward slashes. @@ -102,7 +92,9 @@ function parse_zip(file) end -- print a usage message, with the proper 'active values' line -function print_usage() +function print_usage(actions) + local usage_msg = C.usage_msg + -- get current settings local default, files = {}, {} for _, param in ipairs(C.usage_settings) do local display = param[config[param.name]] @@ -112,22 +104,30 @@ function print_usage() table.insert(files, display) end end + -- format and include them def = table.concat(default, ', ') conf = table.concat(files, ', ') if not (def == '') then def = def..' (default)' end if not (conf == '') then conf = conf..' (user config)' end local sep = (def == '' or conf == '') and '' or '; ' local settings = C.usage_settings_ph..' '..def..sep..conf..'.' - local usage_msg = string.gsub(C.usage_msg, C.usage_settings_ph, settings) + usage_msg = usage_msg:gsub(C.usage_settings_ph, settings) + -- include actions if any + if actions then + usage_msg = usage_msg:gsub(C.actions_ph, + C.actions_ph .. actions .. '\n\n') + else + usage_msg = usage_msg:gsub(C.actions_ph, '') + end + -- finally print it print(usage_msg) end --- finally export a few symbols -export_symbols(L, { - 'err_print', - 'deb_print', - 'w32_path', - 'parse_zip', - 'print_usage', - 'path_parent', -}) +return { + err_print = err_print, + deb_print = deb_print, + w32_path = w32_path, + parse_zip = parse_zip, + print_usage = print_usage, + path_parent = path_parent, +} diff --git a/Master/texmf/scripts/texdoc/main.tlu b/Master/texmf/scripts/texdoc/main.tlu index 9fc20ae1182..8ab4648e770 100644 --- a/Master/texmf/scripts/texdoc/main.tlu +++ b/Master/texmf/scripts/texdoc/main.tlu @@ -1,34 +1,68 @@ --- texdoc's main() ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'os', 'arg', 'print', - 'setup_config_and_alias', 'init_databases', 'print_usage', - 'get_doclist', 'deliver_results', 'aliased_names', - 'config', 'view_file', -}) - --- get started -setup_config_and_alias(arg) -init_databases() +-- main.tlu: default command-line interface of texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details + +-- load texdoclib (kpse initialized by the wrapper) +local texdoc = require('texdoc.texdoclib') + +-- exit codes +local exit_ok = 0 +local exit_error = 1 -- apparently hard-coded in Lua +local exit_usage = 2 + +-- action command-line options, not treated by setup_config_and_alias +local action_help = [[ + -h, --help Print this help message. + -V, --version Print the version number. + -f, --files Print the list of configuration files used. + --just-view file Display file, given with full path (no searching).]] +local action_opts = { + ['-h'] = 'help', + ['--help'] = 'help', + ['-V'] = 'version', + ['--version'] = 'version', + ['-f'] = 'files', + ['--files'] = 'files', + ['--just-view'] = 'view', +} + +-- detect action options, but do not act now (some need setup_config) +local action +if arg[1] then + action = action_opts[arg[1]] + if action then table.remove(arg, 1) end +end + +-- get configuration +if not texdoc.setup_config_and_alias(arg) then + os.exit(exit_usage) +end + +-- handle action options +if action == 'help' then + texdoc.print_usage(action_help) + os.exit(exit_ok) +elseif action == 'version' then + print(texdoc.const.progname .. ' ' .. texdoc.const.version) + print('\n' .. texdoc.const.copyright_msg) + os.exit(exit_ok) +elseif action =='files' then + print(texdoc.const.fullname .. ' ' .. texdoc.const.version) + texdoc.show_config_files(print, true) + os.exit(exit_ok) +elseif action == 'view' then + local ok = texdoc.view_file(arg[1]) + os.exit(ok and exit_ok or exit_error) +end -- make sure we actually have argument(s) if not arg[1] then - print_usage() - os.exit(C.exit_usage) + texdoc.print_usage() + os.exit(exit_usage) end --- special case for just view -if config.just_view then - local ok = view_file(arg[1]) - os.exit(ok and C.exit_ok or C.exit_error) -end +-- initialise databases +texdoc.init_databases() -- main loop local docname @@ -36,7 +70,10 @@ for _, docname in ipairs(arg) do -- do we have more then one argument? local multiarg = not not arg[2] -- get results - local doclist = get_doclist(docname) + local doclist = texdoc.get_doclist(docname) -- deliver results to the user - deliver_results(docname, doclist, multiarg) + texdoc.deliver_results(docname, doclist, multiarg) end + +-- the end +os.exit(exit_ok) diff --git a/Master/texmf/scripts/texdoc/score.tlu b/Master/texmf/scripts/texdoc/score.tlu index 75022e41288..697f0cf1b2a 100644 --- a/Master/texmf/scripts/texdoc/score.tlu +++ b/Master/texmf/scripts/texdoc/score.tlu @@ -1,15 +1,6 @@ --- scoring functions for texdoc ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a local environment. See texdoc.tlu for details. -local L = {} -load_env(L, { - 'config', 'parse_zip', -}) +-- score.tlu: scoring functions for texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details -- shared variables local global_adjscore, spec_adjscore = {}, {} @@ -57,8 +48,6 @@ end -- set the score of a docfile function set_score(df, original_kw) - -- scoring is irrelevant in regex mode - if config.mode == 'regex' then df.score = 0 return end -- scoring is case-insenstitive (patterns are already lowercased) local name = string.lower(df.shortname) deb_print('score', '----------') @@ -96,10 +85,11 @@ function set_score(df, original_kw) if df.details then if string.find(string.lower(df.details), 'readme') then score = score + 0.1 + deb_print('score', 'Catalogue "readme" bonus: +0.1') else score = score + 2.5 + deb_print('score', 'Catalogue details bonus: +2.5') end - deb_print('score', string.format('New score: %g from metadata', score)) end -- adjust from keyword-specific tables if df.tree > -1 and spec_adjscore[original_kw] then @@ -157,14 +147,14 @@ function heuristic_score(file, pat) end end end - -- if extension is bad, score gets < 0 + -- if extension is bad, score becomes an epsilon local ext = config.ext_list[ext_pos(file)] if ext and config.badext_list_inv[ext] and score > 0 then - upscore(-1, 'bad extension', true) + upscore(0.1, 'bad extension', true) end -- if basename is bad, score gets < 0 if has_bad_basename(file) and score > 0 then - upscore(-1, 'bad basename', true) + upscore(0.1, 'bad basename', true) end -- bonus for being in the right directory if string.find('/'..file, '/'..pat..'/', 1, true) and not slash then @@ -287,10 +277,10 @@ function sort_doclist(dl, original_kw) table.sort(dl, docfile_order) end --- export a few symbols -export_symbols(L, { - 'sort_doclist', - 'docfile_quality', - 'ext_pos', - 'confline_to_score', -}) +return { + sort_doclist = sort_doclist, + docfile_quality = docfile_quality, + ext_pos = ext_pos, + is_exact = is_exact, + confline_to_score = confline_to_score, +} diff --git a/Master/texmf/scripts/texdoc/search.tlu b/Master/texmf/scripts/texdoc/search.tlu index 11203fd97c5..1499c65414a 100644 --- a/Master/texmf/scripts/texdoc/search.tlu +++ b/Master/texmf/scripts/texdoc/search.tlu @@ -1,19 +1,6 @@ --- File searching functions for texdoc. ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'os', 'lfs', 'kpse', 'io', 'setmetatable', 'print', - 'dofile', 'loadfile', 'setfenv', 'rawget', 'rawset', - 'parse_zip', 'path_parent', - 'get_patterns', 'sort_doclist', 'docfile_quality', 'ext_pos', - 'config', -}) +-- search.tlu: file searching functions for texdoc. +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details -- Warning: every single function here assumes init_databases() has been called. @@ -362,13 +349,21 @@ function check_ext(file) return false end +-- say if a file (with its path) matches a pattern +function matches(pattern, file) + if pattern.original then + return string.find(file:lower(), pattern.name:lower(), 1, true) + else + return is_exact(file, pattern.name) + end +end + -- return a docfile object if file "matches", nil ortherwise function process_file(patlist, file, pathfile, code) local docfile local pattern for _, pattern in ipairs(patlist) do - if string.find(string.lower(pathfile), string.lower(pattern.name), - 1, config.mode ~= 'regex') then + if matches(pattern, pathfile) then local info = { name = pathfile, tree = code, @@ -568,12 +563,6 @@ function get_tlpinfo_from_cache(filename) s_meta, tlp_from_runfile, tlp_doclist = dofile(filename) end --- get pre-hashed meta from a file -function get_meta_hack() - local f = assert(kpse.find_file(C.data_meta_name, 'texmfscripts')) - s_meta = dofile(f) -end - -- get pre-hashed tlpdb info from a pseudo-cache file function get_tlpinfo_from_dist() local f = assert(kpse.find_file(C.data_tlpdb_name, 'texmfscripts')) @@ -633,7 +622,6 @@ end -- separate sty patterns from the rest function normal_vs_sty(list) - if config.mode == 'regex' then return list, {} end local normal, sty = {}, {} for _, p in ipairs(list) do if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then @@ -645,8 +633,7 @@ function normal_vs_sty(list) return normal, sty end --- finally export a few symbols -export_symbols(L, { - 'init_databases', - 'get_doclist', -}) +return { + init_databases = init_databases, + get_doclist = get_doclist, +} diff --git a/Master/texmf/scripts/texdoc/texdoc.tlu b/Master/texmf/scripts/texdoc/texdoc.tlu index 875450ff8ff..919e381ec33 100755 --- a/Master/texmf/scripts/texdoc/texdoc.tlu +++ b/Master/texmf/scripts/texdoc/texdoc.tlu @@ -1,96 +1,7 @@ #!/usr/bin/env texlua ---[[ -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. +-- texdoc.tlu: small wrapper around main.tlu +-- (makes it easier to install a new version of texdoc in TEXMFHOME) -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. ---]] - ----------------------- functions handling submodules ----------------------- - --- texdoc is divided in submodules (files). --- Most submodules use a private environment: that is, the functions and --- variables defined in a file won't be globally visible, unless explicitly --- exported at the end of the file. --- Also, symbols from the global environment (hence from other submodules) --- aren't imported in the local environment, except if explicitly requested and --- a few default symbols. - --- load a local environment, importing symbols from (this function's) _G --- usage: local L = {} load_env(L, {'a', 'b'}) -function load_env(l, symbols) - local default = { - 'export_symbols', - 'string', 'table', 'pairs', 'ipairs', 'tonumber', 'tostring', 'next', - 'assert', 'error', 'err_print', 'deb_print', - 'C', - } - for _, symb in ipairs(default) do - l[symb] = _G[symb] - end - local _, symb - for _, symb in ipairs(symbols) do - assert(_G[symb] ~= nil, - 'Internal error: trying to import undefined symbol '..symb..'.') - l[symb] = _G[symb] - end - setfenv(2, l) -end - --- export symbols from a local environment to (this fonction's) _G -function export_symbols(l, symbols) - local _, symb - for _, symb in ipairs(symbols) do - assert(l[symb] ~= nil, - 'Internal error: trying to export undefined symbol '..symb..'.') - assert(_G[symb] == nil, - 'Internal error: trying to export existing symbol '..symb..'.') - _G[symb] = l[symb] - end -end - --- execute a submodule of texdoc -function texdoc_do(name) - local f = kpse.find_file(name..'.tlu', 'texmfscripts') - assert(f, 'Internal error: unable to find texdoc module '..name..'.') - dofile(f) -end - ------------------------- initilisation & main code ------------------------- - --- initialize kpathsea kpse.set_program_name(arg[-1], 'texdoc') - --- declare global variables; --- they will be made read-only as soon as they are set -C = {} -- constants -config = {} -- configuration settings - --- actually load the submodules now -texdoc_do('constants') -texdoc_do('functions') -texdoc_do('alias') -texdoc_do('score') -texdoc_do('config') -texdoc_do('search') -texdoc_do('view') - --- execute main() -texdoc_do('main') - --- the end -os.exit(C.exit_ok) +require('texdoc.main') diff --git a/Master/texmf/scripts/texdoc/texdoclib.tlu b/Master/texmf/scripts/texdoc/texdoclib.tlu new file mode 100644 index 00000000000..54311ae4de8 --- /dev/null +++ b/Master/texmf/scripts/texdoc/texdoclib.tlu @@ -0,0 +1,90 @@ +-- texdoclib.tlu: the texdoc library + +--[[ +Copyright 2008, 2009, 2010, 2011 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. +--]] + +------------------------ functions for submodules ------------------------ + +-- texdoc is divided in submodules (files). Each module is loaded in a private +-- copy of a shared environment, and can export symbols to this environments +-- by returning a table to be merge with this environment. + +-- return a simple (not deep) copy of a table +local function simple_copy(t) + local c = {} + for sym, val in pairs(t) do + c[sym] = val + end + return c +end + +-- initialise the shared environment with a copy of the global environment +local prv_env = simple_copy(_G) +setfenv(1, prv_env) + +-- import symbols from a table to the share environment +local function import_symbols(symbols, name) + for sym, val in pairs(symbols) do + assert(val ~= nil, + 'Internal error: '..name..'exporting undefined symbol '..sym..'.') + assert(prv_env[sym] == nil, + 'Internal error: '..name..'exporting existing symbol '..sym..'.') + prv_env[sym] = val + end +end + +-- load a submodule of texdoc +local function texdoc_do(name) + local pathname = kpse.find_file('texdoc/'..name, 'lua') + assert(pathname, 'Internal error: missing submodule: '..name) + local submod = assert(loadfile (pathname)) + setfenv(submod, simple_copy(prv_env)) + local symbols = submod() + if symbols then import_symbols(symbols, name) end +end + +------------------------ initilisation & main code ------------------------- + +-- pre-declare variables in the shared environment +C = {} -- constants +config = {} -- configuration settings + +-- actually load the submodules now +texdoc_do('constants') +texdoc_do('functions') +texdoc_do('alias') +texdoc_do('score') +texdoc_do('config') +texdoc_do('search') +texdoc_do('view') + +return { + setup_config_and_alias = setup_config_and_alias, + init_databases = init_databases, + print_usage = print_usage, + get_doclist = get_doclist, + deliver_results = deliver_results, + aliased_names = aliased_names, + show_config_files = show_config_files, + config = config, + view_file = view_file, + const = C, +} diff --git a/Master/texmf/scripts/texdoc/view.tlu b/Master/texmf/scripts/texdoc/view.tlu index 8c327b00a72..b51bea4c570 100644 --- a/Master/texmf/scripts/texdoc/view.tlu +++ b/Master/texmf/scripts/texdoc/view.tlu @@ -1,16 +1,6 @@ --- view a document and/or display the list of results in texdoc ---[[ -Copyright 2008, 2009 Manuel Pégourié-Gonnard -Distributed under the terms of the GNU GPL version 3 or later. -See texdoc.tlu for details. ---]] - --- Load a private environment for this submodule (see texdoc.tlu). -local L = {} -load_env(L, { - 'os', 'io', 'print', - 'config', 'parse_zip', 'w32_path', -}) +-- view.tlu view a document and/or display the list of results in texdoc +-- +-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details ----------------------------- view a document ------------------------------ @@ -68,6 +58,11 @@ function view_file (filename) -- FIXME: hardcoding such cases this way is not very clean if viewext == 'texlive' then viewext = 'txt' end if viewext == 'htm' then viewext = 'html' end + -- get a viewer from built-in defaults if not already set + if not config['viewer_'..viewext] then + get_default_viewers() + end + -- still no viewers? use txt as a fallback if not config['viewer_'..viewext] then err_print('warning', "No viewer_"..viewext.." defined, using viewer_txt.") @@ -167,7 +162,7 @@ function deliver_results(name, doclist, many) return end -- shall we show all of them or only the "good" ones? - local showall = (config.mode == 'regex') or (config.mode == 'showall') + local showall = (config.mode == 'showall') if not showall and doclist[1].quality ~= 'good' then showall = true err_print('info', 'No good result found, showing all results.') @@ -185,8 +180,7 @@ function deliver_results(name, doclist, many) end end --- finally export a few symbols -export_symbols(L, { - 'view_file', - 'deliver_results', -}) +return { + view_file = view_file, + deliver_results = deliver_results, +} |