summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texdoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-02-19 21:04:06 +0000
committerKarl Berry <karl@freefriends.org>2023-02-19 21:04:06 +0000
commit7fc43fa7c4058476ba50cf5d5432dc4274bcb8ae (patch)
tree9e6fdabab458f9e46eeab56bf8386bc8a5bd36c1 /Master/texmf-dist/doc/support/texdoc
parent2bc64030cbd7b6fb620691f21fda3cd1b24aeffa (diff)
texdoc (19feb23)
git-svn-id: svn://tug.org/texlive/trunk@65938 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/texdoc')
-rw-r--r--Master/texmf-dist/doc/support/texdoc/NEWS16
-rw-r--r--Master/texmf-dist/doc/support/texdoc/README.md38
-rw-r--r--Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls12
-rw-r--r--Master/texmf-dist/doc/support/texdoc/texdoc.pdfbin84314 -> 90076 bytes
-rw-r--r--Master/texmf-dist/doc/support/texdoc/texdoc.tex94
5 files changed, 131 insertions, 29 deletions
diff --git a/Master/texmf-dist/doc/support/texdoc/NEWS b/Master/texmf-dist/doc/support/texdoc/NEWS
index 64cb2199a94..cfb10ca9322 100644
--- a/Master/texmf-dist/doc/support/texdoc/NEWS
+++ b/Master/texmf-dist/doc/support/texdoc/NEWS
@@ -2,6 +2,22 @@ NEWS for texdoc
===============
(This file public domain.)
+Version 4.0 (TeX Live 2023)
+===========================
+Released on 2023-02-20
+
+Major changes
+- Online search feature is added:
+ users using TL without documentation will be sent to texdoc.org
+- Add new action --print-completion:
+ for the moment, only zsh is supported. Contributions welcome.
+
+Minor fixes and tweaks
+- Reflect environment variables (e.g., LANGUAGE, LC_ALL, and LANG) before checking system locale
+- Line continuation with tailing backslashes in config files
+- Scoring adjustments
+- Documentation tweaks
+
Version 3.4.1
-------------
- Bug fix: give locale bonus only if "lang" is set
diff --git a/Master/texmf-dist/doc/support/texdoc/README.md b/Master/texmf-dist/doc/support/texdoc/README.md
index 02150ce4703..57fa31a485e 100644
--- a/Master/texmf-dist/doc/support/texdoc/README.md
+++ b/Master/texmf-dist/doc/support/texdoc/README.md
@@ -21,15 +21,15 @@ If you want to try/test the develop version, please see below.
The easiest way to install the develop version of Texdoc is using [Bundler](https://bundler.io/) and [Rake](https://github.com/ruby/rake):
-```
-$ bundle install
-$ rake install
+```shell
+bundle install
+rake install
```
If you want to uninstall the develop version (to use the TeX Live version), just try:
-```
-$ rake uninstall
+```shell
+rake uninstall
```
### Installing manually
@@ -50,50 +50,50 @@ You can make sure that the right files are used by running `texdoc --files`: the
## Building and Testing
-Many building tasks are defined as [Rake](https://github.com/ruby/rake) tasks:
+Many building tasks are defined as [Rake](https://github.com/ruby/rake) tasks.
### Generating all documentation
The following will generate both the PDF and the manpage in `doc/` directory.
-```
-$ rake doc
+```shell
+rake doc
```
### Generating a pre-hashed cache file
The following will generate a pre-hashed cache file `script/Data.tlpdb.lua`. This task have to be done under a TeX Live setup with tlpdb.
-```
-$ rake gen_datafile
+```shell
+rake gen_datafile
```
### Running tests
The following will run all tests in `spec/` directory.
-```
-$ rake test
+```shell
+rake test
```
Alternatively, you can give spec names with the `--list` (`-l`) option for this task. E.g., following will run only `spec/action/help_spec.rb` and `spec/mode/list_spec.rb`:
-```
-$ rake test -- -l action/help,mode/list
+```shell
+rake test -- -l action/help,mode/list
```
### Showing all available tasks
Following will show all available tasks with a short description.
-```
-$ rake -T
+```shell
+rake -T
```
In addition to that, for options available tasks, e.g., `rake test` and `rake run_texdoc`, you can get options information with `-h` option for each task:
-```
-$ rake test -- -h
+```shell
+rake test -- -h
```
## Further Information
@@ -104,7 +104,7 @@ More specific information, such as the TODO list of this project and some inform
## Copyright and License
-Copyright 2008-2021 Manuel Pégourié-Gonnard, Takuto Asakura, the TeX Live Team.
+Copyright 2008-2023 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.
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls b/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
index a9d229b6a71..5e960588ba3 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls
@@ -1,9 +1,9 @@
% Document style for Texdoc user manual
-% Copyright 2008-2020 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008-2023 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]
+ [2023-02-17 Document class for Texdoc user manual]
% class options
\DeclareOption{draft}{\setlength\overfullrule{5pt}}
@@ -163,7 +163,7 @@
\@for\@item:=#1\do{\@delim\@item}%
\egroup}
\newcommand*{\code}[1]{\bgroup
- \chardef\_=`\_\code@font #1\egroup}
+ \chardef\_=`\_\chardef\~=`\~\code@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
@@ -219,6 +219,12 @@
\hypertarget{\@tmp@hyname}{\code{#1 = #2}}%
\IfNoValueF{#3}{\hfill (#3)}%
\begin{manual@entry}%
+ \bgroup%
+ \def\meta##1{##1}%
+ \def\_{\string_}%
+ \edef\conf@title{#1}%
+ \belowpdfbookmark{\conf@title}{\conf@title}%
+ \egroup%
}
{\ifvmode\else\unskip\fi\end{manual@entry}}
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc.pdf b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
index 5619830b780..f648933a2e1 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/support/texdoc/texdoc.tex b/Master/texmf-dist/doc/support/texdoc/texdoc.tex
index 689e6968775..0e1a0db3e80 100644
--- a/Master/texmf-dist/doc/support/texdoc/texdoc.tex
+++ b/Master/texmf-dist/doc/support/texdoc/texdoc.tex
@@ -1,6 +1,6 @@
-%#!xelatex
+%#!texfot xelatex
% Texdoc user manual
-% Copyright 2008-2022 Manuel Pégourié-Gonnard and Takuto Asakura
+% Copyright 2008-2023 Manuel Pégourié-Gonnard and Takuto Asakura
% distributed under the terms of GPL v3 or later
\documentclass{texdoc-doc}
@@ -8,7 +8,7 @@
\subtitle{Find \& view documentation in \TL}
\pkgurl{https://tug.org/texdoc/}
\author{Manuel Pégourié-Gonnard\and Takuto Asakura}
-\date{v3.4.1\quad \today}
+\date{v4.0\quad \today}
\begin{document}
@@ -151,6 +151,12 @@ but rather intended to be used from another program, like a GUI front-end to
Texdoc.
\end{clopt}
+\begin{clopt}{\code{\lopt{print-completion} \meta{shell}}}
+Print |«shell»| completion. For the time being, it only supports
+zsh\footnote{Your contributions are welcome!}. See
+Section~\ref{sec:completion} for the details.
+\end{clopt}
+
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.
@@ -257,8 +263,8 @@ Variable & Use for & Configuration item \\ \hline
\end{tabular}
\end{center}
-Third, on Unix systems, locale-related variables such as |LANG| and |LC_ALL|
-are used for the default value of \ci{lang}.
+Third, locale-related variables |LANGUAGE_texdoc|, |LANGUAGE|, |LC_ALL|, and
+|LANG| are used to set \ci{lang}.
\subsection{Precedence of configuration sources}
\label{sec:prec}
@@ -504,6 +510,25 @@ 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.
+\subsection{Online Search}
+\label{sec:online}
+
+If Texdoc cannot find any good matches for a document, it may sometimes prompt
+you to search online.
+
+If you use the |view| option, there are no ``good'' matches (|score|${}\ge{}$0),
+but you have some local documentation installed, Texdoc will show you the three
+best locally-installed documents while also prompting you to search online.
+
+If you use the |view| option when you have no local documentation installed,
+Texdoc will skip showing any fuzzy matches, and will instead prompt you to
+search online immediately.
+
+Texdoc checks to see if the |kpathsea| documentation as a heuristic for if
+\emph{any} documentation is installed. If the documentation for Texdoc is
+installed, but no other documentation is installed, the online search prompt
+may produce unexpected results.
+
\section{Configuration items}
\label{sec:conf}
@@ -511,7 +536,7 @@ 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.
+forms:
%
\begin{htcode}
«configuration item» = «value»
@@ -521,6 +546,9 @@ stopalias «original keyword»
adjscore «pattern» = «score adjustment»
adjscore(«keyword») «pattern» = «score adjustment»
\end{htcode}
+%
+You can put a backslash (\code{\char`\\}) at the end of a line to indicate that
+the line is continued on the following line.
We will concentrate on the |«configuration item»| part here, since other
directives have already been presented (Section~\ref{sec:alias} and
@@ -727,11 +755,63 @@ Texdoc within a {\TL}-based {\TeX} distribution which does not ship
|texlive.tlpdb|.
\end{confitem}
+\begin{confitem}{online\_url}{\meta{url}}
+ [default: \code{https://texdoc.org/serve/PKGNAME/0}]
+Sets the \meta{url} to use for online documentation. Texdoc will replace
+|PKGNAME| with the name of the package to search for.
+\end{confitem}
+
+\section{Shell Completion}
+\label{sec:completion}
+
+\subsection{Zsh}
+
+To enable completion for zsh, you need to put
+%
+\begin{htcode}
+autoload -Uz compinit && compinit
+\end{htcode}
+%
+in your zsh configuration file (such as \code{\~/.zshrc}). You can install our
+completion function with either of the following two ways:
+%
+\begin{itemize}
+\item adding \code{eval \$(texdoc \lopt{print-completion} zsh)} to your
+ zsh configuration file.
+
+\item adding the following file (also provided by
+ \href{https://github.com/zsh-users/zsh-completions}{zsh-completions}) to \\
+ \code{/usr/share/zsh/site-functions/\_texdoc}:
+%
+\begin{htcode}
+#compdef texdoc
+(( $+functions[__texdoc] )) || eval "$(texdoc \textbackslash
+ --print-completion zsh)" && __texdoc
+\end{htcode}
+\end{itemize}
+
+You can confirm your installation by checking whether \code{\~/.zcompdump}
+contains the following:
+%
+\begin{htcode}
+'texdoc' '_texdoc'
+\end{htcode}
+
+Note: The path \code{/usr/share} is for GNU/Linux. For other platforms, the
+path can be:
+%
+\begin{description}
+\item[macOS (homebrew, x86)] \verb|/usr/local/share|
+\item[macOS (homebrew, arm)] \verb|/opt/homebrew/share|
+\item[Android (Termux)] \verb|/data/data/com.termux/files/usr/share|
+\item[Windows (Msys2 Mingw64)] \verb|/mingw64/share|
+\end{description}
+
\section{Licence}
\label{sec:licence}
The current version of Texdoc program and its documentation are copyright
-2008--2022 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} Team.
+2008--2023 Manuel Pégourié-Gonnard, Takuto Asakura, the {\TL} 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