diff options
author | Karl Berry <karl@freefriends.org> | 2023-02-19 21:04:06 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-02-19 21:04:06 +0000 |
commit | 7fc43fa7c4058476ba50cf5d5432dc4274bcb8ae (patch) | |
tree | 9e6fdabab458f9e46eeab56bf8386bc8a5bd36c1 /Master/texmf-dist/doc/support/texdoc | |
parent | 2bc64030cbd7b6fb620691f21fda3cd1b24aeffa (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/NEWS | 16 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texdoc/README.md | 38 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texdoc/texdoc-doc.cls | 12 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/texdoc/texdoc.pdf | bin | 84314 -> 90076 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/support/texdoc/texdoc.tex | 94 |
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 Binary files differindex 5619830b780..f648933a2e1 100644 --- a/Master/texmf-dist/doc/support/texdoc/texdoc.pdf +++ b/Master/texmf-dist/doc/support/texdoc/texdoc.pdf 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 |