TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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

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

share|improve this question
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 1 '12 at 1:20

I have three answers.

Upgrade texdoc

Manuel Pégourié-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.

share|improve this answer
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
@mpg: That does sound like the "right" way to do it. – Matthew Leingang Feb 1 '12 at 1:20

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.