tex-live / texdoc

Find and view documentation in TeX Live

Texdoc ― Find and view documentation in TeX Live

General Information

• Website: https://www.tug.org/texdoc/
• Repository: https://github.com/TeX-Live/texdoc/
• Mailing list: [email protected]

Using Texdoc

Texdoc is part of the TeX Live distribution. Generally, you don't have to install it yourself.

If you want to try/test the develop version, please see below.

How to Install the Develop Version

Using Bundler

The easiest way to install the develop version of Texdoc is using Bundler and Rake:

bundle install
rake install

If you want to uninstall the develop version (to use the TeX Live version), just try:

rake uninstall

Installing manually

Here, $TEXDOC means the path to the texdoc dev sources you cloned (or downloaded), and $TEXMFHOME denotes your personal TEXMF tree (you can get its location with kpsewhich --var-value TEXMFHOME).

• The command. Symlink or copy $TEXDOC/script as $TEXMFHOME/scripts/texdoc.
• The configuration file. Symlink or copy $TEXDOC/texdoc.cnf as $TEXMFHOME/texdoc/texdoc-dist.cnf (notice the -dist part). It will completely override the other configuration files except $TEXMFHOME/texdoc/texdoc.cnf which you can still use for you personal settings.

You can make sure that the right files are used by running texdoc --files: the first line contains the full path to the version of used texdoclib.tlu, and the rest lists the configuration files in use.

Files in This Repository

• doc/ contains the documentation,
• script/ contains the source code,
• spec/ is a directory for testing scripts, and
• texdoc.cnf is the default configuration file.

Building and Testing

Many building tasks are defined as Rake tasks.

Generating all documentation

The following will generate both the PDF and the manpage in doc/ directory.

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

Running tests

The following will run all tests in spec/ directory.

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

Showing all available tasks

Following will show all available tasks with a short description.

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

Further Information

More specific information, such as the TODO list of this project and some information for distributors, can be found in the Wiki of our GitHub repository. Please visit:

• https://github.com/TeX-Live/texdoc/wiki

Copyright and License

Copyright 2008-2024 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 of the License, or (at your option) any later version.

Previous work (texdoc program) in the public domain:

• Contributions from Reinhard Kotucha (2008).
• First texlua versions by Frank Küster (2007).
• Original shell script by Thomas Esser, David Aspinall, and Simon Wilkinson.

texdoc's Issues

catalogue-alias support

The TeX Catalogue has an "alias" concept; for example, the package name xdvipdfmx is an alias for dvipdfmx. This ends up as a catalogue-alias line in texlive.tlpdb.

The Catalogue alias feature is not extensively used, but where it's present, this would (sometimes) provide better results for texdoc than the generic algorithm.

As I recall, there is already a case in texdoc if the argument is an exact package name; the idea would just be to extend that to be if the argument was an alias name as well.

Just a thought ...

Improve scoring: ignoring meaningless dirnames

