Alias for hyperref (directing to the PDF version, instead of HTML)

[gusbrs]

Since recently texdoc hyperref has been picking hyperref-doc.html as default. I don't know why but, as far as I recall, this was not the case previously.

Would you consider adding an alias for hyperref to the PDF version of the manual, hyperref-doc.pdf?

(Indeed, texdoc.cnf does contain one such alias for hyperref-dev, but not for released hyperref).

[muzimuzhi]

Since recently texdoc hyperref has been picking hyperref-doc.html as default.

Can't reproduce. hyperref-doc.pdf has higher score than hyperref-doc.html (score 8.5 vs 7.5) hence the pdf doc comes first. I have texdoc 3.4 (2022-03-03) installed with basictex on macOS.

Guess the behavior on your side is affected by some local config. Perhaps ext_list or similar ones, see texdoc texdoc.

Excerpted stdout of texdoc --debug=score hyperref

texdoc debug-score: (9fa4c09) Start scoring /usr/local/texlive/2021basic/texmf-dist/doc/latex/hyperref/hyperref-doc.html
texdoc debug-score: (9fa4c09) Name used: latex/hyperref/hyperref-doc.html
texdoc debug-score: (9fa4c09) Start heuristic scoring with pattern: hyperref
texdoc debug-score: (9fa4c09) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (9fa4c09) New heuristic score: 4.5. Reason: exact match for derived pattern: hyperref-doc
texdoc debug-score: (9fa4c09) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (9fa4c09) Final heuristic score: 6.0
texdoc debug-score: (9fa4c09) Max pattern score: 6.0
texdoc debug-score: (9fa4c09) Catalogue details bonus: +1.5
texdoc debug-score: (9fa4c09) Final score: 7.5
texdoc debug-score: (1c78ad0) Start scoring /usr/local/texlive/2021basic/texmf-dist/doc/latex/hyperref/hyperref-doc.pdf
texdoc debug-score: (1c78ad0) Name used: latex/hyperref/hyperref-doc.pdf
texdoc debug-score: (1c78ad0) Start heuristic scoring with pattern: hyperref
texdoc debug-score: (1c78ad0) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (1c78ad0) New heuristic score: 4.5. Reason: exact match for derived pattern: hyperref-doc
texdoc debug-score: (1c78ad0) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (1c78ad0) Final heuristic score: 6.0
texdoc debug-score: (1c78ad0) Max pattern score: 6.0
texdoc debug-score: (1c78ad0) Catalogue details bonus: +1.5
texdoc debug-score: (1c78ad0) Locale match bonus: +1.0
texdoc debug-score: (1c78ad0) Final score: 8.5

[gusbrs]

Mhm, I don't know what might be going on then. I simply don't have a personal texdoc.cnf:

~$ texdoc -f
/usr/local/texlive/2021/texmf-dist/scripts/texdoc/texdoclib.tlu 3.4
Configuration file(s):
    active  /usr/local/texlive/2021/texmf-dist/texdoc/texdoc.cnf
Recommended file(s) for personal settings:
    /home/gustavo/.texmf/texdoc/texdoc.cnf

In that scenario, I get:

