search

TeX-Live / texdoc

Find and view documentation in TeX Live
https://tug.org/texdoc/
GNU General Public License v3.0
47 stars 8 forks source link

TEXDOCS variable change the order of hits even if not related #67

Closed Rmano closed 3 years ago

Rmano commented 3 years ago

TeXLive 2021 here, up-to-date. In mormal conditions I have: 

[romano:~/tmp] % texdoc -l siunitx
 1 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/siunitx.pdf
   = User manual
 2 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/siunitx-code.pdf
   = Code documentation
 3 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/CHANGELOG.md
 4 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/README.md
   = Readme

but if I add my home TEXMF to the docs:

[romano:~/tmp] 32s % TEXDOCS=/home/romano/texmf/doc// texdoc -l siunitx
 1 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/siunitx-code.pdf
   = Code documentation
 2 /home/romano/texlive2021/texmf-dist/doc/latex/siunitx/siunitx.pdf
   = User manual

even if I have nothing related to siunitx in my TEXMF: 

[romano:~/tmp] 48s % find /home/romano/texmf/ -iname \*siunitx\*
[romano:~/tmp] %

Is that expected? Thanks!

wtsnjp commented 3 years ago

Well yes, that is the "expected" behavior because Texdoc prioritizes documents in TEXDOCS trees.

If you want to add your doc tree to the system default, instead of overwriting the default to TEXDOCS only contains your single doc tree, you have to set the value more properly, e.g.,

$ TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%{}%{}/home/romano/texmf/,%') texdoc -l siunitx
Rmano commented 3 years ago

Ah, ok, tomorrow I'll try.

But really I have no references to siunitx in my local texmf tree - the behavior I was looking to is to have my texmf docs override the global ones, but using the global ones if there are no references in my texmf ... so I am still puzzled that the order and found files are different.

To be clearer: I normally have the experimental version of circuitikz in my texmf and a little more (no other docs); and as you can see from the lists reported above, none of the entries found in the texdoc -l are in my local tree, they are all in the default ones... and still they change if I have TEXDOCS defined.

Rmano commented 3 years ago

Ok, I tried it. Without setting TEXDOCS, I have this: 

1d [romano:~] % kpsewhich -var-value TEXDOCS
{{}/home/romano/texlive2021/texmf-config,/home/romano/texlive2021/texmf-var,/home/romano/texmf,!!/home/romano/texlive2021/texmf-local,!!/home/romano/texlive2021/texmf-config,!!/home/romano/texlive2021/texmf-var,!!/home/romano/texlive2021/texmf-dist}/doc//

which I suppose is ok... with you suggestion, now:

1d [romano:~] % export TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%{}%{}/home/romano/texmf/,%')
1d [romano:~] % kpsewhich -var-value TEXDOCS 
{{}/home/romano/texmf/,/home/romano/texlive2021/texmf-config,/home/romano/texlive2021/texmf-var,/home/romano/texmf,!!/home/romano/texlive2021/texmf-local,!!/home/romano/texlive2021/texmf-config,!!/home/romano/texlive2021/texmf-var,!!/home/romano/texlive2021/texmf-dist}/doc//

and the texdoc -l siunitx works as expected, but: 

1d [romano:~] 4s % texdoc -l circuitikz
 1 /home/romano/texlive2021/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
   = Package documentation
 2 /home/romano/texmf//doc/latex/circuitikz/circuitikzmanual.pdf
   = Package documentation
 3 /home/romano/texmf/doc/latex/circuitikz/circuitikzmanual.pdf
   = Package documentation
[...]

but still the system-wide documentation overrides the local one. Should I re-hash something?

Post-data:

I can remove the repetition of the texmf quite easily with

export TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%,/home/romano/texmf%%' | sed 's%{}%{}/home/romano/texmf/,%')

to remove duplicates, but still my local doc does not override the standard one. For completeness, my setup is the following:

platform=$($TEXDIR/install-tl --print-arch)
                export PATH=$TEXDIR/bin/$platform:~/bin:$PATH
                export MANPATH=$TEXDIR/texmf-dist/doc/man:$MANPATH
                export INFOPATH=$TEXDIR/texmf-dist/doc/info:$INFOPATH
                export TEXMFHOME=$HOME/texmf
                export TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%,/home/romano/texmf%%' | sed 's%{}%{}/home/romano/texmf/,%')