texdoc -l aleph returns only one result, texmf-dist/doc/man/man1/aleph.man1.pdf. I think the readme in texmf-dist/doc/aleph/base/readme.txt should also be in the list. (I don't have an opinion about which should com first.)

I doubt the issue is merely case sensitivity, but if it is, readme and such should be searched for ignoring case. People do anything ... --thanks, karl.

Show Suggestion for Fuzzy Search

At present texdoc performs fuzzy search by default, but shows nothing on it unless -D is specified, which is sometimes confusing.
Notably, if a query exactly matches a package that does not exist on a machine or that has no document, texdoc would pick different packages (#39 (comment), #56).

It would be better if texdoc shows a fuzzy search result similary to search engines like google:

$ texdoc texdac
Did you mean: "texdoc"

I don't think a flag like --fuzzy=interact is necessary since we already have -l.

Also, the default Levenshtein distance of five is a bit large⁠—siunitx and synctex are completely different (#56).

--files only shows active files

current texdoc --files (-f) only reports active config files, it seems.

Page 7 of the manual, the description of --files, says it reports all the config files, and reports whether they are "active, not found, or disabled". I think it would be nice to restore that behavior. I don't see another way to get texdoc to report all the config files it can use. wdyt?

search.tlu: assertion failed

Using Slackware64-current, TeXLive 2018. Package supplied by the distributor.
systemwide lua version: lua 5.1.5

invoking texdoc from the command line fails with the following message:

[eduardo:/run/media/eduardo/TI10701100D/musica]$ texdoc cjhebrew
[string "/usr/share/texmf-dist/scripts/texdoc/search.t..."]:569: assertion failed!
[eduardo:/run/media/eduardo/TI10701100D/musica]$ 

The error message refers to the search.tlu script.

Any help would be appreciated. Thanks in advance.

Comprehensive testing script with RSpec + Aruba

Texdoc used to have only limited test scripts. Since I became a maintainer of the program, I have been trying to write comprehensive test scripts with RSpec + Aruba, but the work is still in progress.

Here's a rough plan of the entire specs (this will be updated accordingly):

• action
  • files: the --files action
  • help: the --help action
  • version: the --version action
  • just view: the --just-view action
• config
  • built-in: the default values
  • environment variables: does ENV work?
  • texdoc.cnf: does texdoc.cnf work?
  • texdoc-dist.cnf: is the shipped texdoc.cnf fine?
• misc
  • errors: error messages and status codes
  • getopt: the command line option (CMO) parser
  • verbose: info messages (messages output with -v option)
• mode
  • view: the view mode (-w)
  • mixed: the mixed mode (-m)
  • list: the list mode (-l)
  • showall: the showall mode (-s)
• score
  • adjscore: the adjscore directive
  • heuristic: the heuristic pattern score, bonus score
  • order: docfile order
• search
  • fuzzy: fuzzy search
  • aliases: the aliases in texdoc.cnf
  • texdocs: documents in TEXDOCS
  • database: documents in databases
• unit
  • texdoclib: check for overall behavior
  • alias: unit tests for texdoclib-alias.tlu
  • score: unit tests for texdoclib-score.tlu
  • search: unit tests for texdoclib-search.tlu
  • util: unit tests for texdoclib-util.tlu
• view
  • file detection: for each extension
  • command: the view commands

How about adding a new configuration item to specify custom texlive.tlpdb path?

Considering about the discussions in #20 and the TeX Live mailing list, adding a new configuration item to specify a custom path for texlive.tlpdb came to my mind. A possible syntax:

tlpdb = /custom/path/texlive.tlpdb

I don't think this have to be provided as a command line option, but providing as a configuration item sounds reasonable to me. After implementing the new -c option (#7), this hack can be easily used by the rake gen_datafile or whatever.

texdoc fails if BROWSER has multiple colon-separated commands

Long standing issue: https://bugs.debian.org/570376

I try to run the command "texdoc eqnarray" and I get the error message:

sh: links:lynx: not found

This is because my BROWSER environment variable contains "links:lynx", as allowed in the specification of the BROWSER variable. So texdoc should parse this variable (and perhaps others), using the first one available.

Maybe this is a missing feature. Feel free to comment. Workaround is known: one could set in addition the variable BROWSER_texdoc containing just one command, which will be preferred over the variable BROWSER.

Ready for CTAN upload?

I'm almost going to upload v3.0 to CTAN.

About the archive for CTAN, is the following structure enough? Or should I follow the TDS structure? Particulary, I'm quite not sure about the location of manpages.

.
├── COPYING
├── NEWS
├── README.md
├── doc
│   ├── man
│   │   ├── texdoc.1
│   │   └── texdoc.man1.pdf
│   ├── texdoc.pdf
│   └── texdoc.tex
├── script
│   ├── alias.tlu
│   ├── config.tlu
│   ├── constants.tlu
│   ├── functions.tlu
│   ├── main.tlu
│   ├── score.tlu
│   ├── search.tlu
│   ├── texdoc.tlu
│   ├── texdoclib.tlu
│   └── view.tlu
└── texdoc.cnf

I think above contains all files necessary for TeX Live distribution, but if it's not, please tell me that too.

texdoc palatino or times both give unexpected result

Test:

$ texdoc -l palatino
 1 /usr/local/texlive/2018/texmf-dist/doc/latex/substitutefont/greek-palatino-didot.pdf
Enter number of file to view, RET to view 1, anything else to skip: 

This is a bit unexpected. Also

$ texdoc -l times
 1 /usr/local/texlive/2018/texmf-dist/doc/latex/substitutefont/greek-times-artemisia.pdf
Enter number of file to view, RET to view 1, anything else to skip: 

These two (and others possibly, I have not tested more) should probably get aliased to psnfss2e.

Adjustment for latex-dev

Documents for the "latex-dev" packages should get lower scores than those for actual "latex" packages. E.g.,

$ texdoc -l varioref
    1 /path/to/texlive/2019/texmf-dist/doc/latex-dev/tools/varioref.pdf
    2 /path/to/texlive/2019/texmf-dist/doc/latex/tools/varioref.pdf

The order of the above result list should be the opposite. However, Texdoc cannot distinguish those two documents because the short names for both documents are "tools/varioref". This can be fixed by adjscore only after implementing #38.

cf. https://tug.org/pipermail/tex-live/2019-September/044081.html

-d crash

texdoc -d (regardless of other args) for me results in:

..live/pretest/texmf-dist/scripts/texdoc/texdoclib-cli.tlu:52: bad argument #1 to 'match' (string expected, got nil)

also, it is annoying that it truncates the filename, making it impossible to copy/paste, aside from ambiguity. is there a way to avoid that?

Searching the source trees as well

texdoc hyphenex (in current TL) gives:
1 texmf-dist/doc/latex/hyphenat/hyphenat.pdf
2 texmf-dist/doc/latex/hyphenat/README

Both of these are about a different package entirely. I realize it's only one vowel and one consonant different, but ...

Anyway, the problem isn't returning those, which is understandable, but that it fails to find the right file at all, which is:
texmf-dist/source/generic/hyphenex/README

It's in source/ rather than doc/, but that should not stop it from being found (and the exact package name match should make it preferred to anything in a wrong package name). There are lots of README and similar under source/, so it's desirable to look there.

Thanks.

"Current settings" in the help is not accurate

This bug is from ancient (at least exist from version 2.017; maybe more).

Texdoc later than version 0.70 (according to the NEWS) shows "current settings" in its help text.

With the default setups, when you specify only "-h":

$ texdoc -h
Usage: texdoc [OPTION]... NAME...
  or:  texdoc ACTION

Try to find appropriate TeX documentation for the specified NAME(s).
Alternatively, perform the given ACTION and exit.

Current settings: --view, --interact (default).
...

This is of course okay.

When you specify the "-l" option with "-h":

$ texdoc -h -l
Usage: texdoc [OPTION]... NAME...
  or:  texdoc ACTION

Try to find appropriate TeX documentation for the specified NAME(s).
Alternatively, perform the given ACTION and exit.

Current settings: --interact (default).
...

Here, the actual mode is "--list" but it doesn't appear. The same things can be said for other modes and nointeractive situations.

In the first place, I'm doubt that this function is really necessary. Current modes (and any other internal statuses) can be shown by the "--debug" option. Moreover, I think the help text must be extremely stable and should never failed to shown up, so I think it is better not to be generated dynamically.

If there aren't any objection, I will remove this function from v3.0.

look in TEXMFCONFIG, not TEXMFVAR

with current, and older, texdoc, -v -f reports:

/usr/local/texlive/dev/texmf-dist/scripts/texdoc/texdoclib.tlu 3.2.2            
Configuration file(s):                                                          
    not found   /u/karl/.texlive2020/texmf-var/texdoc/texdoc-x86_64-linux.cnf   
    not found   /u/karl/.texlive2020/texmf-var/texdoc/texdoc.cnf                
    not found   /u/karl/.texlive2020/texmf-var/texdoc/texdoc-dist.cnf 
... more ...

My question is, why isn't ~/.../texmf-config shown? That would be a normal place to put per-user config files. texmf-var, on the other hand, is supposed to be for automatically generated cache files, i.e., if it is completely removed, everything in it should be able to be regenerated.

The texdoc manual says that everything in TEXMF is looked for, but only a few of the trees defined in TEXMF are actually shown. I think it would be better to just display all of them?

kpsewhich -expand-braces=\$TEXMF
/u/karl/.texlive2020/texmf-config:/u/karl/.texlive2020/texmf-var:/u/karl/texmf:!!/usr/local/texlive/dev/texmf-local:!!/usr/local/texlive/dev/texmf-config:!!/usr/local/texlive/dev/texmf-var:!!/usr/local/texlive/dev/texmf-dist     

The way to find documentation outside TeX Live

I didn't know but Texdoc has a way to find documentation outside TeX Live.

Here, the first source provides a way to access the documentation.

However, this feature is not perfect.

1. Low efficiency (maybe because this feature is too minor?)

It seems this works without caching, so if there are huge trees under TEXDOCS, that will directly be a cause to slow down the performance of Texdoc. At this moment, I don't know anyone complaining about this, so maybe this is not a big problem.

2. No way to add extra information

It is impossible to add extra information (other from document files' name and their containing directory names). This can be solved by the new feature which is currently being discussed in #16.

3. Lack of documentation

The Texdoc manual mentions "the kpathsea variable TEXDOCS". This value is of course also be influenced by the envrionment variable TEXDOCS. On the other hand, this fact is not mentioned in Section ENVIRONMENTS of the manpage of Texdoc. We should fix this.

4. Is this enough?

I don't know how many programs are using the value of TEXDOCS, but is this can be easily customized by users just for Texdoc? If not, perhaps we should provide another way to add a searching souce tree.

In re-packaged TL from MacPorts texdoc tries to find texlive.tlpdb

In short: Running for example "texdoc verbatim" leads to "texdoc error: No texlive.tlpdb nor shipped tlpdb data found."

The issue is described here: https://trac.macports.org/ticket/58615

Checking the existence of file before trying to open it

At least for the --just-view action, Texdoc should check the existence of the file before tying to open it.

Currenly, Texdoc passes the file path to a selected viewer without checking the validity, so if some problem appears, error messages of the viewer are shown to the users. This could be confusing in some situations. An example on macOS:

$ texdoc --just-view /dev/null
/dev/null is not a regular file (use -f to see it)

Here "/dev/null is not a regular file (use -f to see it)" is a message of the less command, so the mentioned "-f" option is that of less, not of Texdoc, which is quite misleading. I know this example is extremely weird, but similar cases can be happen with other inputs on other systems.

Anyway, we should check the validity of the path for --just-view action with no doubt.

My question is: should we check the validity of the path even for other search actions as well?

If the databases (tlpdb and other databases which may be added for #16) and the cache files are always correct, we don't have to do this. But in case those could contain incorrect (or not up-to-dated) paths, this could be a problem.

We can check the validity of a path just before trying to open it (or put it to the result list), and in case it is not valid, Texdoc will try to open the next candidate (or remove it from the list). I think this approach is the best way concering about the performance.

Debug output has no reproducibility

Debug output (-D specified) has no reproducibility, which disturbs debugging.

My environment

TeX Live 2018; texdoc is installed by tlmgr (revision 47946), or manually built (4ed9315)

$ texdoc --version
Texdoc 3.0

Copyright 2018 Manuel Pégourié-Gonnard, Takuto Asakura, Karl Berry, and Norbert Preining.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.

OS: Debian 9.5

Steps to Reproduce

Repeat

#!/bin/sh
: ${texdoc:=texdoc}  # $(kpsewhich -var-value TEXMFHOME)/scripts/texdoc/texdoc.tlu
f=/tmp/texdoc
rm -f $(kpsewhich -var-value TEXMFVAR)/texdoc/cache-tlpdb.lua
$texdoc -lID texdoc 2> $f
l=$(wc -l < $f)
echo $l
mv $f ${f}_${l}_$$

The stdout is always same, but

revision 47946

Number of lines in stderr changes (125, 126, or 127), and the contents of stderr change at runtime.

4ed9315

The number of lines is always 141, but the contents still change, e.g.,

--- /tmp/texdoc_141_22804	2018-07-30 21:13:59.709969028 +0900
+++ /tmp/texdoc_141_22811	2018-07-30 21:14:00.293968672 +0900
@@ -6,10 +6,10 @@
 texdoc debug-config: Setting "lang=ja" from operating system locale.
+texdoc debug-config: Setting "verbosity_level=2" from built-in defaults.
 texdoc debug-config: Setting "basename_list=readme, 00readme" from built-in defaults.
-texdoc debug-config: Setting "max_lines=20" from built-in defaults.
-texdoc debug-config: Setting "fuzzy_level=5" from built-in defaults.
-texdoc debug-config: Setting "badbasename_list=readme, 00readme" from built-in defaults.
-texdoc debug-config: Setting "machine_switch=false" from built-in defaults.
 texdoc debug-config: Setting "ext_list=pdf, htm, html, txt, ps, dvi, " from built-in defaults.
-texdoc debug-config: Setting "verbosity_level=2" from built-in defaults.
+texdoc debug-config: Setting "fuzzy_level=5" from built-in defaults.
 texdoc debug-config: Setting "badext_list=txt, " from built-in defaults.
+texdoc debug-config: Setting "max_lines=20" from built-in defaults.
+texdoc debug-config: Setting "machine_switch=false" from built-in defaults.
+texdoc debug-config: Setting "badbasename_list=readme, 00readme" from built-in defaults.
 texdoc debug-config: Setting "rm_file=rm -f" from built-in defaults.
@@ -36,13 +36,13 @@
 texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/texdoc.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/eptexdoc.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/fonts/greektex/greektexdoc.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/man/man1/texdoc.man1.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/man/man1/texdoctk.man1.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/texdoc.pdf found.
 texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/tetex/TETEXDOC.pdf found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/ptexdoc.pdf found.
 texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/README.md found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/texdoc.pdf found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/NEWS found.
 texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/COPYING found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/man/man1/texdoctk.man1.pdf found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/eptexdoc.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/ptexdoc.pdf found.
 texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/jtexdoc.pdf found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/fonts/greektex/greektexdoc.pdf found.
-texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/man/man1/texdoc.man1.pdf found.
+texdoc debug-search: File /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/NEWS found.
 texdoc debug-score: ----------
@@ -99,4 +99,4 @@
 texdoc debug-score: ----------
-texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/tetex/TETEXDOC.pdf
-texdoc debug-score: Name used: tetex/tetexdoc.pdf
+texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/eptexdoc.pdf
+texdoc debug-score: Name used: ptex-base/eptexdoc.pdf
 texdoc debug-score: Start heuristic scoring with pattern: texdoc
@@ -106,4 +106,4 @@
 texdoc debug-score: ----------
-texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/ptexdoc.pdf
-texdoc debug-score: Name used: ptex-base/ptexdoc.pdf
+texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/fonts/greektex/greektexdoc.pdf
+texdoc debug-score: Name used: greektex/greektexdoc.pdf
 texdoc debug-score: Start heuristic scoring with pattern: texdoc
@@ -111,3 +111,4 @@
 texdoc debug-score: Max pattern score: -10
-texdoc debug-score: Final score: -10
+texdoc debug-score: Catalogue details bonus: +1.5
+texdoc debug-score: Final score: -8.5
 texdoc debug-score: ----------
@@ -120,4 +121,4 @@
 texdoc debug-score: ----------
-texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/eptexdoc.pdf
-texdoc debug-score: Name used: ptex-base/eptexdoc.pdf
+texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/tetex/TETEXDOC.pdf
+texdoc debug-score: Name used: tetex/tetexdoc.pdf
 texdoc debug-score: Start heuristic scoring with pattern: texdoc
@@ -127,4 +128,4 @@
 texdoc debug-score: ----------
-texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/jtexdoc.pdf
-texdoc debug-score: Name used: ptex-base/jtexdoc.pdf
+texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/ptexdoc.pdf
+texdoc debug-score: Name used: ptex-base/ptexdoc.pdf
 texdoc debug-score: Start heuristic scoring with pattern: texdoc
@@ -134,4 +135,4 @@
 texdoc debug-score: ----------
-texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/fonts/greektex/greektexdoc.pdf
-texdoc debug-score: Name used: greektex/greektexdoc.pdf
+texdoc debug-score: Start scoring /usr/local/texlive/2018/texmf-dist/doc/ptex/ptex-base/jtexdoc.pdf
+texdoc debug-score: Name used: ptex-base/jtexdoc.pdf
 texdoc debug-score: Start heuristic scoring with pattern: texdoc
@@ -139,3 +140,2 @@
 texdoc debug-score: Max pattern score: -10
-texdoc debug-score: Catalogue details bonus: +1.5
-texdoc debug-score: Final score: -8.5
+texdoc debug-score: Final score: -10

Get ready for Lua 5.3?

According to LuaTeX's NEWS, from version 1.10 of LuaTeX, Lua 5.3 will be used as default. I checked that fortunately Texdoc works pretty fine with Lua 5.3 and it passes all tests successfully for now (3f67c87). However, this is just because the test script have not been completed yet (see #31 for the details) and actually the difference between Lua 5.2 & 5.3 affect the debug output of Texdoc in some cases. E.g., the debug output texdoc -dscore gotoh are a bit different:

35c35
< texdoc debug-score: Final score: 7
---
> texdoc debug-score: Final score: 7.0

I will look into whether or not another type of effect exists.

Style File has higher score than README for `texdoc setspace`

texdoc version: 2ac708c
texlua version: 1.07.0 (TeX Live 2018)

$ texdoc -IDl setspace 
...
texdoc debug-search: File /opt/texlive/2018/texmf-dist/tex/latex/setspace/setspace.sty found.
texdoc debug-search: File /opt/texlive/2018/texmf-dist/doc/latex/setspace/README found.
texdoc debug-search: File /opt/texlive/2018/texmf-dist/doc/latex/setspace/README found.
texdoc debug-search: File /opt/texlive/2018/texmf-dist/doc/latex/setspace/README found.
texdoc debug-score: ----------
texdoc debug-score: Start scoring /opt/texlive/2018/texmf-dist/tex/latex/setspace/setspace.sty
texdoc debug-score: Name used: /opt/texlive/2018/texmf-dist/tex/latex/setspace/setspace.sty
texdoc debug-score: Matching alias "setspace.sty", score: 4.1
texdoc debug-score: Max pattern score: 4.1
texdoc debug-score: Final score: 4.1
texdoc debug-score: ----------
texdoc debug-score: Start scoring /opt/texlive/2018/texmf-dist/doc/latex/setspace/README
texdoc debug-score: Name used: setspace/readme
texdoc debug-score: Start heuristic scoring with pattern: setspace
texdoc debug-score: New heuristic score: 1. Reason: subword match
texdoc debug-score: New heuristic score: 0.1. Reason: bad extension
texdoc debug-score: New heuristic score: 0.1. Reason: bad basename
texdoc debug-score: New heuristic score: 1.6. Reason: directory bonus
texdoc debug-score: Final heuristic score: 1.6
texdoc debug-score: Max pattern score: 1.6
texdoc debug-score: Catalogue "readme" bonus: +0.1
texdoc debug-score: Adjust by 0.1 from global pattern "readme"
texdoc debug-score: Final score: 1.8
 1 /opt/texlive/2018/texmf-dist/tex/latex/setspace/setspace.sty
 2 /opt/texlive/2018/texmf-dist/doc/latex/setspace/README
   = Readme

1. Why texdoc debug-search: File /opt/texlive/2018/texmf-dist/doc/latex/setspace/README found. appears three times?
2. It is strange that the style file has higher score than README

"DISPLAY is not set; your viewer will likely have problems" on Windows Subsystem for Linux

$ uname -a
Linux mhoffman-m02 4.4.0-18362-Microsoft #836-Microsoft Mon May 05 16:04:00 PST 2020 x86_64 x86_64 x86_64 GNU/Linux

$ texdoc texdoc
texdoc warning: DISPLAY is not set; your viewer will likely have problems.
texdoc warning: Try --list to list results instead of displaying them.

I am able to open the file just fine because this is on Windows Subsystem for Linux where the graphical user interface does not use X.

I suggest either (1) an exception to this warning for WSL like on Mac OS X, or (2) a configuration option that lets us switch this warning off specifically (rather than switching off all warnings).

no more $Id$

Hi Takuto - you might as well delete all the $Id$ lines everywhere that I added, since (as far as I know) git does not support them. Thanks.

The development page of our website

@kberry since the README.md in this repostitory is already prepared, could you please make https://www.tug.org/texdoc/dev/ a parmanent redirect to https://github.com/TeX-Live/texdoc/?

You don't have to hurry, but this is just for a reminder. Thanks.

`sh: realpath: command not found`

I just updated to Texdoc 3.2 (2020-02-02) and now I get

sh: realpath: command not found

each time I use texdoc. Any ideas?

(operating system OS X 10.9)

Edit: OS X 10.15 seems to have the same problem, see https://tug.org/pipermail/tex-live/2020-February/044668.html

newcm -> newcomputermodern

I suggest making newcm an alias for newcomputermodern. Right now, texdoc newcm
brings up one of the doc files ("symbols"), which has newcm in the name, while texdoc newcomputermodern also lists the README and "sample" files. This is all as expected, but since newcm is so much easier to type and remember, an alias seems useful?

Get rid of old/unused stuff

I'd like to remove following things (but not so soon):

• TODO.md: we can use GitHub's issues (here) instead
• some in the doc/: I want to unify the build tool even for the documents
• all in tools/: I'm going to replace these by new scripts/tools
  • scripts for testing: we will use one of the sophisticated/well-known frameworks
  • the gen-datafiles: take into the scope of the build tool (I'm not sure about this)
  • any other necessary things? → if there are, please comment that

Some of the old scripts in this repository are unknown how to use; perhaps no one is using.

[knuth-pdf] Incorrect startup file.

• TeX Live 2021 (on Kubuntu 20.04 LTS)
• Texdoc 3.3 (2021-03-17)
• Package knuth-pdf à la revision 58470

texdoc knuth-pdf opens bibtex/bibtex-changes.pdf, i.e., the first PDF file listed in knuth-pdf.tlpobj, instead of index.pdf, i.e., the top-most PDF in directory knuth-pdf. (Alternatively, there's also index.html.)

texdoc cm -> cm.ps example

Hi Takuto - texdoc cm yields texmf-dist/doc/latex/epslatex-fr/cm.ps as the first result; this is just an example image from that manual, and is useless/meaningless.

Knuth's README is the only core documentation I can think of in TL about the cm fonts themselves: texmf-dist/doc/fonts/cm/README. This only shows up as result #5.

I think this is a candidate for a simple alias/special case. At least, I can't imagine any way to change the algorithms to prefer that README that wouldn't be likely to mess up other results. wdyt?

Separate markdown viewer from text viewer

Currently, Texdoc opens markdown files (*.md) with a text viewer, which set by the environment variables PAGER, PAGER_texdoc, or the configuration item viewer_txt.

Since markdown become very popular format for software documentation and many tools to treat them have been develop, let's separate the viewer for markdown from general text viewer.

I'm going to add:

• New environment variables MDVIEWER and MDVIEWER_texdoc
• A new configuration item viewer_md

Remaining tasks for v3.0

Following list is the only (small) tasks I'll do before releasing v3.0. I'm not going to make a big change from now to the release, but if you find a big problem here (e.g. something very imortant is missing), please let me know.

• moving TODO.md to the Wiki
• moving the description of the old envrionment variables in the document to a footnote (cf. #11)
• writing about the current way to generate a cache file in the README.md
• updating the NEWS file

Documents for AMS-LaTeX classes and IEEEtran

I wrote a small script to check the aliases in our texdoc.cnf and list up all not working aliases. I found 26 invalid aliases in the file and fixed or removed most of them. But there are two cases which I cannot find good solutions and would like to ask for your help.

1. AMS-LaTeX classes

For the name of AMS-LaTeX classes, namely amsart, amsbook, amscls, amsproc, they were aliased to instr-l.pdf. However, this file seems no longer exists in TeX Live.

There is a document texmf-dist/doc/latex/amscls/amsclass.pdf in the current TeX Live, but this looks like a source code documentation and not for normal users. Which document is preferred to show with these names? Do you have any suggestions?

2. IEEEtran

For the name ieee, it was aliased to IEEEtran_HOWTO.pdf. However, it seems this file also not exist in the current TeX Live though the package IEEEtran exists (I tried the find command under the texmf-dist but not found). Is there the file or an alternative in TeX Live?

JFYI, there is a TeX Live-specific README (texmf-dist/doc/latex/IEEEtran/README.TEXLIVE) and it says:

The following files have been removed in the TeX Live installation of
the current package, typically due to duplication, lack of space, or
missing source code.  You can find these files on CTAN at
	http://mirror.ctan.org/macros/latex/contrib/IEEEtran
If questions or concerns, email [email protected].

	IEEEtran_bst_HOWTO.pdf
	IEEEtran_HOWTO.pdf

If the file IEEEtran_HOWTO.pdf doesn't exist in TeX Live, I think this file also needs to be updated.

(I didn't read the readme carefully, sorry.)

Which document is preferred to show with the name "IEEE"? Do you have any suggestions?

Texdoc does not return documentation for added packages

On Ubuntu 20.04, after installing packages "texlive-latex-extra" and "texlive-latex-extra-doc", Texdoc does not return documentation for new packages. On Ubuntu 18.04 it works well.

Creating a new command line option -c

The idea:

$ texdoc -c "fuzzy_level = 0" <keyword>

will work just like fuzzy_level = 0 is written in your texdoc.cnf. This will overwrite all the settings in actual configure files.

Compressed files can't be displayed

https://bugs.debian.org/591781

A rather long standing issue, when using texdoc to display compressed files in GNOME/XFCE . texdoc opens the viewer window, but the to be displayed (temporary) file is already gone and can't be opened. The original submitter runs Debian testing (w/ texdoc 3.0) and XFCE and still sees the issue.

Please be so kind to have a look at the issue. Thanks!

Environment variables without `_texdoc` suffix don't work (see #10)

The issue #10 is closed, so I comment here.

I’m of divided opinion about checking environment. The fact that the code does not work now is, of course, in a need for a fix. (I was hit by this too, on Windows.)

On the other hand, the _texdoc-less variables are very widely used by other applications — which may lead to a conflict about the semantic of these variables. Moreover, since the easy workaround is provided (by _texdoc suffix), such conflicts would not be reported.

On the gripping hand, if such a conflict arises, this workaround still works….

Summary: removing the check may lead to things suddenly breaking (and TeXdoc stopping to work when these variables are set anew) if the conflicts mentioned above actually exist.

Counting of documents off by one (Debian bug #914984)

Hi

here at Debian we got the following bug report:

texdoc -l number
reports:
44 results.  Display them all? (y/N)
but then only lists 43 results. Either the displayed count is wrong or
the final result is not being displayed.

Same happening on current upstream TeX Live as of today.

Fuzzy search does not work with aliases

version: 16ddcb9

Steps to Reproduce

$ texdoc -Ilcfuzzy_level=0 nonexistingpkg
Sorry, no documentation found for nonexistingpkg.
If you are unsure about the name, try searching CTAN's TeX catalogue at
https://ctan.org/search.html#byDescription.
$ mkdir -p $(kpsewhich -var-value=TEXMFHOME)/texdoc
$ echo 'alias nonexistingpkg = texdoc' >> $(kpsewhich -var-value=TEXMFHOME)/texdoc/texdoc.cnf
$ texdoc -Ilcfuzzy_level=0 nonexistingpkg
 1 /usr/local/texlive/2018/texmf-dist/doc/support/texdoc/texdoc.pdf
   = Package documentation
$ texdoc -Ilcfuzzy_level=1 nonexistingpkgs
Sorry, no documentation found for nonexistingpkgs.
If you are unsure about the name, try searching CTAN's TeX catalogue at
https://ctan.org/search.html#byDescription.

$(kpsewhich -var-value=TEXMFHOME)/texdoc/texdoc.cnf is read but fuzzy search returns listings, whose Levenshtein distance is 8.

Environment variables without `_texdoc` suffix don't work

According to the user manual (p. 8), Texdoc should accept following environment variables: PAGER, BROWSER, DVIVIEWER, PSVIEWER, and PDFVIEWER.

However only *_texdoc form of those work at least in my environment.

Looking into the source code (config.tlu), the environment variables with the suffix are used directly (with the function set_config_elt_from_vars()), but others are somehow checked the validty.

-- set config from environment if available
function setup_config_from_env ()
    local function set_config_elt_from_vars(key, vars)
        for _, var in ipairs(vars) do
            local value = os.getenv(var)
            if value then
                set_config_element(key, value, {src='env', name=var})
            end
        end
    end
    local function set_config_elt_from_option_env(key, var)
        if (os.type == "windows") then return end
        local value = os.getenv(var)
        if value then
            for cmd in string.gmatch(value, '([^:]+)') do
                if is_in_path(cmd) then
                    set_config_element(key, cmd, {src='env', name=var})
                    -- don't test other commands if we have found one
                    break
                end
            end
        end
    end
    set_config_elt_from_vars('viewer_pdf',
      {"PDFVIEWER_texdoc", "TEXDOCVIEW_pdf", "TEXDOC_VIEWER_PDF"})
    set_config_elt_from_option_env('viewer_pdf', "PDFVIEWER")
    set_config_elt_from_vars('viewer_ps',
      {"PSVIEWER_texdoc", "TEXDOCVIEW_ps", "TEXDOC_VIEWER_PS"})
    set_config_elt_from_option_env('viewer_ps', "PSVIEWER")
    set_config_elt_from_vars('viewer_dvi',
      {"DVIVIEWER_texdoc", "TEXDOCVIEW_dvi", "TEXDOC_VIEWER_DVI"})
    set_config_elt_from_option_env('viewer_dvi', "DVIVIEWER")
    set_config_elt_from_vars('viewer_html',
      {"BROWSER_texdoc", "TEXDOCVIEW_html", "TEXDOC_VIEWER_HTML"})
    set_config_elt_from_option_env('viewer_html', "BROWSER")
    set_config_elt_from_vars('viewer_md',
      {"MDVIEWER_texdoc", "TEXDOCVIEW_md", "TEXDOC_VIEWER_MD"})
    set_config_elt_from_option_env('viewer_md', "PAGER")
    set_config_elt_from_vars('viewer_txt',
      {"PAGER_texdoc", "TEXDOCVIEW_txt", "TEXDOC_VIEWER_TXT"})
    set_config_elt_from_option_env('viewer_txt', "PAGER")
end

It seems this varification is not working well because even a valid value, e.g. on macOS:

$ export PDFVIEWER="open -a Preview.app"

doesn't work. Furthermore, the function set_config_elt_from_option_env() seems not supporting Windows, i.e. environment variables without the suffix are not supported for Windows (and this behavior is not documented!)

I think users are responsible for setting the valid exvironment variables, so we don't need to check any validity of their values. I'd like to abandon the function set_config_elt_from_option_env() and treat all environment variables by set_config_elt_from_vars() in order to fix this bug.

p.s. The help text was wrong for long time; it said the envrionment variables specially for Texdoc is texdoc_*, but it is actually *_texdoc. I already fixed this with the commit 17d2460.

get rid of Data.tlpdb.lua

I think it would be better to get rid of the Data.tlpdb.lua file. It is perpetually stale. And if it's only a backup. if texlive.tlpdb can't be found, IMHO it is better for texdoc to simply fail.

Takuto, if you agree, can you eradicate all traces of that file from the sources+docs? Thanks.

texdoc siunitx displays synctex man page

Just as the title says, texdoc siunitx displays the man page for synctex. That's on TeXLive 2020.

cache handling

By now texdoc creates new cache files whenever the tlpd changes (even in version 3.0). Didn't we discuss that we drop the cache generation and always use the tlpdb directly?

Suggestions about the environment variables

Relate to #10, I have two suggestions about the environment variables.

Abolishing old names

We are still supporting old names of environment variables such as TEXDOCVIEW_txt and TEXDOC_VIEWER_TXT. Do we really have to do this? I think the release of v3.0 is the good timing to abolish those.

cf. the user manual (again)

The order of priority: environment variables vs. texdoc.cnf

Currently, environment variables win over settings in texdoc.cnf (such as viewer_txt). I'm wondering this is truely desiable behavior, because envrionment variables like PAGER are commonly used.

So my suggestion for the order of priority is here:

1. Environment variables with the suffix (*_texdoc)
2. Settings in texdoc.cnf
3. Environment variables without the suffix
4. Built-in settings

What do you think?

The basic structure of Texdoc: the default texdoc.cnf and source code

This is the topic from #13.

The location of texdoc.cnf

Currently, the default texdoc.cnf (which placed at the top-level of this repository) is placed in texmf-dist/texdoc/. This is top-top-level of TeX Live, and the directory contains only texdoc.cnf; which is clearly unnecessary and undesirable.

One possible solution is putting the texdoc.cnf under texmf-dist/scripts/texdoc/, but in my opinion, it is still not ideal because:

• texdoc.cnf is not a script file (it should not treated exactly same as source code), and
• as a fact, there is no *.cnf file under texmf-dist/scripts/.

So, I'm looking for the best position of the file. If there are no other options, maybe we should put it under texmf-dist/scripts/texdoc/.

This change should be done at some point, but on the other hand, this can destroy the compatibility severely, so we should think twice before doing this change (how to do and when).

Sould texdoclib require the modules by relative path?

The very rough scheme how Texdoc source works is:

1. texdoc[.tlu] setup the Kpathsea (kpse) and requrie texdoc/main.tlu using kpse
2. texdoc/main.tlu require texdoc/texdoclib.tlu using kpse
3. texdoc/texdoclib.tlu require other texdoc/*.tlu using kpse

I don't know and I can't understand why this program have such a complex scheme. Using kpse for requiring Texdoc's own source code is maybe not a good idea, because suppose some of the *.tlu is missing in a directory, the only missing files can be loaded somewhere completely different place in the system.

I'd like to change this to require the all files relatively (so loading files in the same directory) and remove the wrapper for main.tlu (abolish current texdoc[.tlu] and rename main.tlu to texdoc[.tlu]). This will make the scheme simpler and will prevent to load undesirable files (from somewhere using kpse). This won't change the installation method.

Suggesting trying tlmgr-info for packages without any document

Currently, for package names without any document, Texdoc automatically executes the fuzzy search and delivers the results. For instance, with a query "genmisc":

$ texdoc -v genmisc
texdoc info: Fuzzy search result: mentis
texdoc info: View command: open "/usr/local/texlive/2019/texmf-dist/doc/latex/mentis/mentis.pdf"
texdoc info: Setting environment LC_CTYPE to: en_US.UTF-8

However, a package named "genmisc" actually exists in TeX Live. IMO, in case that a package exactly matches to a query exists in TeX Live, it is better to say something like

$ texdoc <kw>
Package <kw> exists, but unfortunately no documentaiton found.
Try `tlmgr info <kw>` for some information about the package.

than silently performing the fuzzy search and deriver results for another package found with the feature.

At this point, the cache files generated by the database texlive.tlpdb does not include any information about packages without any document. This means Texdoc can't recognize the names of such packages. To implement this enhancement, such names also need to be included in the cache files.

showing command being run?

I'm not sure, but I wonder about having texdoc output the command line it runs before it runs it. (The final command line, after all variables have been looked at, etc.) I, at least, would find it useful because I often want to look at other things in that same directory, or modify the viewing command slightly, or whatever.

For example, after texdoc latex, RET, it might show (in my case)
xpdf /usr/local/texlive/dev/texmf-dist/doc/latex/latex-doc-ptr/latex-doc-ptr.pdf

wdyt?

Support invoking Texdoc with absolute paths

when latest release is invoked with an absolute path, I get a fatal error:
$ /usr/local/texlive/pretest/bin/x86_64-linux/texdoc graphicx

/usr/local/texlive/pretest/bin/x86_64-linux/texdoc:15: attempt to index field 'cli' (a nil value)

Using modern frameworks for testing and building

To realize #5, I'm thinking to use frameworks common in the Ruby community. I've not yet decided this, but I'll go for experiments.

The motivations for this are:

• currently testing scripts make me difficult to add new test cases,
• some of the old scripts are unknown how to use & maybe not closs-platform, and
• unfortunately, I'm not good at Perl

About testing

I'm doing experiments to use a framework Aruba with RSpec. This is ongoing in the test branch.

About building

If the experiments for testing succeed, I'm going to do experiments with Rake for building. I'd like to manage all of these operations with only a framework:

• installing/unistalling the develop version
• generating the pre-hashed pseudo cache file
• generating the documentation
• running help2man
• anything else?

And most importantly, the usages of new scripts/tools must be documented in the README.md.

Where is the command of `texdoc`

Command 'texdoc' not found, but can be installed with: sudo apt install texlive-base

I'm using Ubuntu 18.04.
The texlive has been installed as http://tug.org/texlive/quickinstall.html indicated.
/usr/local/texlive/2018/bin/x86_64-linux has been added to the PATH. And, no texdoc in this folder.

So, where is it?

Fuzzy search has no reproducibility

Version: master (b3b2872)

Steps to Reproduce

For example, query is "theses", fuzzy level is at least 3 (default is 5).

$ texdoc -cfuzzy_level=2 theses
Sorry, no documentation found for theses.
If you are unsure about the name, try searching CTAN's TeX catalogue at
https://ctan.org/search.html#byDescription.

Repeat

#!/bin/sh
q='theses'
l=3
texdoc -IlD -cfuzzy_level=$l $q > /tmp/$q.$l.o$$ 2> /tmp/$q.$l.e$$

stdout

--- /tmp/theses.3.o27530	2018-08-11 23:04:40.968485254 +0900
+++ /tmp/theses.3.o27546	2018-08-11 23:04:42.108492568 +0900
@@ -1,4 +1,4 @@
- 1 /usr/local/texlive/2018/texmf-dist/doc/latex/umthesis/example.pdf
-   = Example of use
- 2 /usr/local/texlive/2018/texmf-dist/doc/latex/umthesis/README
+ 1 /usr/local/texlive/2018/texmf-dist/doc/latex/afthesis/usethesis.pdf
+   = Package documentation
+ 2 /usr/local/texlive/2018/texmf-dist/doc/latex/afthesis/README
    = Readme

stderr

$  wc -l /tmp/theses.3.e*
   59 theses.3.e27530
   77 theses.3.e27546
  136 total

Cause

texdoc/script/search.tlu

Lines 614 to 632 in b3b2872

	-- fuzzy search by using levenshtein distance
	function fuzzy_search(pattern)
	local tmp_d
	local min = 100
	local result
	for p in pairs(tlp_doclist) do
	tmp_d = levenshtein(pattern, p)
	if tmp_d < min then
	min, result = tmp_d, p
	end
	end
	if min <= config.fuzzy_level then
	return result
	else
	return ''
	end
	end

Levenshtein distance of each candidate is always same, but the order of tlp_doclist is arbitrary, resulting in unreproducible result (can be shown by -v option).

#24