texdoc debug-score: (9fa4c09) Start scoring /usr/local/texlive/2021/texmf-dist/doc/latex/hyperref/hyperref-doc.html
texdoc debug-score: (9fa4c09) Name used: latex/hyperref/hyperref-doc.html
texdoc debug-score: (9fa4c09) Start heuristic scoring with pattern: hyperref
texdoc debug-score: (9fa4c09) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (9fa4c09) New heuristic score: 4.5. Reason: exact match for derived pattern: hyperref-doc
texdoc debug-score: (9fa4c09) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (9fa4c09) Final heuristic score: 6.0
texdoc debug-score: (9fa4c09) Max pattern score: 6.0
texdoc debug-score: (9fa4c09) Catalogue details bonus: +1.5
texdoc debug-score: (9fa4c09) Locale match bonus: +1.0
texdoc debug-score: (9fa4c09) Final score: 8.5
texdoc debug-score: (1c78ad0) Start scoring /usr/local/texlive/2021/texmf-dist/doc/latex/hyperref/hyperref-doc.pdf
texdoc debug-score: (1c78ad0) Name used: latex/hyperref/hyperref-doc.pdf
texdoc debug-score: (1c78ad0) Start heuristic scoring with pattern: hyperref
texdoc debug-score: (1c78ad0) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (1c78ad0) New heuristic score: 4.5. Reason: exact match for derived pattern: hyperref-doc
texdoc debug-score: (1c78ad0) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (1c78ad0) Final heuristic score: 6.0
texdoc debug-score: (1c78ad0) Max pattern score: 6.0
texdoc debug-score: (1c78ad0) Catalogue details bonus: +1.5
texdoc debug-score: (1c78ad0) Final score: 7.5

It appears that the difference is in Locale match bonus which for you adds +1 to the PDF and, for me, adds +1 to the HTML. What determines this "locale bonus"?

My texdoc version is also Texdoc 3.4 (2022-03-03). Installed with TeX Live 2021, on Linux Mint 20.3.

And this is what I get from texdoc --debug=config hyperref:

~$ texdoc --debug=config hyperref
texdoc debug-version: /usr/local/texlive/2021/texmf-dist/scripts/texdoc/texdoclib.tlu v3.4
texdoc debug-config: Setting "debug_list=config" from command-line option "--debug".
texdoc debug-config: Setting "suffix_list=doc, -doc, _doc, .doc, /doc, manual, /manual, -manual, userguide, /user_guide, -guide, -user, man, -man, notes, -info, ref" in file "/usr/local/texlive/2021/texmf-dist/texdoc/texdoc.cnf" on line 88.
texdoc debug-config: Setting "lastfile_switch=true" in file "/usr/local/texlive/2021/texmf-dist/texdoc/texdoc.cnf" on line 561.
texdoc debug-config: Setting "max_lines=20" from built-in defaults.
texdoc debug-config: Setting "badbasename_list=readme, 00readme" from built-in defaults.
texdoc debug-config: Setting "interact_switch=true" from built-in defaults.
texdoc debug-config: Setting "ext_list=pdf, htm, html, txt, dat, md, ps, dvi, " from built-in defaults.
texdoc debug-config: Setting "badext_list=txt, dat, " from built-in defaults.
texdoc debug-config: Setting "fuzzy_level=3" from built-in defaults.
texdoc debug-config: Setting "mode=view" from built-in defaults.
texdoc debug-config: Setting "machine_switch=false" from built-in defaults.
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 "zipext_list=" from built-in defaults.
texdoc debug-config: Setting "rm_file=rm -f" from built-in defaults.
texdoc debug-config: Setting "rm_dir=rmdir" from built-in defaults.
texdoc debug-files: Configuration file(s):
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-config/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-config/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-config/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-var/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-var/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/gustavo/.texlive2021/texmf-var/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/gustavo/.texmf/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/gustavo/.texmf/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/gustavo/.texmf/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /usr/local/texlive/texmf-local/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /usr/local/texlive/texmf-local/texdoc/texdoc.cnf
texdoc debug-files: not found   /usr/local/texlive/texmf-local/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-config/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-config/texdoc/texdoc.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-config/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-var/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-var/texdoc/texdoc.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-var/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-dist/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: active  /usr/local/texlive/2021/texmf-dist/texdoc/texdoc.cnf
texdoc debug-files: not found   /usr/local/texlive/2021/texmf-dist/texdoc/texdoc-dist.cnf
texdoc debug-config: Setting "viewer_ps=(xdg-open %s) &" from built-in defaults.
texdoc debug-config: Setting "viewer_dvi=(xdg-open %s) &" from built-in defaults.
texdoc debug-config: Setting "viewer_txt=(xdg-open %s) &" from built-in defaults.
texdoc debug-config: Setting "viewer_html=(xdg-open %s) &" from built-in defaults.
texdoc debug-config: Setting "viewer_pdf=(xdg-open %s) &" from built-in defaults.
texdoc info: View command: (xdg-open "/usr/local/texlive/2021/texmf-dist/doc/latex/hyperref/hyperref-doc.html") &
texdoc info: Setting environment LC_CTYPE to: en_US.UTF-8