where TEXDIR is where I have installed the (full) TeXLive root as a portable installation.

wtsnjp commented 3 years ago

Ok, that sounds a bit strange. When two documents get the same score, and that should happen for your circuitikzmanual.pdf case, Texdoc should prioritize the one in the tree which appears faster in the TEXDOCS list.

I can remove the repetition of the texmf quite easily with

export TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%,/home/romano/texmf%%' | sed 's%{}%{}/home/romano/texmf/,%')

to remove duplicates, but still my local doc does not override the standard one.

For the above, could you provide the output with full debug information?

$ texdoc -DlM circuitikz
Rmano commented 3 years ago

Here it is:

1d [romano:~] % echo $TEXDOCS
{{}/home/romano/texmf/,/home/romano/texlive2021/texmf-config,/home/romano/texlive2021/texmf-var,!!/home/romano/texlive2021/texmf-local,!!/home/romano/texlive2021/texmf-config,!!/home/romano/texlive2021/texmf-var,!!/home/romano/texlive2021/texmf-dist}/doc//
1d [romano:~] % texdoc -DlM circuitikz
texdoc debug-version: /home/romano/texlive2021/texmf-dist/scripts/texdoc/texdoclib.tlu v3.3
texdoc debug-config: Setting "debug_list=all" from command line option "-D".
texdoc debug-config: Setting "mode=list" from command line option "-l".
texdoc debug-config: Setting "machine_switch=true" from command line option "-M".
texdoc debug-config: Setting "suffix_list=doc, -doc, _doc, .doc, /doc, manual, /manual, -manual, userguide, /user_guide, -guide, -user, -man, notes, -info, ref" in file "/home/romano/texlive2021/texmf-dist/texdoc/texdoc.cnf" on line 94.
texdoc debug-config: Setting "lastfile_switch=true" in file "/home/romano/texlive2021/texmf-dist/texdoc/texdoc.cnf" on line 561.
texdoc debug-config: Setting "interact_switch=true" 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 "badbasename_list=readme, 00readme" from built-in defaults.
texdoc debug-config: Setting "fuzzy_level=3" from built-in defaults.
texdoc debug-config: Setting "max_lines=20" 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 "rm_file=rm -f" from built-in defaults.
texdoc debug-config: Setting "rm_dir=rmdir" from built-in defaults.
texdoc debug-config: Setting "zipext_list=" from built-in defaults.
texdoc debug-files: Configuration file(s):
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texmf/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texmf/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texmf/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-local/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-local/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-local/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-config/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-var/texdoc/texdoc-dist.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-dist/texdoc/texdoc-x86_64-linux.cnf
texdoc debug-files: active  /home/romano/texlive2021/texmf-dist/texdoc/texdoc.cnf
texdoc debug-files: not found   /home/romano/texlive2021/texmf-dist/texdoc/texdoc-dist.cnf
texdoc debug-texdocs: texdocs[7] = /home/romano/texmf//doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[7] using filesystem search
texdoc debug-texdocs: texdocs[6] = /home/romano/texlive2021/texmf-config/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[5] = /home/romano/texlive2021/texmf-var/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[4] = /home/romano/texlive2021/texmf-local/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[4] using index: /home/romano/texlive2021/texmf-local (shift=doc/)
texdoc debug-texdocs: texdocs[3] = /home/romano/texlive2021/texmf-config/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[2] = /home/romano/texlive2021/texmf-var/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[1] = /home/romano/texlive2021/texmf-dist/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[1] using index: /home/romano/texlive2021/texmf-dist (shift=doc/)
texdoc debug-tlpdb: Using cached data from /home/romano/texlive2021/texmf-var/texdoc/cache-tlpdb.lua
texdoc debug-search: Searching documents for pattern "circuitikz"
texdoc debug-search: File /home/romano/texlive2021/texmf-dist/doc/context/third/circuitikz/circuitikz-context.pdf found.
texdoc debug-search: File /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/CHANGELOG.md found.
texdoc debug-search: File /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/README.md found.
texdoc debug-search: File /home/romano/texlive2021/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf found.
texdoc debug-search: File /home/romano/texmf//doc/generic/circuitikz/README.md found.
texdoc debug-search: File /home/romano/texmf//doc/latex/circuitikzgit/circuitikzmanualgit.pdf found.
texdoc debug-search: File /home/romano/texmf//doc/context/third/circuitikz/circuitikz-context.pdf found.
texdoc debug-search: File /home/romano/texmf//doc/latex/circuitikz/circuitikzmanual.pdf found.
texdoc debug-search: File /home/romano/texmf//doc/generic/circuitikz/CHANGELOG.md found.
texdoc debug-score: (ff19c4d) Start scoring /home/romano/texlive2021/texmf-dist/doc/context/third/circuitikz/circuitikz-context.pdf
texdoc debug-score: (ff19c4d) Name used: context/third/circuitikz/circuitikz-context.pdf
texdoc debug-score: (ff19c4d) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (ff19c4d) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (ff19c4d) New heuristic score: 2.5. Reason: directory bonus
texdoc debug-score: (ff19c4d) Final heuristic score: 2.5
texdoc debug-score: (ff19c4d) Max pattern score: 2.5
texdoc debug-score: (ff19c4d) Final score: 2.5
texdoc debug-score: (3d493ae) Start scoring /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/CHANGELOG.md
texdoc debug-score: (3d493ae) Name used: generic/circuitikz/changelog.md
texdoc debug-score: (3d493ae) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (3d493ae) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (3d493ae) New heuristic score: 2.5. Reason: directory bonus
texdoc debug-score: (3d493ae) Final heuristic score: 2.5
texdoc debug-score: (3d493ae) Max pattern score: 2.5
texdoc debug-score: (3d493ae) Final score: 2.5
texdoc debug-score: (7a49233) Start scoring /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/README.md
texdoc debug-score: (7a49233) Name used: generic/circuitikz/readme.md
texdoc debug-score: (7a49233) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (7a49233) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (7a49233) New heuristic score: 0.1. Reason: bad basename
texdoc debug-score: (7a49233) New heuristic score: 1.6. Reason: directory bonus
texdoc debug-score: (7a49233) Final heuristic score: 1.6
texdoc debug-score: (7a49233) Max pattern score: 1.6
texdoc debug-score: (7a49233) Catalogue "readme" bonus: +0.1
texdoc debug-score: (7a49233) Adjust by 0.1 from global pattern "readme"
texdoc debug-score: (7a49233) Final score: 1.8
texdoc debug-score: (faaac75) Start scoring /home/romano/texlive2021/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
texdoc debug-score: (faaac75) Name used: latex/circuitikz/circuitikzmanual.pdf
texdoc debug-score: (faaac75) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (faaac75) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (faaac75) New heuristic score: 4.5. Reason: exact match for derived pattern: circuitikzmanual
texdoc debug-score: (faaac75) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (faaac75) Final heuristic score: 6.0
texdoc debug-score: (faaac75) Max pattern score: 6.0
texdoc debug-score: (faaac75) Catalogue details bonus: +1.5
texdoc debug-score: (faaac75) Final score: 7.5
texdoc debug-score: (7a49233) Start scoring /home/romano/texmf//doc/generic/circuitikz/README.md
texdoc debug-score: (7a49233) Name used: generic/circuitikz/readme.md
texdoc debug-score: (7a49233) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (7a49233) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (7a49233) New heuristic score: 0.1. Reason: bad basename
texdoc debug-score: (7a49233) New heuristic score: 1.6. Reason: directory bonus
texdoc debug-score: (7a49233) Final heuristic score: 1.6
texdoc debug-score: (7a49233) Max pattern score: 1.6
texdoc debug-score: (7a49233) Catalogue "readme" bonus: +0.1
texdoc debug-score: (7a49233) Adjust by 0.1 from global pattern "readme"
texdoc debug-score: (7a49233) Final score: 1.8
texdoc debug-score: (834bb7f) Start scoring /home/romano/texmf//doc/latex/circuitikzgit/circuitikzmanualgit.pdf
texdoc debug-score: (834bb7f) Name used: latex/circuitikzgit/circuitikzmanualgit.pdf
texdoc debug-score: (834bb7f) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (834bb7f) Final heuristic score: -10.0
texdoc debug-score: (834bb7f) Max pattern score: -10.0
texdoc debug-score: (834bb7f) Final score: -10.0
texdoc debug-score: (ff19c4d) Start scoring /home/romano/texmf//doc/context/third/circuitikz/circuitikz-context.pdf
texdoc debug-score: (ff19c4d) Name used: context/third/circuitikz/circuitikz-context.pdf
texdoc debug-score: (ff19c4d) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (ff19c4d) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (ff19c4d) New heuristic score: 2.5. Reason: directory bonus
texdoc debug-score: (ff19c4d) Final heuristic score: 2.5
texdoc debug-score: (ff19c4d) Max pattern score: 2.5
texdoc debug-score: (ff19c4d) Final score: 2.5
texdoc debug-score: (faaac75) Start scoring /home/romano/texmf//doc/latex/circuitikz/circuitikzmanual.pdf
texdoc debug-score: (faaac75) Name used: latex/circuitikz/circuitikzmanual.pdf
texdoc debug-score: (faaac75) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (faaac75) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (faaac75) New heuristic score: 4.5. Reason: exact match for derived pattern: circuitikzmanual
texdoc debug-score: (faaac75) New heuristic score: 6.0. Reason: directory bonus
texdoc debug-score: (faaac75) Final heuristic score: 6.0
texdoc debug-score: (faaac75) Max pattern score: 6.0
texdoc debug-score: (faaac75) Catalogue details bonus: +1.5
texdoc debug-score: (faaac75) Final score: 7.5
texdoc debug-score: (3d493ae) Start scoring /home/romano/texmf//doc/generic/circuitikz/CHANGELOG.md
texdoc debug-score: (3d493ae) Name used: generic/circuitikz/changelog.md
texdoc debug-score: (3d493ae) Start heuristic scoring with pattern: circuitikz
texdoc debug-score: (3d493ae) New heuristic score: 1.0. Reason: subword match
texdoc debug-score: (3d493ae) New heuristic score: 2.5. Reason: directory bonus
texdoc debug-score: (3d493ae) Final heuristic score: 2.5
texdoc debug-score: (3d493ae) Max pattern score: 2.5
texdoc debug-score: (3d493ae) Final score: 2.5
circuitikz  7.5 /home/romano/texlive2021/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf       Package documentation
circuitikz  7.5 /home/romano/texmf//doc/latex/circuitikz/circuitikzmanual.pdf       Package documentation
circuitikz  2.5 /home/romano/texlive2021/texmf-dist/doc/context/third/circuitikz/circuitikz-context.pdf     
circuitikz  2.5 /home/romano/texmf//doc/context/third/circuitikz/circuitikz-context.pdf     
circuitikz  2.5 /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/CHANGELOG.md     
circuitikz  2.5 /home/romano/texmf//doc/generic/circuitikz/CHANGELOG.md     
circuitikz  1.8 /home/romano/texlive2021/texmf-dist/doc/generic/circuitikz/README.md        Readme
circuitikz  1.8 /home/romano/texmf//doc/generic/circuitikz/README.md        Readme
wtsnjp commented 3 years ago

