texlive[53643] trunk: texdoc (2feb20)
commits+karl at tug.org
commits+karl at tug.org
Sun Feb 2 23:44:20 CET 2020
Revision: 53643
http://tug.org/svn/texlive?view=revision&revision=53643
Author: karl
Date: 2020-02-02 23:44:20 +0100 (Sun, 02 Feb 2020)
Log Message:
-----------
texdoc (2feb20)
Modified Paths:
--------------
trunk/Build/source/texk/texlive/linked_scripts/texdoc/texdoc.tlu
trunk/Master/texmf-dist/doc/man/man1/texdoc.1
trunk/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf
trunk/Master/texmf-dist/doc/support/texdoc/NEWS
trunk/Master/texmf-dist/doc/support/texdoc/README.md
trunk/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
trunk/Master/texmf-dist/doc/support/texdoc/texdoc.tex
trunk/Master/texmf-dist/scripts/texdoc/texdoc.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
trunk/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
trunk/Master/texmf-dist/texdoc/texdoc.cnf
trunk/Master/tlpkg/libexec/ctan2tds
Added Paths:
-----------
trunk/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
Modified: trunk/Build/source/texk/texlive/linked_scripts/texdoc/texdoc.tlu
===================================================================
--- trunk/Build/source/texk/texlive/linked_scripts/texdoc/texdoc.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Build/source/texk/texlive/linked_scripts/texdoc/texdoc.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -7,11 +7,39 @@
-- Note: we keep this file small as much as possible so that make it easier
-- to install a new version of texdoc in TEXMFHOME.
--- setup the kpse library and load texdoclib
+local lfs = require 'lfs'
+local kpse = require 'kpse'
+
+-- setup kpse library
kpse.set_program_name(arg[-1], 'texdoc')
-local texdoc = require('texdoclib')
--- execute
+-- get realpath of this file
+local function realpath(p)
+ if os.type == 'unix' then
+ local h = io.popen(string.format("realpath '%s'", p))
+ local r = h:read('*a')
+ h:close()
+ return r:gsub('\n$', '')
+ else
+ return ''
+ end
+end
+local file = realpath(arg[0])
+
+-- if the file is not in TEXMFMAIN, set temporal TEXMFAUXTREES and TEXMFDIST
+local texmf = file:match('^(.*/texmf[^/]*)/scripts/texdoc/texdoc.tlu$')
+if texmf ~= nil then
+ if texmf ~= kpse.var_value('TEXMFMAIN') then
+ io.stderr:write('Info: ' ..
+ 'Running Texdoc not installed in the current TEXMFMAIN.\n')
+ os.setenv('TEXMFAUXTREES', texmf .. ',')
+ os.setenv('TEXMFDIST', ',')
+ end
+end
+
+-- load the library and execute
+local texdoc = require 'texdoclib'
+assert(texdoc.cli, 'Internal error: Texdoc is not installed properly.')
texdoc.cli.exec()
-- vim: ft=lua:
Modified: trunk/Master/texmf-dist/doc/man/man1/texdoc.1
===================================================================
--- trunk/Master/texmf-dist/doc/man/man1/texdoc.1 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/doc/man/man1/texdoc.1 2020-02-02 22:44:20 UTC (rev 53643)
@@ -1,16 +1,16 @@
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
-.TH "TEXDOC" "1" "March 2019" "Texdoc 3.1" "Texdoc manual"
+.TH "TEXDOC" "1" "February 2020" "Texdoc 3.2" "Texdoc manual"
.
.SH "NAME"
\fBtexdoc\fR \- find & view documentation in TeX Live
.
.SH "SYNOPSIS"
-\fBtexdoc\fR [OPTION\.\.\.] NAME\.\.\.
+\fBtexdoc\fR [OPTION]\.\.\. NAME\.\.\.
.
.br
-\fBtexdoc\fR [OPTION\.\.\.] ACTION
+\fBtexdoc\fR [OPTION]\.\.\. ACTION
.
.SH "DESCRIPTION"
Try to find appropriate TeX documentation for the specified NAME(s)\. Alternatively, perform the given ACTION and exit\.
@@ -59,10 +59,10 @@
.
.TP
\fB\-d\fR LIST, \fB\-\-debug\fR=LIST
-Activate debug output restricted to the items specified in LIST\.
+Activate debug output restricted to the categories specified in LIST\.
.
.br
-Available items: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\.
+Available categories: \fBconfig\fR, \fBfiles\fR, \fBsearch\fR, \fBscore\fR, \fBtexdocs\fR, \fBtlpdb\fR, \fBversion\fR, \fBview\fR, and \fBall\fR to activate all of these\.
.
.TP
\fB\-c\fR NAME=VALUE
@@ -87,6 +87,7 @@
Display FILE, given with full path (no searching)\.
.
.SH "ENVIRONMENT"
+The following environment variables can be split by colon and used to set viewers:
.
.TP
\fBBROWSER\fR, \fBBROWSER_texdoc\fR
@@ -112,6 +113,9 @@
\fBPSVIEWER\fR, \fBPSVIEWER_texdoc\fR
Set the command to be used for PS documents\.
.
+.P
+The following environment variables are also used:
+.
.TP
\fBLANG\fR, \fBLC_ALL\fR and so on
Set the locale (which will influence on the search results)\.
@@ -152,7 +156,7 @@
Source: \fIhttps://github\.com/TeX\-Live/texdoc\fR
.
.SH "COPYRIGHT"
-Copyright 2018 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining\.
+Copyright 2008\-2020 Manuel Pe\'gourie\'\-Gonnard, Takuto Asakura, the TeX Live Team\.
.
.br
License: GNU GPL version 3 or later \fIhttp://gnu\.org/licenses/gpl\.html\fR\.
Modified: trunk/Master/texmf-dist/doc/man/man1/texdoc.man1.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/texdoc/NEWS
===================================================================
--- trunk/Master/texmf-dist/doc/support/texdoc/NEWS 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/doc/support/texdoc/NEWS 2020-02-02 22:44:20 UTC (rev 53643)
@@ -2,6 +2,13 @@
===============
(This file public domain.)
+Version 3.2 (TeX Live 2020)
+===========================
+- Improved the scoring scheme to prioritize the latex tree than the latex-dev
+- Support invoking the program with absolute paths
+- The document was entirely rewritten
+- Other small improvements and bug fixes
+
Version 3.1 (TeX Live 2019)
===========================
- New option -c: changing configure temporally
Modified: trunk/Master/texmf-dist/doc/support/texdoc/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/support/texdoc/README.md 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/doc/support/texdoc/README.md 2020-02-02 22:44:20 UTC (rev 53643)
@@ -1,4 +1,4 @@
-# Texdoc v3.1 (2019-03-28)
+# Texdoc 3.2 (2020-02-02)
[](https://travis-ci.org/TeX-Live/texdoc)
[](https://ci.appveyor.com/project/wtsnjp/texdoc/branch/master)
@@ -106,7 +106,7 @@
## Copyright and License
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
This package is distributed under the terms of the GNU General Public License as published by the Free Software Foundation, either [version 3](./COPYING) of the License, or (at your option) any later version.
Added: trunk/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
===================================================================
--- trunk/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls (rev 0)
+++ trunk/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls 2020-02-02 22:44:20 UTC (rev 53643)
@@ -0,0 +1,236 @@
+% Document style for Texdoc user manual
+% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
+% distributed under the terms of GPL v3 or later
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{texdoc-doc}
+ [2020/02/02 Document class for Texdoc user manual]
+
+% class options
+\DeclareOption{draft}{\setlength\overfullrule{5pt}}
+\ProcessOptions\relax
+
+% remove "draft" from global options list
+% (code from https://tex.stackexchange.com/questions/33245/)
+\def\@clearglobaloption#1{%
+ \def\@tempa{#1}%
+ \def\@tempb{\@gobble}%
+ \@for\next:=\@classoptionslist\do
+ {\ifx\next\@tempa
+ \message{Cleared option \next\space from global list}%
+ \else
+ \edef\@tempb{\@tempb,\next}%
+ \fi}%
+ \let\@classoptionslist\@tempb
+ \expandafter\ifx\@tempb\@gobble
+ \let\@classoptionslist\@empty
+ \fi}
+\@clearglobaloption{draft}
+
+% basic dependency
+\LoadClass[a4paper,oneside,parskip=half-]{scrartcl}
+\RequirePackage[british]{babel}
+\RequirePackage{needspace}
+\RequirePackage{xunicode}
+\RequirePackage{fancyvrb}
+\RequirePackage{xparse}
+
+% font settings
+\RequirePackage{fontspec}
+\defaultfontfeatures{Ligatures=TeX}
+\setmainfont{DejaVuSerif}
+\setsansfont{DejaVuSans}
+\setmonofont{DejaVuSansMono}
+\renewcommand{\familydefault}{\sfdefault}
+
+% for math
+%\RequirePackage{unicode-math}
+%\setmathfont[math-style=ISO,bold-style=ISO]{TeX Gyre DejaVu Math}
+
+\setkomafont{title}{}
+\setkomafont{subtitle}{\Large}
+\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
+
+% headers
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.5\baselineskip]{section}
+\RedeclareSectionCommand[
+ runin=false,
+ afterindent=false,
+ beforeskip=\baselineskip,
+ afterskip=.3\baselineskip]{subsection}
+
+% colors
+\RequirePackage{xcolor}
+\definecolor{links}{named}{violet}
+\definecolor{special}{rgb}{0,0.5,0}
+\definecolor{code}{rgb}{0,0,0.6}
+
+% list environments
+\RequirePackage{enumitem}
+\newlength\lssep \setlength\lssep{\smallskipamount}
+\setlist{noitemsep, topsep=\lssep, partopsep=\lssep}
+
+% hyperref and bookmark
+\RequirePackage[
+ colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links,
+ bookmarks=true, bookmarksnumbered=true, bookmarksopen=true,
+ bookmarksopenlevel=2]{hyperref}
+\RequirePackage{bookmark}
+
+% text styles
+\DeclareUrlCommand\path{\urlstyle{tt}\color{links}}
+\DeclareTextFontCommand{\emph}{\color{code}}
+
+% for metadata
+\AtBeginDocument{%
+ \bgroup
+ \def\and{, }%
+ \hypersetup{%
+ pdftitle={\@title: \@subtitle},
+ pdfauthor={\@author},
+ pdfsubject={Texdoc's user manual},
+ pdfkeywords={Texdoc, TeX Live, manual, documentation}}
+ \egroup}
+\RequirePackage[yyyymmdd]{datetime}
+\renewcommand{\dateseparator}{-}
+
+% title (overwrite \@maketitle from scrartcl)
+\newcommand*{\pkgurl}[1]{\gdef\@pkgurl{\url{#1}}}
+\renewcommand*{\@maketitle}{%
+ \global\@topnum=\z@
+ \setparsizes{\z@}{\z@}{\z@\@plus 1fil}\par at updaterelative
+ \ifx\@titlehead\@empty \else
+ \begin{minipage}[t]{\textwidth}
+ \usekomafont{titlehead}{\@titlehead\par}%
+ \end{minipage}\par
+ \fi
+ \null
+ \vskip 2em%
+ \begin{center}%
+ \ifx\@subject\@empty \else
+ {\usekomafont{subject}{\@subject \par}}%
+ \vskip 1.5em
+ \fi
+ {\usekomafont{title}{\huge \@title \par}}%
+ \vskip .5em
+ {\ifx\@subtitle\@empty\else\usekomafont{subtitle}\@subtitle\par\fi}%
+ \vskip .1em
+ {\ifx\@pkgurl\@empty\else\usekomafont{subtitle}\@pkgurl\par\fi}%
+ \vskip 1em
+ {%
+ \usekomafont{author}{%
+ \lineskip .5em%
+ \begin{tabular}[t]{c}
+ \@author
+ \end{tabular}\par
+ }%
+ }%
+ \vskip 1em%
+ {\usekomafont{date}{\@date \par}}%
+ \vskip \z@ \@plus 1em
+ {\usekomafont{publishers}{\@publishers \par}}%
+ \ifx\@dedication\@empty \else
+ \vskip 2em
+ {\usekomafont{dedication}{\@dedication \par}}%
+ \fi
+ \end{center}%
+ \par
+ \vskip 2em
+}
+
+% Low layer settings
+\lastlinefit=500 % e-TeX powered
+\catcode`\ 10\relax % take care of non-breakable spaces
+
+% some macros
+\DeclareRobustCommand{\TL}{\texorpdfstring{\TeX\,\,Live}{TeX Live}}
+\newcommand*{\TexdocML}
+ {\href{http://lists.tug.org/texdoc}{mailing list}}
+\newcommand*{\TexdocRepo}
+ {\href{https://github.com/TeX-Live/texdoc}{GitHub repository}}
+\newcommand*{\ie}{i.e.,\,}
+\newcommand*{\eg}{e.g.,\,}
+\newcommand*{\hyph}{-}
+\newcommand*{\meta}[1]{\bgroup
+ \normalfont\color{special}$\langle$\textit{#1}$\rangle$\egroup}
+\newcommand*{\metatab}{\code{\char`\\t}}
+\newcommand*{\choice}[1]{\bgroup
+ \def\@delim{\def\@delim{\space\char`\|\space}}%
+ \normalfont\color{special}%
+ \@for\@item:=#1\do{\@delim\@item}%
+ \egroup}
+\newcommand*{\code}[1]{\bgroup
+ \chardef\_=`\_\code at font #1\egroup}
+\newcommand*{\sopt}[1]{\hyperlink{cl:#1}{\code{\hyph#1}}}
+\newcommand*{\lopt}[1]{\hyperlink{cl:#1}{\code{\hyph{}\hyph#1}}}
+\newcommand*{\ci}[1]{\bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp at hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \hyperlink{\@tmp at hyname}{\code{#1}}}
+
+% verbatim
+\def\code at font{% code
+ \color{code}\normalfont\ttfamily}
+\fvset{%
+ formatcom=\code at font,
+ defineactive=\makeallfancy,
+ commandchars=\\\{\},
+ codes=\fancyactives}
+\newcommand{\fancyactives}{\catcode`\«\active}
+\newcommand{\makeallfancy}{\makefancyog}
+\bgroup
+ \catcode`\«\active
+ \gdef\makefancyog{\def«##1»{\meta{##1}}}
+\egroup
+
+% manual entries
+\newenvironment{manual at entry}{\begin{list}{}{%
+ \setlength{\leftmargin}{2em}%
+ \setlength{\itemindent}{0pt}%
+ \setlength{\itemsep}{0pt}%
+ \setlength{\parsep}{0pt}%
+ \setlength{\rightmargin}{0em}%
+ }\item}{\end{list}}
+
+\NewDocumentEnvironment{clopt}{ m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\sopt##1{\hypertarget{cl:##1}{\code{\hyph##1}}}%
+ \def\lopt##1{\hypertarget{cl:##1}{\code{\hyph{}\hyph##1}}}%
+ \needspace{3ex}\noindent #1\egroup
+ \IfNoValueF{#2}{\hfill (#2)}%
+ \begin{manual at entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual at entry}}
+
+\NewDocumentEnvironment{confitem}{ m m o }
+ {%
+ \par\vskip\baselineskip
+ \bgroup
+ \def\_{-}\def\meta##1{##1}%
+ \edef\x{\noexpand\def\noexpand\@tmp at hyname{cf:#1}}%
+ \expandafter\egroup\x
+ \needspace{3ex}\noindent
+ \hypertarget{\@tmp at hyname}{\code{#1 = #2}}%
+ \IfNoValueF{#3}{\hfill (#3)}%
+ \begin{manual at entry}%
+ }
+ {\ifvmode\else\unskip\fi\end{manual at entry}}
+
+% code in hors-text
+\newenvironment{htcode}
+ {\SaveVerbatim[samepage]{verbmat}}
+ {%
+ \endSaveVerbatim
+ \par\medskip\noindent\hspace*{2em}%
+ \BUseVerbatim{verbmat}%
+ \par\medskip\@endpetrue
+ }
+
+\DefineShortVerb{\|}
+% EOF
Property changes on: trunk/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/support/texdoc/texdoc.tex
===================================================================
--- trunk/Master/texmf-dist/doc/support/texdoc/texdoc.tex 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/doc/support/texdoc/texdoc.tex 2020-02-02 22:44:20 UTC (rev 53643)
@@ -1,603 +1,530 @@
%#!xelatex
% Texdoc user manual
-% Copyright 2008 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
% distributed under the terms of GPL v3 or later
+\documentclass{texdoc-doc}
-\setlength\overfullrule{5pt}
-
-\documentclass[a4paper,oneside]{scrartcl}
-\usepackage{fontspec}
-\usepackage{xunicode}
-
-\defaultfontfeatures{Ligatures=TeX}
-\setmainfont{DejaVuSerif}
-\setsansfont{DejaVuSans}
-\setmonofont{DejaVuSansMono}
-\renewcommand\familydefault{\sfdefault} \normalfont
-\newcommand\mylangle{$\langle$}
-\newcommand\myrangle{$\rangle$}
-
-\usepackage{xargs,xspace,fancyvrb,xcolor,pifont,calc,ifmtarg,mathstyle}
-
-\usepackage[sf,bf]{titlesec}
-\titlelabel{\makebox[0pt][r]{\thetitle\kern1pc}}
-\titleformat{\subsubsection}[runin]{\itshape}
- {\makebox[0pt][r]{\thetitle\kern1pc}}
- {0pt}{}[\maybedot\space --- \kern0pt]
-\titlespacing{\subsubsection}{0pt}{0.5\baselineskip}{0pt}
-
-\usepackage{enumitem}
-\newlength\lssep \setlength\lssep{\smallskipamount}
-\setlist{noitemsep,topsep=\lssep,partopsep=\lssep}
-
-\usepackage[british]{babel}
-\usepackage[bookmarks=true]{hyperref}
-\usepackage{bookmark}
-\hypersetup{%
- bookmarksnumbered=true, bookmarksopen=true, bookmarksopenlevel=2,
- pdftitle={Texdoc: find and view documentation in TeX Live},
- pdfauthor={Manuel Pégourié-Gonnard, Takuto Asakura},
- pdfsubject={Texdoc's user manual},
- pdfkeywords={Texdoc, TeX Live, manual, documentation},
-}
-
-\usepackage[yyyymmdd]{datetime}
-\renewcommand{\dateseparator}{-}
-
-\newcommand\texlive{\TeX~Live\xspace}
-
-\setlength\parindent{\baselineskip}
-
-\lastlinefit=500 % e-TeX powered
-
-\definecolor{links}{named}{violet}
-\definecolor{special}{rgb}{0,0.5,0}
-\definecolor{code}{rgb}{0,0,0.6}
-\hypersetup{colorlinks=true, linkcolor=links, urlcolor=links, citecolor=links}
-
-\newcommand\cofont{% code
- \color{code}\normalfont\ttfamily}
-\newcommand\meta[1]{% meta elements
- {\normalfont\color{special}\mylangle\textit{#1}\myrangle}}
-
-% take care of non-breakable spaces
-\catcode`\ 10\relax
-
-\fvset{%
- formatcom=\cofont,
- defineactive=\makeallfancy,
- codes=\fancyactives,
-}
-\newcommand\fancyactives{\catcode`\«\active}
-\newcommand\makeallfancy{\makefancyog}
-\bgroup
- \catcode`\«\active
- \global\def\makefancyog{\def«##1»{\meta{##1}}}
-\egroup
-
-\newif\ifframed
-\newlength\dec
-\setlength\dec{\heightof{\cofont{texdoc \meta{name}}}}
-
-\makeatletter
-\newenvironment{commandes}[3]{%
- \def\thecmd{\noexpand#1}%
- \def\bmtext{#2}%
- \def\thelabel{#3}%
- \SaveVerbatim[samepage, gobble=2]{verbmat}%
-}{%
- \endSaveVerbatim
- \xdef\sectioncmd{\noexpand\nodotthistime
- \thecmd[\bmtext]{%
- \ifframed
- \unexpanded{\normalsize\normalfont
- \fbox{\raisebox{\dec}{\BUseVerbatim[baseline=t]{verbmat}}}}%
- \else
- \unexpanded{\normalsize\normalfont
- \BUseVerbatim{verbmat}}%
- \fi
- \noexpand\label{\thelabel}}}%
- \aftergroup\sectioncmd
-}
-\makeatother
-
-\newcommand\maybedot{.}
-\newcommand\nodotthistime{\renewcommand\maybedot{\global\def\maybedot{.}}}
-
-\newenvironment{cmdsubsec}[2]
- {\framedtrue \commandes\subsection{#1}{#2}}
- {\endcommandes}
-
-\newenvironment{cmdsubsub}[2]
- {\framedfalse \commandes\subsubsection{#1}{#2}}
- {\endcommandes}
-
-\makeatletter
-% code in hors-text
-\newenvironment{htcode}
- {\SaveVerbatim[samepage, gobble=2]{verbmat}}
- {
- \endSaveVerbatim
- \par\medskip\noindent\hspace*{\parindent}%
- \BUseVerbatim{verbmat}%
- \par\medskip\@endpetrue
- }
-\makeatother
-\DefineShortVerb{\|}
-
-\setkomafont{title}{}
-\setkomafont{subtitle}{\Large}
-\deffootnote[1.5em]{1.5em}{1em}{\textsuperscript{\thefootnotemark}\thinspace}
-
-\newcommand\tdml{\href{http://lists.tug.org/texdoc}{texdoc mailing list}\xspace}
-
\title{Texdoc}
-\subtitle{Find \& view documentation in \texlive\\
- \href{https://tug.org/texdoc/}{https://tug.org/texdoc/}}
+\subtitle{Find \& view documentation in \TL}
+\pkgurl{https://tug.org/texdoc/}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
-\date{v3.1\quad \today}
+\date{v3.2\quad \today}
\begin{document}
+
\VerbatimFootnotes
\maketitle
-\section{Quick guide}
+\section{Quick Guide}
-\subsection{Basics}
-
-Texdoc is a command line tool which find and view documentation in \texlive.
-If you type
+Texdoc is a command-line tool to find and view documents in {\TL}. Typing
%
-\begin{quote}
-|texdoc «name»|
-\end{quote}
+\begin{htcode}
+texdoc «name»
+\end{htcode}
%
-in your command line, the documentation of the |«name»| package will pop up. Of
-course, you have to replace |«name»| with the actual name of the package. To
-look up the documentation of more than one package at once, just use multiple
-|«name»|s as arguments.
+in your command line, you will see a document of the |«name»| package is popped
+up. Of course, you have to replace |«name»| with the actual name of a package.
+To look up the documentation of more than one packages at once, just give
+multiple |«name»|s as arguments.
-\subsection{Modes}\label{ss-modes}
+\subsection{Modes}
+\label{sec:modes}
-Texdoc has different modes that determine how results will be handled. In the
-default, ``view'' mode, it opens the first (supposedly the best) result with a
-suitable 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.
+Texdoc has several modes that determine how results will be returned. The
+default is \emph{view} mode, which opens the first, that is supposedly the
+best, result with a suitable viewer. It is rather handy when you know what you
+want to read. On the other hand, there may be other relevant documents for the
+given |«name»|, which are ignored in the view mode.
-The so-called ``list mode'' makes Texdoc list all relevant documentation and
-ask you which one you want to view. It is useful when there another interesting
-sources of information besides the package's main documentation.
+In the \emph{list} mode, Texdoc lists all relevant documentation and ask you
+which one you want to view. This mode is useful when there are other
+interesting sources of information in addition to the main documentation of a
+package.
-There is also a ``mixed'' mode, intended to combine the best of view mode and
-list mode: if there is only one relevant result, then Texdoc opens it in a
-viewer, else it offers you a menu.
+There is also a \emph{mixed} mode, intended to get the best of the view mode
+and list mode: if there is only one good result, then Texdoc opens it in a
+viewer, like in the view mode. Otherwise, it offers you a menu, like in the
+list mode.
-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.
+By default, Texdoc hides some results, which expected to be less relevant,
+unless it cannot find any relevant result. In the \emph{showall} mode, Texdoc
+always shows all results, including bad ones.
-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.
+A couple of command-line options are available for selecting the mode to
+execute: \sopt{w} (\lopt{view}) for the view mode, \sopt{m} (\lopt{mixed}) for
+the mixed mode, \sopt{l} (\lopt{list}) for the list mode, and \sopt{s}
+(\lopt{showall}) for the showall mode.
-If you always (or mostly) use the same mode, you don't want to keep typing the
-same option. The next section describes how to customize Texdoc using
-configurations files.
+If you have your favorite mode and always use it, you may not want to keep
+typing the same option. The next section describes how to customize Texdoc
+using its configurations files.
-\subsection{Configuration files}\label{ss-quick-file}
+\subsection{Configuration files}
+\label{sec:quick-file}
-Use |texdoc --files| to know where to put your personal configuration file;
-you'll need to create this file (a possibly some directories) the first time.
-(If you want to know the full list of possible configuration files,
-see~\ref{ss-prec}.)
+The configuration file enables you to tweak Texdoc in many ways. You can use
+the \lopt{files} option to know where to put your personal configuration file;
+you may need to create this file, possibly with some parent directories. If you
+want to know the full list of possible configuration files, see
+Section~\ref{sec:prec}.
-In order to select you favorite mode, just insert a line |mode = «mode»| in
-this file, where |«mode»| is one of |view|, |mixed|, |list| or |showall|. To
-set your favorite language, use |lang = «2-letter code»|, though it is usually
-detected automatically.
+To set your favorite mode, just insert a line |\ci{mode} = «mode»| in your
+personal configuration file, where |«mode»| is one of |view|, |mixed|, |list|,
+and |showall|. Though your preferred language is usually detected automatically
+by getting the system locale, you can set it explicitly with a line
+|\ci{lang} = «2-letter code»| in the configuration file.
-The configuration file can be used to tweak Texdoc in many ways, the most
-useful of which is probably the selection of the viewers for various types of
-documents, explained in the next section.
+\subsection{Viewers}
+\label{sec:viewer}
-\subsection{Viewers}\label{ss-viewer}
-
-Texdoc's mechanism for choosing a viewer varies according to your platform.
-On Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
+The way of Texdoc for choosing a viewer varies according to your platform. On
+Windows, macOS, or Unix with KDE, GNOME, or XFCE, it uses your file
associations like when you double-click files in the Explorer, the Finder or
your default file manager (except for the text viewer, which is always a
pager). Otherwise, it tries to find a viewer in the path from a list of
``known'' viewers.
-You may want to select a different viewer for some kind of file. This is
-achieved by setting the various |viewer_«ext»| configuration options, where
-|«ext»| is the extension corresponding to the file type. For example, if you
-want to set xpdf as your default PDF viewer, and run it in the background,
-insert the line |viewer_pdf = xpdf %s &| in your configuration file. Here,
-|%s| stands for the name of the file to view.
+You may want to use a different viewer for some types of documents. This can be
+achieved by setting the various \ci{viewer\_\meta{ext}} configuration items,
+where |«ext»| is an extension corresponding to a file type. For example, if
+you want to set \code{xpdf} as your default PDF viewer, and run it in the
+background, insert the line |viewer_pdf = xpdf %s &| in your configuration
+file. Herein, |%s| is a place holder for the name of the file to view.
-\subsection{You can stop reading now}
+\subsection*{\underline{You can stop reading now}}
-Following parts explain Texdoc's mechanisms for finding the best results and
-how to customize them. We have been trying hard to optimize the default
-configuration values so that you normally don't need to fiddle with that, but
-you may be curious or have special needs.
+The following parts explain the mechanisms of Texdoc for finding the best
+results and how to customize them. We have been trying hard to optimize the
+default configuration values so that normal users do not need to fiddle with
+it. Thus, the following parts are useful only when you are curious or have
+special needs.
-The final part is a full reference including a few points omitted in the
-present and next parts.
-
\clearpage
-\section{File search, aliases, score}
+\section{Controlling Texdoc}
-\subsection{An overview of how Texdoc works}
+\subsection{Command-line options}
+\label{sec:cl}
-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{https://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 be
- |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. In case Texdoc cannot find any documentation here, fuzzy search will
-find the closest package name to the |«keyword»| and reselect the files (see
-\ref{ss-fuzzy}).
-
-The selected files are then score according to some simple heuristics. For
-example, a file named |«keyword».pdf|, is good, |«keyword»-«lang».pdf| will
-score higher if your favorite language |«lang»| is detected or configured,
-|«keyword»-doc| will be preferred over |«keyword»whatever|, files in a
-directory named exactly |«keyword»| get a bonus, etc.
-
-Score may also be adjusted base on file extensions or known names (or
-subwords): for example, by default, |Makefile|s get a very bad score since
-they are almost never documentation.\footnote{They often end up in the doc
- tree, since the source of documentation is often in the same directory as
- the documentation itself in \texlive. Other source files are discriminated
- by extension.}
-
-Finally, depending on the mode, the file with the highest score is opened in a
-viewer, or the list of results is shown. Usually, only results with a positive
-score are displayed, except in showall mode. Results with very bad scores
-(-100 and below) are never displayed.
-
-\medskip
-
-This model for searching and scoring is quite efficient, but is unfortunately
-not perfect: Texdoc may sometimes need a hint, either to find a relevant file
-or, more likely, to recognize which of the files found is the most relevant.
-
-For example, assume you are looking for the documentation of the shortvrb
-{\LaTeX} package. Texdoc will find |shortvrb.sty| in the |latex| \texlive
-package, but since this package contains a lot of documentation files, none of
-which contains the string |shortvrb|, it will sort them basically at random.
-
-Here comes the notion of \emph{alias}: in the default configuration file,
-|shortvrb| is aliased to |base/doc|, so that when you type |texdoc shortvrb|,
-Texdoc knows it has to look primarily for |base/doc|. Note that Texdoc will
-also look for the original name, and that a name can be aliased to more than
-one new name.
-
-\medskip
-
-We will soon see how you can configure this, but let's start with a few
-definitions about how a file can match keyword (all matching is
-case-insensitive):
-\begin{enumerate}
- \item The keyword is a substring of the file name.
- \item The keyword is a ``subword'' of the file name; words are defined as
- sequences of alphanumeric characters delimited by punctuation characters
- (there is no space in file names in \texlive) and a subword is a
- substring both ends of which are a word boundary.
- \item The keyword matches ``exactly'' the file name: that is, the file
- name is the keyword, possibly plus an extension.
-\end{enumerate}
-
-\subsection{Alias directives}\label{ss-alias}
-
+The full usage of Texdoc can be summarized as follows:
+%
\begin{htcode}
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
+texdoc «names»
+texdoc «options» «names»
+texdoc «action»
+texdoc «options» «action»
\end{htcode}
-You can define your own aliases in Texdoc's configuration files
-(see~\ref{ss-quick-file} or \ref{ss-prec}). For example,
-insert\footnote{Actually, you don't need to do this, the default configuration
- file already includes this directive.}
-\begin{htcode}
- alias shortvrb = base/doc
-\end{htcode}
-in order to alias |shortvrb| to |base/doc|. Precisely, it means that files in
-the doc trees matching exactly |base/doc| will be added to the result list
-when you look for |shortvrb|, and get a score of 10 (default score for alias
-results). This is greater than the results of heuristic scoring: it means that
-results found via aliases will always rank before results associated to the
-original keyword.
+We have tried to implement a GNU-compatible option parser. Short options, each of
+which consists of a single letter, must start with a single hyphen |-|.
+Multiple short options can be specified with a single hyphen, \eg |-vl| is
+equivalent to |-v -l|. Long options have to be following double hyphens |--|.
+All options must be specified before the first argument. A String beginning
+with a hyphen after the first argument will be treated as an argument starting
+with a hyphen.
-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.
+Some options are called action options, which can be used for |«action»| in the
+above usage. Four actions are available:
-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.
+\begin{clopt}{\sopt{h}, \lopt{help}}
+Shows a quick help message (namely a list of command-line options) and exit
+successfully.
+\end{clopt}
-You can have a look at the configuration file provided (the last shown by
-|texdoc -f|) for examples. If you feel one of the aliases you defined locally
-should be added to the default configuration, please share it on the \tdml.
+\begin{clopt}{\sopt{V}, \lopt{version}}
+Shows the current version of the program and exit successfully.
+\end{clopt}
-Aliases are additive: if you define your own aliases for a keyword in your
-configuration file, and there are also aliases for the same keyword in the
-default configuration, they will add up. To prevent the default aliases
-from being 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.
+\begin{clopt}{\sopt{f}, \lopt{files}}
+Shows the list of configuration files for the current installation and
+platform, with their status and exit successfully. Normally, only ``active''
+and ``disabled'' files are shown (see~\ci{lastfile\_switch}). To show ``not
+found'' files as well, you can use \lopt{verbose}.
+\end{clopt}
-\textit{Remark.} Aliasing is case-insensitive, and doesn't cascade:
-only aliases associated to the original keyword are used.
+\begin{clopt}{\code{\lopt{just-view} \meta{file}}}
+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.
+\end{clopt}
-\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.
+Some normal options such as \sopt{v} are effective for some actions but note
+that you have to specify such options \emph{before} the action option. Options
+after an action option will be ignored.
-\subsection{Score directives}\label{ss-score}
+The followings are other normal command-line options:
-\begin{htcode}
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
-\end{htcode}
+\begin{clopt}{\sopt{w}, \lopt{view}}[default]
+Set \ci{mode} to |view|. Texdoc will open the best results it found by the best
+application it knows. See Section~\ref{sec:modes}.
+\end{clopt}
-It is possible to adjust the score of results containing some pattern as a
-subword, either globally (for the result of all searches) or only when
-searching with a particular keyword. This is done in a configuration file
-(\ref{ss-quick-file} or \ref{ss-prec}) using the |adjscore| directive. Here are
-a few examples from the default configuration file.
+\begin{clopt}{\sopt{l}, \lopt{list}}
+Set \ci{mode} to |list|. Texdoc will show the lists of all relevant documents
+it found and ask you which to open. When used with the \lopt{nointeract}
+option, Texdoc will just show the lists of documents and exist successfully.
+\end{clopt}
-\begin{htcode}
- adjscore /Makefile = -1000
- adjscore /tex-virtual-academy-pl/ = -50
- adjscore(tex) texdoc = -10
-\end{htcode}
+\begin{clopt}{\sopt{m}, \lopt{mixed}}
+Set \ci{mode} to |mixed|. If Texdoc finds only a document for your keyword,
+then it opens it, and if it finds multiple, then it will behave like in the
+|list| mode.
+\end{clopt}
-All files named |Makefile| (and also files named |Makefile-foo| if there are
-any) are ``killed'' : by adjusting their score with such a large negative
-value, their final score will most probably be less than -100, so they will
-never be displayed. Files from the |tex-virtual-academy-pl| directory, on the
-other hand, are not killed but just get a malus, since they are a common
-source of ``fake'' matches which hide better results (even for the lucky ones
-who can read polish).
+\begin{clopt}{\sopt{s}, \lopt{showall}}
+Set \ci{mode} to |showall|. It also behave like in a |list| mode, but show all
+the documents it found including documents which seem to be not a good result.
+\end{clopt}
-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 will not be displayed unless ``showall'' mode is active.
+\begin{clopt}{\sopt{i}, \lopt{interact}}[default]
+Texdoc may require user reactions, \eg ask you which document to open in the
+|list| mode. Internally, this sets \ci{interact\_switch} to |true|.
+\end{clopt}
-\textbf{Warning}: Values of scores (like the default score for aliases, the
-range of heuristic scoring, etc.) may change in a future version of Texdoc.
-So, don't be surprised if you need to adapt your scoring directives after a
-future update of Texdoc. This warning will hopefully disappear at some point.
+\begin{clopt}{\sopt{I}, \lopt{nointeract}}
+If this is specified, Texdoc will never request any input from users.
+Internally, this sets \ci{interact\_switch} to |false|.
+\end{clopt}
-\subsection{File extensions and names}\label{ss-ext}
+\begin{clopt}{\sopt{M}, \lopt{machine}}
+This make the result list of Texdoc machine-readable. Only effective for the
+|list| mode and its friends. This option implies \lopt{nointeract}.
+Internally, this sets \ci{machine\_switch} to |true|.
+\end{clopt}
-The allowed file extensions are defined by the configuration item |ext_list|
-(default: pdf, html, htm, txt, md, ps, dvi, no extension). You can configure it
-with a line |ext_list = «your, list»| in a configuration file. Be aware
-that it will completely override the default list, not add to it. An empty
-string in the list means files without extension (no dot in the name), while a
-star means any extension.
+\begin{clopt}{\sopt{q}, \lopt{quiet}}
+This suppress warnings and most error messages. Internally, this sets
+\ci{verbosity\_level} to minimum.
+\end{clopt}
-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).
+\begin{clopt}{\sopt{v}, \lopt{verbose}}
+Make Texdoc to print additional information such as viewer commands which are
+invoked by the program. Internally, this sets \ci{verbosity\_level} to maximum.
+\end{clopt}
-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|.
+\begin{clopt}{%
+ \code{\sopt{d} \meta{list}}, \code{\lopt{debug}=\meta{list}},
+ \sopt{D}, \lopt{debug}}
+This sets \ci{debug\_list} to show dubbging information in the specified
+category. You can specify multiple categories with a comma-separated list. If
+you specify |-D| or |--debug| without specifying a list, it activates all
+available debug categories.
+\end{clopt}
-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.''
+\begin{clopt}{\code{\sopt{c} \meta{name}=\meta{value}}}
+This enables you to set arbitrary configuration items |«name»| to |«value»|
+from the command-line. See Section~\ref{sec:conf} for the list of all available
+configuration items.
+\end{clopt}
-\subsection{Variants}\label{ss-variants}
+\subsection{Environment variables}
+\label{sec:envvar}
-The documentation for a given package is often found in a file named like
-|«package»-doc|. To handle this properly, Texdoc gives a special score files
-named |«package»«suffix»| where |«suffix»| is one element of the list given by
-the configuration setting |suffix_list|.
+Some environment variables affect the behavior of Texdoc. The environment
+variables can be roughly categorized into three groups.
-To customise this list, add a line with |suffix_list = «your, list»| in a
-configuration file. 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).
+First, as well as other programs in {\TL}, searching path for the Texdoc are
+determined with the Kpathsea variables like |TEXMF*|. The mechanism of Kpathsea
+is complex, so please refer to `the {\TL} Guide', which supposed to be open by
+|texdoc texlive|, and the document of Kpathsea for the details. Usually, Texdoc
+searches documents for the |TEXMF| trees including |TEXMFDIST|, |TEXMFLOCAL|,
+and |TEXMFHOME| and trees specified in |TEXDOCS|. It also self-locates its own
+program using |TEXMF| search path. In addition, Texdoc uses |TEXMFROOT| and
+|TEXMFVAR| to look for the tlpdb database and the cache respectively.
-\subsection{Fuzzy search}\label{ss-fuzzy}
+Second, the viewers for opening documents can be controlled by some environment
+variables. They all correspond to some \ci{viewer\_\meta{ext}}
+setting.\footnote{Old names of environment variables, namely
+|TEXDOCVIEW_\{html,dvi,md,txt,pdf,ps\}| and
+|TEXDOC_VIEWER_\{HTML,DVI,MD,TXT,PDF,PS\}|, are deprecated but still work.} You
+can append |_texdoc| to every name in the first column: this wins over every
+other name. These variables can be split by colon |:| and the first non-nil
+occurrence is used. If a viewer command contains colon, please specify it by
+\ci{viewer\_\meta{ext}}.
+%
+\begin{center}
+\begin{tabular}{lll}
+Variable & Use for & Configuration item \\ \hline
+|BROWSER| & HTML files & |viewer_html| \\
+|DVIVIEWER| & DVI files & |viewer_dvi| \\
+|MDVIEWER| & Markdown files & |viewer_md| \\
+|PAGER| & Text files & |viewer_txt| \\
+|PDFVIEWER| & PDF files & |viewer_pdf| \\
+|PSVIEWER| & PS files & |viewer_ps| \\
+\end{tabular}
+\end{center}
-When the normal search can't find any document in {\texlive}, Texdoc will
-execute fuzzy search without user-interactions. The fuzzy search finds the
-closest name of package in {\texlive}\footnote{Note that the feature searches
-only package names at this point. Other objects such as aliases cannot be found
-by the fuzzy search.} to the input |«keyword»|. The results of fuzzy search are
-shown by as an informational message (you can see that with option |-v|).
+Third, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
+are used for the default value of \ci{lang}.
-The default allowance of Levenshtein distance is 5. You can change this default
-value by specifying |fuzzy_level| in your |texdoc.cnf| (see
-\ref{cf-fuzzy_level}). Results of fuzzy search could be irreproducible if
-multiple strings have the same Levenshtein distance.
+\subsection{Precedence of configuration sources}
+\label{sec:prec}
-\clearpage
-
-\section{Full reference}
-
-\subsection{Precedence of configuration sources}\label{ss-prec}
-
Values for a particular setting can come from several sources. The sources are
-treated in the following order and the first value found is always used:
+looked at in the following order and the first value found is always used:
+%
\begin{enumerate}
- \item Command-line options.
- \item Environment variables ending with |_texdoc|.
- \item Other environment variables.
- \item Values from configuration files (see below).
- \item Hard-coded defaults that may depend on the current machine.
+\item Command-line options.
+\item Environment variables ending with |_texdoc|.
+\item Other environment variables.
+\item Values from configuration files (see below).
+\item Hard-coded defaults that may depend on the current machine.
\end{enumerate}
-The configuration files are found in the directories |TEXMF/texdoc|, where
-|TEXMF| is the kpathsea variable, in the order given by this variable. Inside
-each directory, three files are recognized, in this order:
+The configuration files are found in the directories \path{TEXMF/texdoc}, where
+\path{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{https://github.com/TeX-Live/texdoc}{our GitHub repository} for
- instructions on running the development version.
+\item |texdoc-«platform».cnf| where |«platform»| is the name of the current
+ platform (defined as the name of the directories where the {\TL}
+ 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
+ {\TexdocRepo} for instructions on running the development version.
\end{enumerate}
-\subsection{Command-line options}\label{ss-cl}
+\subsection{Exit codes}
+\label{sec:exit}
-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.
+The status of Texdoc, which is whether or not it was successfully executed and
+an expected result was delivered, can be grasped by seeing its exit code. This
+will be useful to manage Texdoc by other programs. The current exit codes of
+Texdoc are:
+%
+\begin{description}[left=2em]
+\item[\code{0}] Success.
+\item[\code{1}] Internal error.
+\item[\code{2}] Usage error.
+\item[\code{3}] No documentation found.
+\end{description}
-\begin{cmdsubsub}{-h, --help}{cl-h}
- -h, --help
-\end{cmdsubsub}
+\section{Customizing the Search Results}
-Shows a quick help message (namely a list of command-line options) and exit
-successfully.
+\subsection{An overview of how Texdoc works}
-\begin{cmdsubsub}{-V, --version}{cl-V}
- -V, --version
-\end{cmdsubsub}
+When you type |texdoc «keyword»|, first filenames related to the |«keyword»|
+are collected from the two following sources.
+%
+\begin{enumerate}
+\item the |TEXMF| trees containing documentation that specified by the
+ \href{https://www.tug.org/kpathsea/}{kpathsea} variable |TEXDOCS|: Texdoc
+ collects all files containing |«keyword»| in their filenames or in the names
+ of their parent directories.
+\item the {\TL} Database (|texlive.tlpdb|): Texdoc searches for packages named
+ |«keyword»| or containing a file |«keyword».«ext»| where |«ext»| may be |sty|
+ or |cls|, and collects all document files of the found packages.
+\end{enumerate}
-Shows the current version of the program and exit successfully.
+Second, the collected filenames are filtered by their extensions. After
+filtering, only files with known extensions (listed in \ci{ext\_list}) remain.
+If Texdoc cannot find any documentation, the fuzzy search will find the closest
+package name to the |«keyword»| and it will recollect document files (see
+Section~\ref{sec:fuzzy}).
-\begin{cmdsubsub}{-f, --files}{cl-f}
- -f, --files
-\end{cmdsubsub}
+Third, the collected filenames are given numeric scores by using some
+heuristics. For example, a filename |«keyword».pdf| is good, and thus gets a
+high score. A name |«keyword»-«lang».pdf| is also good and gets a higher score
+if the |«lang»| is the preferred language code in your configuration. In
+addition, there are several rules such as ``a name |«keyword»-doc| always wins
+over any names |«keyword»whatever|'' and ``files under a directory named
+exactly |«keyword»| get bonuses''. Scores may also be adjusted based on the
+extensions and some known names or subwords. For example, by default,
+|Makefile|s get very low scores because basically they are not
+documents.\footnote{Nevertheless, they often end up in the |doc| trees,
+because in {\TL}, sources of documents are usually in the same directory as the
+documents themselves. Other source files for documents are discriminated by
+their extensions.}
-Shows the list of configuration files for the current installation and
-platform, with their status and exit successfully. Normally, only ``active''
-and ``disabled'' files are shown (see~\ref{cf-lastfile_switch}). To show ``not
-found'' files as well, you can use |--verbose|.
+Finally, a file with the highest score is opened with a viewer, or the list
+of results is shown, depending on the current mode. Usually, only results with
+positive scores are displayed, except in the |showall| mode. Results with very
+bad scores, that are lower than |-100|, are never displayed.
-\begin{cmdsubsub}{--just-view}{cl-just-view}
- --just-view «file»
-\end{cmdsubsub}
+This model for searching and scoring is efficient, but unfortunately, it is not
+perfect: Texdoc may sometimes need a hint, either to find a relevant file or,
+more likely, to recognize which of the found files is the best. For example,
+suppose you are looking for a document of the {\LaTeX} package |shortvrb|.
+Texdoc will successfully find |shortvrb.sty| in the {\TL} package |latex|.
+However, Texdoc will not be able to sort a number of documents in the |latex|
+package correctly because none of them contains the string |shortvrb|.
-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.
+For such cases, \emph{aliases} are useful: in the default configuration file,
+|shortvrb| is aliased to |base/doc|, so that Texdoc primarily look for
+|base/doc| when you type |texdoc shortvrb|. Note that Texdoc will also look for
+the original keyword, and that a name can be aliased to more than one new
+name.
-\begin{cmdsubsub}{-w, -l, -m, -s, --view, --list, --mixed, --showall}{cl-mode}
- -w, --view, -l, --list, -m, --mixed, -s, --showall
-\end{cmdsubsub}
+\subsection{Aliases}
+\label{sec:alias}
-Set |mode| to the given value, see~\ref{cf-mode}.
+Aliases can be set in configuration files of Texdoc with the following syntax:
+%
+\begin{htcode}
+alias «original keyword» = «name»
+alias(«score») «original keyword» = «name»
+\end{htcode}
+%
+A number of aliases are already set in the default configuration file. You can
+also define your own aliases in your personal configuration files (see
+Section~\ref{sec:quick-file} or \ref{sec:prec} to know where is that). For example,
+you can add a line
+%
+\begin{htcode}
+alias td = texdoc
+\end{htcode}
+%
+to the file to alias |td| to |texdoc|. Then, files in the doc trees matching
+exactly with |texdoc|, \ie this document |texdoc.pdf|, will be added to the
+result list when you search for the keyword |td|.
-\begin{cmdsubsub}{-i, -I, --interact, --nointeract}{cl-i}
- -i, --interact, -I, --nointeract
-\end{cmdsubsub}
+By default, files match with the aliased name get a score of |10|. This score
+is greater than any result of heuristic scoring. It means that results found
+via aliases will always be ranked higher than results found for the original
+keyword. If you want the results associated with a particular alias to have a
+custom score instead of the default score |10|, you can use the optional
+argument to the |alias| directive. This can be useful if you associate multiple
+aliases to a keyword and want to specify the priorities for them.
-Set |interact_switch| to true (or false), see~\ref{cf-interact_switch}.
+In addition, 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 when searching for |«keyword»|. Files match with these language-based
+aliases get additional bonus scores so that they win over the results for
+language-independent aliases.
-\begin{cmdsubsub}{-M, --machine}{cl-M}
- -M, --machine
-\end{cmdsubsub}
+For concrete examples, please have a look at the default configuration file,
+which can be found in the last line of the output for |texdoc -f|. If you think
+aliases you defined locally should be added to the default configuration,
+please share the idea to the {\TexdocML} or {\TexdocRepo}.
-Set |machine_switch| to true, see~\ref{cf-machine_switch}.
+Aliases are additive: if you define your own aliases for a keyword in your
+configuration file, and there are also aliases for the same keyword in the
+default configuration, they will add up. To prevent the default aliases from
+being applied for a particular keyword, add a line |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.
-\begin{cmdsubsub}{-q, --quiet}{cl-q}
- -q, --quiet
-\end{cmdsubsub}
+Here are some notes for aliases. First, they are case-insensitive. Second, they
+do not work recursively: only aliases set to the original keyword are used.
+Third, results found for aliases always get the score defined by the |alias|
+directive (|10| by default). The adjustments described in the other subsections
+are not applied to results for aliases.
-Set |verbosity_level| to minimum, see~\ref{cf-verbosity_level}.
+\subsection{Score adjustments}
+\label{sec:score}
-\begin{cmdsubsub}{-v, --verbose}{cl-v}
- -v, --verbose
-\end{cmdsubsub}
+Scores can be arbitrary adjusted by using the |adjscore| directive in the
+configuration files. The adjustment can be done either for global, \ie for any
+keywords, or a particular keyword. The syntax is as follow:
+%
+\begin{htcode}
+adjscore «pattern» = «score adjustment»
+adjscore(«keyword») «pattern» = «score adjustment»
+\end{htcode}
+%
+When the optional argument |«keyword»| is specified, the adjustment will be
+applied only when a user searches for the |«keyword»|. Otherwise, the
+adjustment applied always for the |«pattern»|.
-Set |verbosity_level| to maximum, see~\ref{cf-verbosity_level}.
+Here are a few examples from the default configuration file.
-\begin{cmdsubsub}{-d, -D, --debug}{cl-d}
- -d «list», --debug=«list», -D, --debug
-\end{cmdsubsub}
+\begin{htcode}
+adjscore /Makefile = -1000
+adjscore /tex-virtual-academy-pl/ = -50
+adjscore(tex) texdoc = -10
+\end{htcode}
+%
+Herein, all files named |Makefile|, and those with suffixes, \eg |Makefile.in|,
+will be eliminated from results: by adjusting their score with such a large
+negative value, their final score will be less than |-100|. Which means they
+will never be displayed. Files from the |tex-virtual-academy-pl| directory, on
+the other hand, are not eliminated but get a negative adjustment, since they
+are a common source of ``fake'' matches which hide better results. The third
+line gives a minus adjustment for results containing |texdoc| only when the
+searched keyword is |tex|. Otherwise, such results would get high scores
+because the heuristic scoring would assume |texdoc| is the name of
+documentation for {\TeX} itself. The adjustment value |-10| is enough to ensure
+that those results will have a negative score, so the files containing |texdoc|
+will not be displayed unless |showall| mode is used.
-Set |debug_list|, see~\ref{cf-debug_list}. If you specify |-D| or |--debug|
-without specifying a list, activates all available debug items.
+Note that the values of scores, such as the default score for aliases and the
+range of heuristic scores, may be changed in a future version of Texdoc.
+Therefore, you may need to adapt your score adjustments after updating Texdoc
+in the future.
-\begin{cmdsubsub}{-c}{cl-c}
- -c «name»=«value»
-\end{cmdsubsub}
+\subsection{Extensions and basenames of files}
+\label{sec:ext}
-Set configuration item |«name»| to |«value»|. This is a general way to access
-any configuration items listed in \ref{ss-conf} from command line.
+File extensions regarded as documents by Texdoc can be specified with the
+configuration item \ci{ext\_list}. By default, files with extensions |pdf|,
+|html|, |htm|, |txt|, |md|, |ps|, and |dvi| and files without extension are
+recognized as documents.
-\subsection{Environment variables}\label{ss-envvar}
+During the scoring process, the configuration item |badext_list| is also used:
+files with a ``bad'' extension appearing in this list will get a lesser score.
-They all correspond to some |viewer_«ext»| setting, and the reader is referred
-to~\ref{cf-viewer_*} for details.\footnote{Old names of environment variables,
-namely |TEXDOCVIEW_{html,dvi,md,txt,pdf,ps}| and
-|TEXDOC_VIEWER_{HTML,DVI,MD,TXT,PDF,PS}|, are deprecated but still work.} You can
-append |_texdoc| to every name in the first column: this wins over every other
-name.
+In the practical filenames, things which are not actually extensions can follow
+dots, \eg |readme.fr| and |readme.texlive|. Thus, in addition to the lists of
+known extensions, Texdoc has lists for known basenames: \ci{basename\_list} and
+\ci{badbasename\_list}. These configuration items are respectively similar to
+\ci{ext\_list} and \ci{badext\_list}. In short, a file will be selected if
+either its extension or its basename is known, and get a lesser score if either
+is known to be ``bad''.
-\begin{center}
-\begin{tabular}{ll}
-Environment variables & Configuration items \\
-|BROWSER| & |viewer_html| \\
-|DVIVIEWER| & |viewer_dvi| \\
-|MDVIEWER| & |viewer_md| \\
-|PAGER| & |viewer_txt| \\
-|PDFVIEWER| & |viewer_pdf| \\
-|PSVIEWER| & |viewer_ps| \\
-\end{tabular}
-\end{center}
+\subsection{Common filenames}
+\label{sec:common-names}
-Also, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
-are used for the default value of |lang|.
+Document filenames of packages are often in the form of |«package»-doc|.
+Respecting this culture in the {\TeX} community, Texdoc gives a special score
+for files named |«package»«suffix»|, where |«suffix»| is an element of the list
+\ci{suffix\_list}. Please refer to the shipped configuration file for the
+default setting. Also, feel free to suggest additional elements for the list to
+the {\TexdocML} with a real-life example.
-\subsection{Configuration items}\label{ss-conf}
+\subsection{Fuzzy search}
+\label{sec:fuzzy}
-\subsubsection{Structure of configuration files}\label{sss-sonf-struct}
+When the normal search cannot find any document in {\TL}, Texdoc will execute a
+fuzzy search. The fuzzy search tries to find the closest name of a package in
+{\TL}\footnote{Note that the feature searches only package names at this point.
+Other objects such as aliases cannot be found by the fuzzy search.} to the
+input |«keyword»|. The results of the fuzzy search are shown in an info
+message, which can be seen by using the command-line option |-v|.
+The default allowance of Levenshtein distance is |5|. You can change this
+allowance by using the configuration item \ci{fuzzy\_level}. Results of fuzzy
+search could be different among executions if multiple package names have the
+same Levenshtein distance to the input.
+
+\section{Configuration items}
+\label{sec:conf}
+
Configuration files are line-oriented text files. Comments begin with a |#|
and run to the end of line. Lines containing only space are ignored. Space at
the beginning or end of a line, as well as around an |=| sign, is ignored.
Apart from comments and empty lines, each line must be of one of the following
forms.
-
+%
\begin{htcode}
- «configuration item» = «value»
- alias «original keyword» = «name»
- alias(«score») «original keyword» = «name»
- stopalias «original keyword»
- adjscore «pattern» = «score adjustment»
- adjscore(«keyword») «pattern» = «score adjustment»
+«configuration item» = «value»
+alias «original keyword» = «name»
+alias(«score») «original keyword» = «name»
+stopalias «original keyword»
+adjscore «pattern» = «score adjustment»
+adjscore(«keyword») «pattern» = «score adjustment»
\end{htcode}
We will concentrate on the |«configuration item»| part here, since other
-directives have already been presented (\ref{ss-alias} and \ref{ss-score}).
+directives have already been presented (Section~\ref{sec:alias} and
+\ref{sec:score}).
In the above, |«value»| never needs to be quoted: quotes would be interpreted
as part of the value, not as quotation marks (this also holds for the other
@@ -606,56 +533,48 @@
Lines which do not obey these rules raise a warning, as well as unrecognised
values of |«configuration item»|. The |«value»| can be an arbitrary string,
except when the name of the |«configuration item»| ends with:
+%
\begin{enumerate}
- \item |_list|, then |«value»| is a coma-separated list of strings. Space
- around commas is ignored. Two consecutive comas or a coma at the beginning
- or end of the list means the empty string at the corresponding place.
- \item |_switch|, then |«value»| must be either |true| or |false|
- (lowercase).
- \item |_level|, then |«value»| is an integer.
+\item |_list|, then |«value»| is a coma-separated list of strings. Spaces
+ around commas are ignored. Two consecutive comas or a coma at the beginning
+ or end of the list means the empty string at the corresponding place.
+\item |_switch|, then |«value»| must be either |true| or |false|
+ (lowercase).
+\item |_level| and |_lines|, then |«value»| is an integer.
\end{enumerate}
+%
In these cases, an improper |«value»| will raise a warning too.
-\begin{cmdsubsub}{mode}{cf-mode}
- mode = «view, list, mixed, showall»
-\end{cmdsubsub}
-Set the mode to the given value. Default is |view|. The various modes
-have been presented in~\ref{ss-modes}.
+\begin{confitem}{mode}
+ {\choice{view, list, mixed, showall}}[default: \code{view}]
+Set the mode to the given value. The various modes have been described
+in Section~\ref{sec:modes}.
+\end{confitem}
-\begin{cmdsubsub}{interact}{cf-interact_switch}
- interact_switch = «true, false»
-\end{cmdsubsub}
+\begin{confitem}{interact\_switch}{\choice{true, false}}[default: \code{true}]
+Turn on or off interaction. Turning interaction off prevents Texdoc from asking
+you to choose a file to view when there are multiple choices, so it just prints
+the list of files found.
+\end{confitem}
-Turn on or off interaction. Default is on. Turning interaction off prevents
-Texdoc from asking you to choose a file to view when there are multiple
-choices, so it just prints the list of files found.
+\begin{confitem}{suffix\_list}{\meta{list}}[default: empty]
+Set the list of known suffixes to |«list»| (see
+Section~\ref{sec:common-names}). Default is the empty list, but see the
+shipped configuration file for more.
+\end{confitem}
-\begin{cmdsubsub}{suffix_list}{cf-suffix_list}
- suffix_list = «list»
-\end{cmdsubsub}
-
-Set the list of known suffixes to |«list»| (see~\ref{ss-variants}). Default is
-the empty list, but see the shipped configuration file for more.
-
-\begin{cmdsubsub}{ext_list}{cf-ext_list}
- ext_list = «list»
-\end{cmdsubsub}
-
-Set the list of recognised extensions to |«list»|. The default value is:
+\begin{confitem}{ext\_list}
+ {\meta{list}}[default: \code{pdf, html, htm, txt, md, dvi, ps,}]
+Set the list of recognised extensions to |«list»|. This list is used to filter
+and sort the results that have the same score (with the default value: pdf
+first, etc). Two special values are recognised:
%
-\begin{htcode}
- pdf, html, htm, txt, md, dvi, ps,
-\end{htcode}
-%
-This list is used to filter and sort the results that have the same
-score (with the default value: pdf first, etc). Two special values are
-recognised:
\begin{itemize}
- \item \emph{The empty element}. This means files without extensions, or more
- precisely without a dot in their name. This is meant for files like
- |README|, etc. The file is assumed to be plain text for viewing purpose.
- \item |*| means any extension. Of course if it is present in the list, it
- can be the only element!
+\item \emph{The empty element}. This means files without extensions, or more
+ precisely without a dot in their name. This is meant for files like
+ |README|, etc. The file is assumed to be plain text for viewing purpose.
+\item |*| means any extension. Of course if it is present in the list, it
+ can be the only element!
\end{itemize}
There is a very special case: if the searched |«name»| has |.sty| extension,
@@ -669,94 +588,78 @@
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, md, dvi, ps,
- viewer_1 = man
- viewer_5 = man
+ext_list = pdf, html, htm, 1, 5, txt, md, dvi, ps,
+viewer_1 = man
+viewer_5 = man
\end{htcode}
As a special case, if the extension is |sty|, then the |txt| viewer is used;
similarly, if it is |htm| the |html| viewer is used. Otherwise, the |txt|
viewer is used and a warning is issued.
+\end{confitem}
-\begin{cmdsubsub}{badext_list}{cf-badext_list}
- badext_list = «list»
-\end{cmdsubsub}
+\begin{confitem}{badext\_list}{\meta{list}}[default: \code{txt}]
+Set the list of ``bad'' extensions to |«list»|. Files with those extensions get
+a malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
-Set the list of ``bad'' extensions to |«list»|. Default is ``|txt,|''. Files
-with those extensions get a malus of |1| on their heuristic score if it was
-previously positive.
+\begin{confitem}{basename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
+Set the list of ``known'' base names to |«list»|. 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.
+\end{confitem}
-\begin{cmdsubsub}{basename_list}{cf-basename_list}
- basename_list = «list»
-\end{cmdsubsub}
+\begin{confitem}{badbasename\_list}
+ {\meta{list}}[default: \code{readme, 00readme}]
-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.
+Set the list of ``bad'' base names to |«list»|. Files with those names get a
+malus of |1| on their heuristic score if it was previously positive.
+\end{confitem}
-\begin{cmdsubsub}{badbasename_list}{cf-badbasename_list}
- badbasename_list = «list»
-\end{cmdsubsub}
+\begin{confitem}{viewer\_\meta{ext}}{\meta{command}}
+Set the viewer command for files with extension |«ext»| to |«command»|. For
+files without an extension, |viewer_txt| is used. Note that there is no
+|viewer_| variable. In |«command»|, |%s| can be used as a placeholder for the
+filename, which is otherwise inserted at the end of the command. The command
+can be an arbitrary shell construct.
+\end{confitem}
-Set the list of ``bad'' base names to |«list»|. Default is ``|readme|''. Files
-with those names get a malus of |1| on their heuristic score if it was
-previously positive.
+\begin{confitem}{lang}{\meta{2-letter code}}
+Set your preferred language. By default, it reflects your system's locale.
+\end{confitem}
-\begin{cmdsubsub}{viewer_*}{cf-viewer_*}
- viewer_«ext» = «cmd»
-\end{cmdsubsub}
-
-Set the viewer command for files with extension |«ext»| to |«cmd»|. For files
-without extension, |viewer_txt| is used, and there's no |viewer_| variable.
-In |«cmd»|, |%s| can be used as a placeholder for the file name, which is
-otherwise inserted at the end of the command. The command can be an arbitrary
-shell construct.
-
-\begin{cmdsubsub}{lang}{cf-lang}
- lang = «2-letter code»
-\end{cmdsubsub}
-
-Set you preferred language. Defaults to your system's locale.
-
-\begin{cmdsubsub}{verbosity_level}{cf-verbosity_level}
- verbosity_level = «n»
-\end{cmdsubsub}
-
-Set the verbosity level to |«n»| (default: 2). At level~3, errors, warnings and
-informational messages will be printed on stderr; 2 means only errors and
-warnings, 1 only errors and 0 nothing except internal errors (obviously not
+\begin{confitem}{verbosity\_level}{\meta{number}}[default: \code{2}]
+Set the verbosity level to |«number»|. 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).
+\end{confitem}
-\begin{cmdsubsub}{debug_list}{cf-debug_list}
- debug_list = «list»
-\end{cmdsubsub}
+\begin{confitem}{debug\_list}{\meta{list}}[default: empty]
+Set the list of activated debug categories. Available debug categories are
+|config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|, |view|,
+and |all| to activate all of these. Implies |--verbose|. Debug information are
+printed on standard error.
+\end{confitem}
-Set the list of activated debug items (default: none). Available debug items
-are |config|, |files|, |search|, |score|, |texdocs|, |tlpdb|, |version|,
-|view|, and |all| to activate all of these. Implies |--verbose|. Debug
-information are printed on standard error.
-
-\begin{cmdsubsub}{max_line}{cf-max_lines}
- max_lines = «number»
-\end{cmdsubsub}
-
+\begin{confitem}{max\_lines}{\meta{number}}[default: \code{20}]
Set the maximum number of results to be printed without confirmation in list,
-mixed or showall mode (default: 20). This setting has no effect if interaction
-is disabled.
+mixed or showall mode. This setting has no effect if interaction is disabled.
+\end{confitem}
-\begin{cmdsubsub}{machine_switch}{cf-machine_switch}
- machine_switch = «true, false»
-\end{cmdsubsub}
-
-Turn on or off machine-readable output (default: off). With this option
-active, the value of |interact_switch| is forced to |false|, and each line of
-output is
+\begin{confitem}{machine\_switch}{\choice{true, false}}[default: \code{false}]
+Turn on or off machine-readable output. With this option active, the value of
+|interact_switch| is forced to |false|, and each line of output is
+%
\begin{htcode}
- «argument»\t«score»\t«filename»
+«argument»\metatab«score»\metatab«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)
+(mainly useful if there were many arguments), {\metatab} is the tab (ASCII \#9)
character, and the other entries are pretty self-explanatory. Nothing else is
printed on stdout, except if an internal error occurs (in which case exit code
will be 1). In the future, more tab-separated fields may be added at the end
@@ -763,49 +666,45 @@
of the line, but the first 3 fields will remain unchanged.
Currently, there are two additional fields: a two-letter language code, and an
-unstructured description, both taken from the CTAN catalogue (via the \texlive
+unstructured description, both taken from the CTAN catalogue (via the {\TL}
database). These fields may be empty, and they are not guaranteed to keep the
same meaning in future versions of Texdoc.
+\end{confitem}
-\begin{cmdsubsub}{zipext_list}{cf-zipext_list}
- zipext_list = «list»
-\end{cmdsubsub}
+\begin{confitem}{zipext\_list}{\meta{list}}[default: empty]
+List of supported extensions for zipped files. Allows compressed files with
+names like |foobar.«zip»|, with |«zip»| in the given |«list»|, to be found and
+unzipped before the viewer is started (the temporary file will be destroyed
+right after).
-List of supported extensions for zipped files (default: empty). Allows
-compressed files with names like |foobar.«zip»|, with |«zip»| in the given
-|«list»|, to be found and unzipped before the viewer is started (the
-temporary file will be destroyed right after).
+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.
+At the same time, make sure you are using blocking (i.e., not returning
+immediately) viewers.
-\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. At the same time, make sure you are using blocking (i.e., not
-returning immediately) viewers.
+Remark: {\TL} doesn't ship compressed documentation files, so this option is
+mainly useful with re-packaged version of {\TL} that do, for example in Linux
+distributions.
+\end{confitem}
-\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{confitem}{unzip\_\meta{zipext}}{\meta{command}}[no default]
+The unzipping command for compressed files with extension |«zipext»|. Define
+one for each item in \ci{zipext\_list}. The command must print the result on
+stdout, like |gzip -d -c| does.
+\end{confitem}
-\begin{cmdsubsub}{unzip_*}{cf-unzip_star}
- unzip_«zipext» = «command»
-\end{cmdsubsub}
+\begin{confitem}{rm\_file}{\meta{command}}[default: \code{rm -f}]
+Commands for removing files on your system. Only useful for zipped documents
+(see \ci{zipext\_list}).
+\end{confitem}
-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{confitem}{rm\_dir}{\meta{command}}[default: \code{rmdir}]
+Commands for removing directories on your system. Also only useful for zipped
+documents (see \ci{zipext\_list}).
+\end{confitem}
-\begin{cmdsubsub}{rm_file, rm_dir}{cf-rm_star}
- rm_file = «command»
- rm_dir = «command»
-\end{cmdsubsub}
-
-Commands for removing files (resp. directories) on your system (defaults:
-|rm -f| and |rmdir|). Only useful for zipped documents (see |zipext_list|).
-
-\begin{cmdsubsub}{lastfile_switch}{cf-lastfile_switch}
- lastfile_switch = «true, false»
-\end{cmdsubsub}
-
+\begin{confitem}{lastfile\_switch}{\choice{true, false}}[default: \code{false}]
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
@@ -812,29 +711,28 @@
default configuration file from older versions to be used (see the
\href{https://github.com/TeX-Live/texdoc}{README} for instructions on how to do
so).
+\end{confitem}
-\begin{cmdsubsub}{fuzzy_level}{cf-fuzzy_level}
- fuzzy_level = «n»
-\end{cmdsubsub}
+\begin{confitem}{fuzzy\_level}{\meta{number}}[default: \code{5}]
+Set the allowance of Levenshtein distance to |«number»| for fuzzy search. At
+level~|0|, the fuzzy search feature is disabled.
+\end{confitem}
-Set the allowance of Levenshtein distance to |«n»| for the fuzzy search
-(default: 5). At level 0, the fuzzy search feature is disabled.
+\begin{confitem}{texlive\_tlpdb}{\meta{path}}[no default]
+This enables you to specify the |«path»| for the database |texlive.tlpdb| which
+Texdoc uses for searching documents. By default, Texdoc uses
+\path{TEXMFROOT/tlpkg/texlive.tlpdb}. Usually, you don't have to (or should
+not) set this configuration item. This is only useful when you want to use
+Texdoc within a {\TL}-based {\TeX} distribution which does not ship
+|texlive.tlpdb|.
+\end{confitem}
-\subsection{Exit codes}\label{ss-exit}
+\section{Licence}
+\label{sec:licence}
-The current exit codes are:
-\begin{enumerate}[start=0]
- \item Success.
- \item Internal error.
- \item Usage error.
- \item No documentation found.
-\end{enumerate}
+The current version of Texdoc program and its documentation are copyright
+2008--2020 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} Team.
-\section{Licence}\label{s-licence}
-
-The current version of Texdoc program and its documentation are copyright 2008
-Manuel Pégourié-Gonnard, Takuto Asakura, and the {\texlive} Team.
-
They are free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
@@ -851,17 +749,20 @@
\bigskip
Previous work (Texdoc program) in the public domain:
+%
\begin{itemize}
- \item Contributions from Reinhard Kotucha (2008).
- \item First texlua versions by Frank Küster (2007).
- \item Original shell script by Thomas Esser, David Aspinall, and Simon
- Wilkinson.
+\item Contributions from Reinhard Kotucha (2008).
+\item First texlua versions by Frank K\"uster (2007).
+\item Original shell script version by Thomas Esser, David Aspinall, and Simon
+ Wilkinson.
\end{itemize}
\bigskip
-\begin{center}\Large\bfseries
- Happy {\TeX}ing!
+
+\begin{center}
+\Large\bfseries
+Happy {\TeX}ing!
\end{center}
\end{document}
-% vim: ambiwidth=single spell:
+% vim: set ambiwidth=single spell:
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoc.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoc.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoc.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -7,11 +7,39 @@
-- Note: we keep this file small as much as possible so that make it easier
-- to install a new version of texdoc in TEXMFHOME.
--- setup the kpse library and load texdoclib
+local lfs = require 'lfs'
+local kpse = require 'kpse'
+
+-- setup kpse library
kpse.set_program_name(arg[-1], 'texdoc')
-local texdoc = require('texdoclib')
--- execute
+-- get realpath of this file
+local function realpath(p)
+ if os.type == 'unix' then
+ local h = io.popen(string.format("realpath '%s'", p))
+ local r = h:read('*a')
+ h:close()
+ return r:gsub('\n$', '')
+ else
+ return ''
+ end
+end
+local file = realpath(arg[0])
+
+-- if the file is not in TEXMFMAIN, set temporal TEXMFAUXTREES and TEXMFDIST
+local texmf = file:match('^(.*/texmf[^/]*)/scripts/texdoc/texdoc.tlu$')
+if texmf ~= nil then
+ if texmf ~= kpse.var_value('TEXMFMAIN') then
+ io.stderr:write('Info: ' ..
+ 'Running Texdoc not installed in the current TEXMFMAIN.\n')
+ os.setenv('TEXMFAUXTREES', texmf .. ',')
+ os.setenv('TEXMFDIST', ',')
+ end
+end
+
+-- load the library and execute
+local texdoc = require 'texdoclib'
+assert(texdoc.cli, 'Internal error: Texdoc is not installed properly.')
texdoc.cli.exec()
-- vim: ft=lua:
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-alias.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -5,7 +5,7 @@
--[[ structure of the alias table
alias = {
- name1 = {<true or nill> stop, <aliasentry> aliasentry1, ...},
+ name1 = {<true or nil> stop, <aliasentry> aliasentry1, ...},
...
}
stop == true means further alias directives should be ignored
@@ -22,7 +22,7 @@
-- dependencies
local texdoc = {
- config = require('texdoclib-config'),
+ config = require 'texdoclib-config',
}
-- shortcuts
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-cli.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -4,11 +4,11 @@
-- dependencies
local texdoc = {
- const = require('texdoclib-const'),
- util = require('texdoclib-util'),
- config = require('texdoclib-config'),
- search = require('texdoclib-search'),
- view = require('texdoclib-view'),
+ const = require 'texdoclib-const',
+ util = require 'texdoclib-util',
+ config = require 'texdoclib-config',
+ search = require 'texdoclib-search',
+ view = require 'texdoclib-view',
}
-- shortcuts
@@ -21,7 +21,7 @@
-- modified Alternative GetOpt
-- cf. http://lua-users.org/wiki/AlternativeGetOpt
local function getopt(arg, options)
- local tmp
+ local tmp = nil
local tab = {}
local saved_arg = {table.unpack(arg)}
@@ -30,25 +30,36 @@
table.remove(arg, 1)
local x = string.find(v, '=', 1, true)
if x then
- table.insert(tab, {string.sub(v, 3, x-1), string.sub(v, x+1)})
+ table.insert(tab, {string.sub(v, 3, x - 1), string.sub(v, x+1)})
else
table.insert(tab, {string.sub(v, 3), true})
end
+
elseif string.sub(v, 1, 1) == '-' then
table.remove(arg, 1)
local y = 2
local l = string.len(v)
local jopt
+
while (y <= l) do
jopt = string.sub(v, y, y)
+
if string.find(options, jopt, 1, true) then
if y < l then
- tmp = string.sub(v, y+1)
+ tmp = string.sub(v, y + 1)
y = l
else
table.remove(arg, 1)
tmp = saved_arg[k + 1]
end
+
+ -- check the existence of an argument
+ if not tmp then
+ err_print('error',
+ 'Option -%s requires an argument.', jopt)
+ os.exit(C.exit_error)
+ end
+
if string.match(tmp, '^%-') then
table.insert(tab, {jopt, false})
else
@@ -59,6 +70,9 @@
end
y = y + 1
end
+
+ else
+ if tmp then tmp = nil else break end
end
end
@@ -67,7 +81,6 @@
local function parse_options()
local curr_arg
- local action = true
local cl_config = {}
local function insert_cl_config(key, val, opt_name)
@@ -87,13 +100,13 @@
-- action
if (curr_arg == '-h') or (curr_arg == '--help') then
- action = 'help'
+ return true, 'help', cl_config
elseif (curr_arg == '-V') or (curr_arg == '--version') then
- action = 'version'
+ return true, 'version', cl_config
elseif (curr_arg == '-f') or (curr_arg == '--files') then
- action = 'files'
+ return true, 'files', cl_config
elseif curr_arg == '--just-view' then
- action = 'view'
+ return true, 'view', cl_config
-- mode
elseif (curr_arg == '-w') or (curr_arg == '--view') then
@@ -117,8 +130,7 @@
-- config
elseif curr_arg == '-c' then
- local item, value = string.match(v, '^([%a%d_]+)%s*=%s*(.+)')
- insert_cl_config(item, value, curr_arg)
+ insert_cl_config(v, nil, curr_arg)
-- debug
elseif (curr_arg == '-d') or (curr_arg == '--debug') then
@@ -141,7 +153,7 @@
end
end
- return action, cl_config
+ return true, action, cl_config
end
-------------------------- process execution --------------------------
@@ -157,7 +169,7 @@
'\n\n' .. C.copyright_msg)
os.exit(C.exit_ok)
elseif action == 'files' then
- print(C.fullname .. ' ' .. C.version)
+ print(texdoc.util.w32_path(C.fullname) .. ' ' .. C.version)
texdoc.config.show_config_files(true)
os.exit(C.exit_ok)
elseif action == 'view' then
@@ -189,9 +201,9 @@
function M.exec()
-- parsing command line options
- local action, cl_config = parse_options()
+ local ok, action, cl_config = parse_options()
- if not action then
+ if not ok then
os.exit(C.exit_usage)
end
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-config.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -2,9 +2,12 @@
--
-- The TeX Live Team, GPLv3, see texdoclib.tlu for details
+-- dependencies
+local lfs = require 'lfs'
+
-- shortcuts
local M = {}
-local C = require('texdoclib-const')
+local C = require 'texdoclib-const'
-- config is local to this file
local config = {}
@@ -172,8 +175,20 @@
-- Note: Make sure to set a default value in setup_config_from_defaults()
-- if relevant.
local function setup_config_from_cl(cl_config)
+ local err_print = import_function('util', 'err_print')
+
for _, e in ipairs(cl_config) do
- set_config_element(e[1], e[2], {src='cl', name=e[3]})
+ if e[3] == '-c' then
+ local item, value = string.match(e[1], '^([%a%d_]+)%s*=%s*(.+)')
+ if item and value then
+ set_config_element(item, value, {src='cl', name='-c'})
+ else
+ err_print('warning',
+ 'Invalid argument "%s" for Option -c. Ignoring.', e[1])
+ end
+ else
+ set_config_element(e[1], e[2], {src='cl', name=e[3]})
+ end
end
end
@@ -184,6 +199,7 @@
local function set_config_elt_from_vars(key, vars)
for _, var in ipairs(vars) do
local value = os.getenv(var)
+ value = value and string.gmatch(value, '([^:]+)')()
if value then
set_config_element(key, value, {src='env', name=var})
end
@@ -316,7 +332,7 @@
or function(s) dbg_print('files', s) end
-- show the list of configuration files
- print_func('Configuration files are:')
+ print_func('Configuration file(s):')
for i, file in ipairs(config_files) do
-- if not verbose, do not show "not found" files for -f
if file.status ~= "not found"
@@ -329,7 +345,7 @@
if is_action then
print_func('Recommended file(s) for personal settings:')
local sep = (os.type == 'windows') and ';' or ':'
- local texmfhomes = string.explode(kpse.var_value('TEXMFHOME'), sep)
+ local texmfhomes = string.explode(kpse.expand_path('$TEXMFHOME'), sep)
for _, home in ipairs(texmfhomes) do
print_func(indent .. w32_path(home .. '/texdoc/texdoc.cnf'))
end
@@ -340,12 +356,20 @@
---------------------- config from locale settings -------------------------
+-- set up the locale from the system setting
+-- Note that luatex set the locale to a neutral value for a reason, so we need
+-- to set the locale (for the category 'all') to nil to ignore it.
local function setup_config_from_locale()
- local current = os.setlocale(nil, 'all')
- os.setlocale('', 'all')
- local native = os.setlocale(nil, 'time')
- os.setlocale(current, 'all')
- local lang = string.match(native, '^[a-z][a-z]')
+ local current, native, lang
+ current = os.setlocale(nil, 'all') -- save the default value
+ os.setlocale('', 'all') -- set it to nil temporary
+ native = os.setlocale(nil, 'all') -- get the actual system locale
+ os.setlocale(current, 'all') -- put back the default value
+ if native == 'C' then -- the default C locale is en
+ lang = 'en'
+ else
+ lang = string.match(native, '^[a-z][a-z]')
+ end
if lang then
set_config_element('lang', lang, {src='loc'})
end
@@ -381,6 +405,8 @@
end
if os.getenv('GNOME_DESKTOP_SESSION_ID')
or string.match(xdg_current_desktop, '.*GNOME.*') then -- gnome
+ if is_in_path('gio') then return '(gio open %s) &' end
+ -- followings are deplecated commands but keep these for compatibility
if is_in_path('gvfs-open') then return '(gvfs-open %s) &' end
if is_in_path('gnome-open') then return '(gnome-open %s) &' end
end
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-const.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -4,7 +4,7 @@
-- use an empty environment that will become texdoc_env.C (see EOF)
local constants = {}
-local kpse = kpse
+local kpse = kpse or require 'kpse'
local setfenv = setfenv
local texdoc_env
@@ -21,14 +21,14 @@
-- progname and version
fullname = kpse.find_file('texdoc/texdoclib', 'lua')
progname = 'Texdoc'
-version = '3.1'
-release_date = '2019-03-28'
+version = '3.2'
+release_date = '2020-02-02'
-- 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...
- or: texdoc [OPTION...] ACTION
+Usage: texdoc [OPTION]... NAME...
+ or: texdoc [OPTION]... ACTION
Try to find appropriate TeX documentation for the specified NAME(s).
Alternatively, perform the given ACTION and exit.
@@ -63,7 +63,7 @@
Please email bugs to <texdoc at tug.org>.]]
copyright_msg = [[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.]]
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-score.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -3,14 +3,14 @@
-- The TeX Live Team, GPLv3, see texdoclib.tlu for details
-- dependencies
+local md5 = require 'md5'
local texdoc = {
- util = require('texdoclib-util'),
- config = require('texdoclib-config'),
+ util = require 'texdoclib-util',
+ config = require 'texdoclib-config',
}
-- shortcuts
local M = {}
-local dbg_print = texdoc.util.dbg_print
-- shared variables
local global_adjscore, spec_adjscore = {}, {}
@@ -73,18 +73,19 @@
end
-- compute a heuristic score -10 <= s < 10
-local function heuristic_score(file, pat)
- dbg_print('score', 'Start heuristic scoring with pattern: ' .. pat)
+local function heuristic_score(file, pat, dbg_score)
+ dbg_score('Start heuristic scoring with pattern: ' .. pat)
+
-- score management
local score = -10
local function upscore(s, reason, force)
if s > score or force then
score = s
- dbg_print('score',
- 'New heuristic score: %.1f. Reason: %s', s, reason)
+ dbg_score('New heuristic score: %.1f. Reason: %s', s, reason)
end
end
local slash = not not string.find(pat, '/', 1, true)
+
-- look for exact or subword match
if M.is_exact_locale(file, pat) then
upscore(5, 'exact match with correct locale')
@@ -93,32 +94,37 @@
elseif is_subword(file, pat) then
upscore(1, 'subword match')
end
+
-- try derivatives unless pat contains a slash
if not slash then
for _, suffix in ipairs(texdoc.config.get_value('suffix_list')) do
- local deriv = pat..suffix
+ local deriv = pat .. suffix
if M.is_exact(file, deriv) then
- upscore(3, 'exact match for derived pattern: ' .. deriv)
+ upscore(4.5, 'exact match for derived pattern: ' .. deriv)
elseif is_subword(file, deriv) then
- upscore(2, 'subword match for derived pattern: ' .. deriv)
+ upscore(3.5, 'subword match for derived pattern: ' .. deriv)
end
end
end
+
-- if extension is bad, score becomes an epsilon
local ext = texdoc.config.get_value('ext_list')[M.ext_pos(file)]
if ext and texdoc.config.get_value('badext_list_inv')[ext] and score > 0 then
upscore(0.1, 'bad extension', true)
end
+
-- if basename is bad, score becomes an epsilon
if has_bad_basename(file) and score > 0 then
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
upscore(score + 1.5, 'directory bonus')
end
+
-- done
- dbg_print('score', 'Final heuristic score: %.1f', score)
+ dbg_score('Final heuristic score: %.1f', score)
return score
end
@@ -125,72 +131,84 @@
-- set the score of a docfile
local function set_score(df, original_kw)
-- scoring is case-insensitive (patterns are already lowercased)
- local name = string.lower(df.shortname)
- dbg_print('score', '----------')
- dbg_print('score', 'Start scoring ' .. df.realpath)
- dbg_print('score', 'Name used: ' .. name)
+ local name = string.lower(df.normname)
+ local df_id = string.sub(md5.sumhexa(name), 1, 7)
+
+ -- special debugging function
+ local function dbg_score(msg, ...)
+ -- add the hash id prefix to make the outputs grep-friendly
+ local msg = string.format('(%s) ', df_id) .. msg
+ texdoc.util.dbg_print('score', msg, ...)
+ end
+
+ dbg_score('Start scoring ' .. df.realpath)
+ dbg_score('Name used: ' .. name)
+
-- get score from patterns
local score = -10
for _, pat in ipairs(df.matches) do
local s = -10
local p = string.lower(pat.name)
- if pat.original then
- s = df.tree > -1 and heuristic_score(name, p) or 1
- elseif M.is_exact(name, p) then
+ if pat.original then -- non-alias
+ s = df.tree > -1 and heuristic_score(name, p, dbg_score) or 1
+ elseif M.is_exact(name, p) then -- alias
local bonus, note = 0, ''
if pat.locale then
bonus, note = 5, ', (language-based)'
end
- s = (pat.score or 10) + bonus -- default alias score is 10
- dbg_print('score',
- 'Matching alias "%s", score: %.1f%s', pat.name, s, note)
+ s = (pat.score or 10) + bonus -- default alias score is 10
+ dbg_score('Matching alias "%s", score: %.1f%s', pat.name, s, note)
end
if s > score then score = s end
end
- dbg_print('score', 'Max pattern score: %.1f', score)
+ dbg_score('Max pattern score: %.1f', score)
+
-- get score from tlp associations
if score == -10 and df.tlptodoc then
score = -1
- dbg_print('score',
- 'New score: %.1f from package name association', score)
+ dbg_score('New score: %.1f from package name association', score)
end
+
if score == -10 and df.runtodoc then
score = -5
- dbg_print('score',
- 'New score: %.1f from sty/cls association', score)
+ dbg_score('New score: %.1f from sty/cls association', score)
end
+
-- bonus for metadata
if df.details then
if string.find(string.lower(df.details), 'readme') then
score = score + 0.1
- dbg_print('score', 'Catalogue "readme" bonus: +0.1')
+ dbg_score('Catalogue "readme" bonus: +0.1')
else
score = score + 1.5
- dbg_print('score', 'Catalogue details bonus: +1.5')
+ dbg_score('Catalogue details bonus: +1.5')
end
end
+
-- adjust from keyword-specific tables
if df.tree > -1 and spec_adjscore[original_kw] then
for pat, val in pairs(spec_adjscore[original_kw]) do
if val and is_subword('/' .. name, pat) then
score = score + val
- dbg_print('score',
- 'Adjust by %.1f from specific pattern "%s"', val, pat)
+ dbg_score('Adjust by %.1f from specific pattern "%s"', val, pat)
end
end
end
+
-- adjust from global tables
if df.tree > -1 then
for pat, val in pairs(global_adjscore) do
if val and is_subword('/' .. name, pat) then
if score > -10 or val < 0 then score = score + val end
- dbg_print('score',
- 'Adjust by %.1f from global pattern "%s"', val, pat)
+ dbg_score('Adjust by %.1f from global pattern "%s"', val, pat)
end
end
end
- dbg_print('score', 'Final score: %.1f', score)
- df.score = score
+
+ dbg_score('Final score: %.1f', score)
+
+ -- the final score should be a float value
+ df.score = score + 0.0
end
-- set the scores for a doclist
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib-search.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -5,12 +5,14 @@
-- Warning: Some functions here assume that M.init_databases() has been called.
-- dependencies
+local kpse = require 'kpse'
+local lfs = require 'lfs'
local texdoc = {
- const = require('texdoclib-const'),
- util = require('texdoclib-util'),
- alias = require('texdoclib-alias'),
- score = require('texdoclib-score'),
- config = require('texdoclib-config'),
+ const = require 'texdoclib-const',
+ util = require 'texdoclib-util',
+ alias = require 'texdoclib-alias',
+ score = require 'texdoclib-score',
+ config = require 'texdoclib-config',
}
-- shortcuts
@@ -24,11 +26,11 @@
local s_meta -- {[normname] = meta, ...} (populated by init_tlp_database)
local vanilla -- is this a vanilla TL or a re-package one without tlpdb?
----------------------------- utility functions -----------------------------
+--------------------------- utility functions ----------------------------
-- find the TeX Live root
local function get_tlroot()
- local tlroot = kpse.var_value('TEXMFROOT')
+ local tlroot = kpse.expand_path('$TEXMFROOT') -- it should be exisitng one
get_tlroot = function() return tlroot end
return tlroot
end
@@ -36,7 +38,7 @@
-- says if file has a known extension according to ext_list
-- (or known basename according to basename_list)
local function check_ext(file)
- file = string.lower(file)
+ file = file:lower()
-- remove zipext if applicable
file = texdoc.util.parse_zip(file)
-- then do the normal thing
@@ -44,12 +46,12 @@
if e == '*' then
return true
elseif (e == '') then
- if not string.find(file, '.', 1, true) then
+ if not file:find('.', 1, true) then
return true
end
else
- local dot_e = '.'..e
- if string.sub(file, -string.len(dot_e)) == dot_e then
+ local dot_e = '.' .. e
+ if file:sub(-#dot_e) == dot_e then
return true
end
end
@@ -63,7 +65,7 @@
return false
end
------------------------ docfile and doclist objects ------------------------
+---------------------- docfile and doclist objects -----------------------
--[[
doclist = {
@@ -128,7 +130,6 @@
-- those are virtual members, see below
realpath = full path
normname = nomrmalised (path removed up to the 'doc' component)
- shortname = short name used for scoring
basename = basename
lang = language tag from the catalogue metadata
details = details tag from the catalogue metadata
@@ -201,7 +202,7 @@
-- normalise a name from the tlpdb (use for s_meta indexes)
local function reloc_tlpdb_path(name)
- return string.gsub(name, '^texmf[^/]*/doc/', '', 1)
+ return name:gsub('^texmf[^/]*/doc/', '')
end
-- return normalised name
@@ -221,16 +222,9 @@
return meta and (meta.details or false) or false
end
--- return the short name used for scoring
-function Docfile:get_shortname()
- if self.tree == -1 then return self.name end
- -- remove first component of name if at least two directory levels
- return string.match(self.normname, '^..-/(.+/.+)$') or self.normname
-end
-
-- return the base name
function Docfile:get_basename()
- return string.gsub(self.name, '.*/', '', 1)
+ return self.name:gsub('.*/', '')
end
-- for interface consistency, matches should always be a table, never nil
@@ -246,12 +240,12 @@
return texdoc.score.ext_pos(self.basename)
end
--------------------- select results from TEXDOCS trees ---------------------
+------------------- select results from TEXDOCS trees --------------------
-- says if a file (with its path) matches a pattern
local function matches(pattern, file)
if pattern.original then
- return string.find(file:lower(), pattern.name:lower(), 1, true)
+ return file:lower():find(pattern.name:lower(), 1, true)
else
return texdoc.score.is_exact(file, pattern.name)
end
@@ -296,7 +290,7 @@
-- scan it
local db = {}
- local maybe_dir, isdoc = true, false
+ local maybe_dir, is_doc = true, false
local current_dir
local l = #shift
while true do
@@ -303,18 +297,21 @@
local line = lsr:read('*line')
while line == '' do line, maybe_dir = lsr:read('*line'), true end
if line == nil then break end -- EOF
- local dir_line = maybe_dir and string.match(line, '^%./(.*):$')
+ local dir_line = maybe_dir and line:match('^%./(.*):$')
if dir_line then
maybe_dir = false -- next line may not be a dir
if string.sub(dir_line .. '/', 1, l) == shift then
- isdoc = true
- current_dir = string.sub(dir_line, l+1)
+ is_doc = true
+ current_dir = dir_line:sub(l + 1)
db[current_dir] = nil
- elseif isdoc then
+ elseif is_doc then
break -- we're exiting the ./doc (or shift) dir, so it's over
end
- elseif isdoc then
- local file = (current_dir == '') and line or current_dir .. '/' .. line
+ elseif is_doc then
+ local file = line
+ if current_dir ~= '' then
+ file = current_dir .. '/' .. line
+ end
if check_ext(line) then db[file] = line end
end
end
@@ -361,14 +358,14 @@
local function lsr_root(path)
if not lfs.isdir (path) then return end
local root, shift = path, ''
- if string.sub(root, -1) == '/' then root = string.sub(root, 1, -2) end
- while string.find(root, '/', 1, true) do
+ if root:sub(-1) == '/' then root = root:sub(1, -2) end
+ while root:find('/', 1, true) do
if lfs.isfile(root .. '/ls-R') then
return root, shift
end
- local last_comp = string.match(root, '^.*/(.*)$')
+ local last_comp = root:match('^.*/(.*)$')
-- /!\ cannot put last_comp in a regex: can contain special char
- root = string.sub(root, 1, - (#last_comp + 2))
+ root = root:sub(1, - (#last_comp + 2))
shift = last_comp .. '/' .. shift
end
end
@@ -375,10 +372,10 @@
doc_roots = {}
local sep = (os.type == 'windows') and ';' or ':'
- local kpse_texdocs = kpse.expand_var("$TEXDOCS")
+ local kpse_texdocs = kpse.expand_var('$TEXDOCS')
-- expand the path and turn it into a lua list
- local raw_doc_roots = string.explode(kpse.expand_braces(kpse_texdocs), sep)
+ local raw_doc_roots = kpse.expand_braces(kpse_texdocs):explode(sep)
local max = #raw_doc_roots + 1
for j, dir in ipairs(raw_doc_roots) do
@@ -387,9 +384,9 @@
local path, db
-- get path, !! and // values
- dir, n = string.gsub (dir, '//$', '')
+ dir, n = dir:gsub('//$', '')
local recursion_allowed = (n == 1)
- local path, n = string.gsub (dir, '^!!', '')
+ local path, n = dir:gsub('^!!', '')
local index_mandatory = (n == 1)
dbg_print('texdocs',
'texdocs[%d] = %s (index_mandatory=%s, recursion_allowed=%s)',
@@ -426,7 +423,7 @@
end -- end scope of doc_roots
----------------------------- look for sty files ----------------------------
+--------------------------- look for sty files ---------------------------
-- add doclist entries for sty files in patlist
local function get_doclist_sty(patlist)
@@ -443,7 +440,7 @@
end
end
--------------------------------- use tlpdb ---------------------------------
+------------------------------- use tlpdb --------------------------------
-- tlpdb mean TeX Live Package DataBase and tlp means TeX Live Package
@@ -493,23 +490,23 @@
local curr_tlp
local state = 'none'
for line in io.lines(filename) do
- if state == 'none' and string.find(line, '^name ') then
+ if state == 'none' and line:find('^name ') then
-- begin a new package
- curr_tlp = string.lower(string.sub(line, 6, -1))
+ curr_tlp = line:sub(6, -1):lower()
tlp_doclist[curr_tlp] = {}
elseif state == 'docfiles' then
- if not string.find(line, '^ ') then
+ if not line:find('^ ') then
state = 'none'
else
- local file = string.match(line, '^ ([^ ]*)')
- local meta = string.match(line, '^ [^ ]* (.+)')
- local basename = string.match(file, '([^/]*)$')
+ local file = line:match('^ ([^ ]*)')
+ local meta = line:match('^ [^ ]* (.+)')
+ local basename = file:match('([^/]*)$')
if check_ext(basename) then
-- we've got a docfile here, add it
table.insert(tlp_doclist[curr_tlp], file)
if meta then
- local details = string.match(meta, 'details="([^"]+)"')
- local lang = string.match(meta, 'language="([^"]+)"')
+ local details = meta:match('details="([^"]+)"')
+ local lang = meta:match('language="([^"]+)"')
s_meta[reloc_tlpdb_path(file)] = {
details = details,
lang = lang,
@@ -518,13 +515,13 @@
end
end
elseif state == 'runfiles' then
- if not string.find(line, '^ ') then
+ if not line:find('^ ') then
state = 'none'
else
-- check for interesting runfiles
- local e = string.sub(line, -4, -1)
+ local e = line:sub(-4, -1)
if e == '.tex' or e == '.sty' or e == '.cls' then
- local f = string.match(line, '.*/(.*)%.')
+ local f = line:match('.*/(.*)%.')
tlp_from_runfile[f] = tlp_from_runfile[f] or {}
tlp_from_runfile[f][curr_tlp] = true
end
@@ -531,9 +528,9 @@
end
end
-- update state
- if string.find(line, '^docfiles ') then
+ if line:find('^docfiles ') then
state = 'docfiles'
- elseif string.find(line, '^runfiles ') then
+ elseif line:find('^runfiles ') then
state = 'runfiles'
end
end
@@ -658,8 +655,8 @@
-- get tlpinfo tables initialised by whatever mean
local function init_tlp_database()
- local TEXMFVAR = kpse.var_value('TEXMFVAR')
- local cache_file = TEXMFVAR .. '/' .. C.cache_name
+ -- we assume TEXMFVAR always consists of an element
+ local cache_file = kpse.expand_var('$TEXMFVAR/' .. C.cache_name)
-- set vanilla and detect texlive.tlpdb to use
local texlive_tlpdb = get_tlroot() .. '/tlpkg/texlive.tlpdb'
@@ -686,7 +683,8 @@
dbg_print('tlpdb', 'Using cached data from ' .. cache_file)
get_tlpinfo_from_cache(cache_file)
else
- dbg_print('tlpdb', 'Getting data from tlpdb file ' .. texlive_tlpdb)
+ dbg_print('tlpdb',
+ 'Getting data from tlpdb file ' .. texlive_tlpdb)
get_tlpinfo_from_tlpdb(texlive_tlpdb)
dbg_print('tlpdb', 'Writing data in cache file ' .. cache_file)
local ok, msg = mkdir_p(texdoc.util.path_parent(cache_file))
@@ -704,7 +702,7 @@
end
end
------------------------------- main function -------------------------------
+----------------------------- main function ------------------------------
-- initialise the various databases (must be called first)
function M.init_databases()
@@ -714,11 +712,13 @@
-- find docfiles according to pattern
function M.get_doclist(pattern, no_alias)
+ dbg_print('search', 'Searching documents for pattern "%s"', pattern)
+
-- separate sty patterns from the rest
local function normal_vs_sty(list)
local normal, sty = {}, {}
for _, p in ipairs(list) do
- if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then
+ if p.name:lower():match('%.([^/.]*)$') == 'sty' then
table.insert(sty, p)
else
table.insert(normal, p)
Modified: trunk/Master/texmf-dist/scripts/texdoc/texdoclib.tlu
===================================================================
--- trunk/Master/texmf-dist/scripts/texdoc/texdoclib.tlu 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/scripts/texdoc/texdoclib.tlu 2020-02-02 22:44:20 UTC (rev 53643)
@@ -1,7 +1,7 @@
-- texdoclib.tlu: the texdoc library
--[[
-Copyright 2008 Manuel Pégourié-Gonnard, Takuto Asakura, and the TeX Live Team.
+Copyright 2008-2020 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
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
Modified: trunk/Master/texmf-dist/texdoc/texdoc.cnf
===================================================================
--- trunk/Master/texmf-dist/texdoc/texdoc.cnf 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/texmf-dist/texdoc/texdoc.cnf 2020-02-02 22:44:20 UTC (rev 53643)
@@ -141,6 +141,9 @@
adjscore /figures/ = -3
adjscore /images/ = -3
+# latex-dev stuff are less important than stable ones
+adjscore /latex-dev/ = -2
+
# readme files usually get negative scores because they have bad extensions,
# but they're still slightly better than other results with negative scores
adjscore readme = +0.1
@@ -165,7 +168,15 @@
adjscore(latex) Content_LaTeX_Package_Demo = -10
adjscore(latex) example_latex = -10
adjscore(latex) test_latex = -10
+# dir names
+adjscore(latex) /latex/ = -4
+adjscore(latex) /latex-dev/ = -5
+adjscore(latex) /generic/ = -5
+# prioritize official documents for 'latex'
+adjscore(latex) /latex/base/ = +5
+adjscore(latex) /latex/tools/ = +5
+
# beamer
adjscore(beamer) beamer-tut-pt/tutorialbeamer = +10
adjscore(beamer) beamer-FUBerlin = -3
@@ -206,11 +217,47 @@
# To override one of the settings below, use the 'noalias' directive in
# your personal configuration file, see the manual for details.
-## Essential documentation
+## TeX Live documentation
+# texlive-en for general, but prioritized local version if exists
+alias texlive = texlive-en
+alias texlive-cz = texlive-cz
+alias texlive-de = texlive-de
+alias texlive-en = texlive-en
+alias texlive-es = texlive-es
+alias texlive-fr = texlive-fr
+alias texlive-it = texlive-it
+alias texlive-ja = texlive-ja
+alias texlive-pl = texlive-pl
+alias texlive-ru = texlive-ru
+alias texlive-sr = texlive-sr
+alias texlive-zh-cn = texlive-zh-cn
+
alias live = texlive-en
-alias texlive = texlive-en
+alias live-cz = texlive-cz
+alias live-de = texlive-de
+alias live-en = texlive-en
+alias live-es = texlive-es
+alias live-fr = texlive-fr
+alias live-it = texlive-it
+alias live-ja = texlive-ja
+alias live-pl = texlive-pl
+alias live-ru = texlive-ru
+alias live-sr = texlive-sr
+alias live-zh-cn = texlive-zh-cn
+
alias tex-live = texlive-en
+alias tex-live-cz = texlive-cz
+alias tex-live-de = texlive-de
+alias tex-live-en = texlive-en
+alias tex-live-es = texlive-es
+alias tex-live-fr = texlive-fr
+alias tex-live-it = texlive-it
+alias tex-live-ja = texlive-ja
+alias tex-live-pl = texlive-pl
+alias tex-live-ru = texlive-ru
+alias tex-live-sr = texlive-sr
+alias tex-live-zh-cn = texlive-zh-cn
## various stuff
@@ -281,6 +328,10 @@
alias tracefnt = source2e
# TODO: try to avoid the huge amount of false positives for `doc' itself.
+# latex-dev instruction
+alias latex-dev = latex/base/ltnews30
+alias(9) latex-dev = latex-dev.man1
+
# latex's required graphics bundle
alias color-dev = color
alias epsfig-dev = epsfig
@@ -374,7 +425,8 @@
alias l3prop = interface3
alias l3box = interface3
alias l3coffins = interface3
-alias l3color = interface3
+alias l3color-base = interface3
+alias l3regex = interface3
alias l3msg = interface3
alias l3keys = interface3
alias l3file = interface3
@@ -386,6 +438,8 @@
alias afoot = arabtex-doc
alias arabicfont = bezos
alias bibtex = btxdoc
+alias btxdoc-ja = jbtxdoc
+alias btxhak-ja = jbtxhak
alias changes = changes.english.pdf
alias cm = cm/README
alias(5) cmsuper = cm-super/FAQ
Modified: trunk/Master/tlpkg/libexec/ctan2tds
===================================================================
--- trunk/Master/tlpkg/libexec/ctan2tds 2020-02-02 22:42:37 UTC (rev 53642)
+++ trunk/Master/tlpkg/libexec/ctan2tds 2020-02-02 22:44:20 UTC (rev 53643)
@@ -2042,6 +2042,7 @@
'tex-ini-files','\.(dat|ini|tex)$',
'tex-ps', '\.tex',
'texapi', 'texapi\.tex',
+ 'texdoc', 'NULL', # not texdoc-doc.cls
'texdraw', 'tex$|' . $standardtex,
'texosquery', '\.tex$|' . $standardtex,
'texproposal', 'NULL',
More information about the tex-live-commits
mailing list.