[muzimuzhi]

I get an extra line from texdoc --debug=config hyperref

texdoc debug-config: Setting "lang=en" from operating system locale.

The corresponding logic https://github.com/TeX-Live/texdoc/blob/f1b65100a0f425319a9e4849a3f37c6e9c3c0da1/script/texdoclib-score.tlu#L213-L227 is added in https://github.com/TeX-Live/texdoc/commit/1b2a302e469bc5eb5c6f07c31a8cc008a324e707#diff-1a7fb3ff68a9ab86305369ae001bde7fd946a0a1792ff1ba7120f47e96789071R218-R233 and released with v3.4. I think this explains why you experienced the change recently.

Edit: I think adding lang=en to a personal texdoc.cnf may be a workaround.

[gusbrs]

The corresponding logic

is added in https://github.com/TeX-Live/texdoc/commit/1b2a302e469bc5eb5c6f07c31a8cc008a324e707#diff-1a7fb3ff68a9ab86305369ae001bde7fd946a0a1792ff1ba7120f47e96789071R218-R233 and released with v3.4. I think this explains why you experienced the change recently.

It makes sense. It is hard to be precise, but a couple of weeks from the release seems to fit my memory of things having changed.

Edit: I think adding lang=en to a personal texdoc.cnf may be a workaround.

That is fine, I have already set an alias there and have things working for me. But I reported because it felt to me like a "bad default".

Anyway, I remain at your disposal to query anything in my system you may want to know, in order to diagnose why texdoc is failing to set lang properly from the environment variables (if that's what it does).

[muzimuzhi]

I've used up my limited knowledge about texdoc and system locale. Time to wait for maintainers' response.

Also I'm curious about why hyperref-doc.pdf matches locale, but hyperref-doc.html doesn't.

[gusbrs]

I may have a theory on what's going on.

texdoc -l hyperref returns (excerpt):

 1 /usr/local/texlive/2021/texmf-dist/doc/latex/hyperref/hyperref-doc.html
   = Manual, HTML version
 2 /usr/local/texlive/2021/texmf-dist/doc/latex/hyperref/hyperref-doc.pdf
   = [en] Manual, PDF version

From the other thread, I gather the PDF has metadata, and states it is en. The HTML does not appear to offer this metadata.

Since, in my system for some reason lang is not set, config_lang == file_lang for the HTML, both empty. So the HTML gets the bonus.

Makes sense?

[wtsnjp]

Thanks for reporting. And yes, your theory is right. I simply forgot considering that the lang can be null.

The behavior was reproduced in my local and fixed with the above commit. Thanks a lot!

[gusbrs]

@muzimuzhi and @wtsnjp Thank you very much!

And, if you'd like to investigate why lang fails to get set automatically from locale data, I remain at your disposal (if that's a problem, that is).

[wtsnjp]

Well, for the locale detection, Texdoc just uses the feature of LuaTeX (and I guess they also just use that of Lua) and even I don't know the details. To the best of my knowledge, setting the LC_ALL variable properly works for many environments while LANG does not on some platforms. You can report the issue for the upstream projects, but I guess there is only a very small chance that something will be changed.

[gusbrs]

I see, that's OK for me. I did follow @muzimuzhi 's suggestion and have lang=en in my personal texdoc.cnf now.

And, indeed, my settings are somewhat "mixed" in that area, I do set the system language to English, but for the "region" I set it to my actual local, which is different. So this may well be the reason that automatic detection does not work on my system. (LANG is en_US.UTF-8, but LC_ALL is empty).

Thanks again!