Customizing texdoc - funny search path

Question

I want to ensure that texdoc cool opens up texmf-dist/doc/latex/cool/Content_LaTeX_Package_Demo.pdf instead of texmf-dist/doc/latex/cool/cool.pdf: My default configuration is this:

$ texdoc -l cool
 1 /usr/local/texlive/2010/texmf-dist/doc/latex/cool/cool.pdf
   = Package documentation
 2 /usr/local/texlive/2010/texmf-dist/doc/latex/cool/Content_LaTeX_Package_Demo.pdf
   = EXamples of use
Please enter the number of the file to view, anything else to skip:

According to the texdoc manual this can by done with a local texdoc/texdoc.cnf file. I get that. But when I checked texdoc's search path I get something funny:

$ texdoc -f
texdoc 0.72
Configuration files are:
    absent  /Users/matthew/Dropbox/Library/texmf:~/Library/texmf/texdoc/texdoc-x86_64-darwin.cnf
(*) absent  /Users/matthew/Dropbox/Library/texmf:~/Library/texmf/texdoc/texdoc.cnf
    absent  /Users/matthew/Dropbox/Library/texmf:~/Library/texmf/texdoc/texdoc-dist.cnf
    absent  /usr/local/texlive/2010/../texmf-local/texdoc/texdoc-x86_64-darwin.cnf
    absent  /usr/local/texlive/2010/../texmf-local/texdoc/texdoc.cnf
    active  /usr/local/texlive/2010/texmf/texdoc/texdoc.cnf
(*) This is the recommended configuration file for your personal preferences.

The first three directories look like they have a literal :~ in them. If I create config files in ~/Dropbox/Library/texmf/texdoc/ or ~/Library/texmf/texdoc they are not found.

I think I created this problem when I followed the solution to How to add an extra searchable dir with personal style files to TeXLive, NOT under ~/Library/texmf? :

$ kpsewhich --var-value=TEXMFHOME
/Users/matthew/Dropbox/Library/texmf:~/Library/texmf

It looks like texdoc assumes that $TEXMFHOME is a single directory and not a colon-separated list of directories. Is there a workaround?

Speaking as texdoc's author, I think it is a bug in texdoc. More precisely, it was a bug which should be fixed since version 0.81 (shipped with TeX live 2011). — mpg, Jan 31 '12 at 16:08
On an unrelated note, I think the result of texdoc cool is clearly suboptimal, so the adjustment you wanted to make to your configuration should actually be incorporated in the default configuration file. I'd like to encourage everyone to report such suboptimal (or wrong) results on the texdoc list so that I can fix them. Such user input is very useful for me to keep making texdoc better. Thanks in advance. — mpg, Jan 31 '12 at 16:17
@mpg: Thanks for letting me know this isn't an issue in the current stable version. — Matthew Leingang, Feb 01 '12 at 01:20

score 2 · Answer 1 · edited Apr 13 '17 at 12:35

I have three answers.

Upgrade `texdoc`

Manuel Pégourié-Gonnard (mpg), the maintainer of texdoc, says the issue has been fixed since v0.81, which shipped with TeX Live 2011. I'll verify this when I upgrade my TL.

Set a KPSE variable

See MPG's comment below. The KPSE variable $TEXMFHOME.texdoc can be used to override $TEXMFHOME for texdoc purposes only. I ran

$ sudo tlmgr conf texmf TEXMFHOME.texdoc "~/Library/texmf"

Now I see:

$ texdoc -f
texdoc 0.72
Configuration files are:
    absent  /Users/matthew/Library/texmf/texdoc/texdoc-x86_64-darwin.cnf
(*) active  /Users/matthew/Library/texmf/texdoc/texdoc.cnf
    absent  /Users/matthew/Library/texmf/texdoc/texdoc-dist.cnf
    absent  /usr/local/texlive/2010/../texmf-local/texdoc/texdoc-x86_64-darwin.cnf
    absent  /usr/local/texlive/2010/../texmf-local/texdoc/texdoc.cnf
    active  /usr/local/texlive/2010/texmf/texdoc/texdoc.cnf
(*) This is the recommended configuration file for your personal preferences.

and if I add to ~/Library/texmf/texdoc/texdoc.cnf the line

adjscore(cool) Content_LaTeX_Package_Demo = 10

I get:

$ texdoc -l cool
 1 /usr/local/texlive/2010/texmf-dist/doc/latex/cool/Content_LaTeX_Package_Demo.pdf
   = EXamples of use
 2 /usr/local/texlive/2010/texmf-dist/doc/latex/cool/cool.pdf
   = Package documentation

which is what I want. Not only that, when I choose Help > Show Help for Package... in TeXShop, it reflects this update.

Set a environment variable

This was my first answer. The texdoc manual notes that environment variables can be overridden for texdoc purposes by suffixing _texdoc to them. So a workaround is to set:

$ export TEXMFHOME_texdoc=~/Library/texmf

(I'm using the bash shell on Mac OSX.) This has to be put in my ~/.profile file so it is executed within every shell.

But since I have TeX Live and have already customized it it makes sense to go the TL route rather than environment variables.

Rather than an environment variable, I suggest you use a KPSE variable, named TEXMFHOME.texdoc (same as the envvar but with a dot---actually it's the other way round: the envvar is named after the KPSE var). You can set it either by manually editing a relevant texmf.cnf file or by having tlmgr edit on for you, eg tlmgr conf texmf TEXMFHOME.texdoc "~/texmf", exactly in the same way you modified the value of TEXMFHOME in the first place. — mpg, Jan 31 '12 at 16:02

Customizing texdoc - funny search path

1 Answers1

Upgrade texdoc

Set a KPSE variable

Set a environment variable

Upgrade `texdoc`