Ah, now I see the reason. This is an unexpected side-effect of #26. It compares "fullpath" before comparing tree priorities but this behavior is not reasonable in your case.

https://github.com/TeX-Live/texdoc/blob/0e9f08650891e902e2d6f205aea9bdc07a34720d/script/texdoclib-score.tlu#L250-L265

I will think about how to resolve this issue.

Rmano commented 3 years ago

Hmmm--- maybe giving a (small) score for coming first in the path order? Something that will not reasonably change anything else, like a -0.01 for each step forward in the list?

wtsnjp commented 3 years ago

I made a fix. Please have a try.

Rmano commented 3 years ago

I just made the change manually in my distro file, and it works:

1d [romano:~/tmp] 6s % texdoc -l circuitikz
 1 /home/romano/texmf//doc/latex/circuitikz/circuitikzmanual.pdf
   = Package documentation
 2 /home/romano/texlive2021/texmf-dist/doc/latex/circuitikz/circuitikzmanual.pdf
   = Package documentation
[...]

there is a double // there but this is clearly my fault in the sed expression (it should be:

export TEXDOCS=$(kpsewhich -var-value TEXDOCS | sed 's%,/home/romano/texmf%%' | sed 's%{}%{}/home/romano/texmf,%')

without the / after the last texmf).

1000 thanks!