texdoc doesn’t search at $TEXMFHOME

Question

I built a little private package and I want texdoc to find its manual. So I moved the documentation to <TEXMFHOME>/doc/twindex.pdf (i.e. ~/Library/texmf/doc/twindex.pdf on my Mac). But if I call

texdoc twindex

it doesn’t find the package. If I ask kpsewhich with

kpsewhich -format "TeX system documentation" twindex.pdf

it finds the right file (/Users/Tobi/Library/texmf/doc/twindex.pdf)

I thought that texdoc looks at $TEXMFHOME too, am I wrong with that? How can I configure it to search there too?

Update

^{Belonging to Andrey’s (and Phil’s) answer}

I tried to use a category but it doesn’t work. kpsewhich finds the file at

/Users/Tobi/Library/texmf/doc/latex/twindex/twindex.pdf

I also had a look at $TEXDOCS and it contains my texmf folder. But if I compare it with $PATH, there is a difference. In the latter the paths are separated by : instead of , may this the problem?

Update 2

The TEXDOCS varaiable contains my user texmf folder (line 3):

Tobis-Mac:~ Tobi$ kpsewhich --var-value TEXDOCS
{/Users/Tobi/Library/texlive/2011/texmf-config,
/Users/Tobi/Library/texlive/2011/texmf-var,
/Users/Tobi/Library/texmf,
!!/usr/local/texlive/2011/texmf-config,
!!/usr/local/texlive/2011/texmf-var,
!!/usr/local/texlive/2011/texmf,
!!/usr/local/texlive/2011/../texmf-local,
!!/usr/local/texlive/2011/texmf-dist}/doc//

Update 3

To debug texdoc I tried texdoc --debug=texdocs twindex while twindex.pdf is saved at $TEXMFHOME/doc/latex/twindex/twindex.pdf and additionally at $TEXMFHOME/tex/latex /tw/twindex/twindex.pdf and $TEXMFHOME/twindex.pdf my home path is $TEXMFOME = /Users/Tobi/Library/texmf

Tobis-Mac:texmf Tobi$ texdoc --debug=texdocs twindex
texdoc debug-version: /usr/local/texlive/2011/texmf/scripts/texdoc/texdoclib.tlu version 0.83
texdoc debug-texdocs: texdocs[8] = /Users/Tobi/Library/texlive/2011/texmf-config/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[7] = /Users/Tobi/Library/texlive/2011/texmf-var/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[6] = /Users/Tobi/Library/texmf/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[6] using index: /Users/Tobi/Library/texmf (shift=doc/)
texdoc debug-texdocs: texdocs[5] = /usr/local/texlive/2011/texmf-config/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[4] = /usr/local/texlive/2011/texmf-var/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[3] = /usr/local/texlive/2011/texmf/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[3] using index: /usr/local/texlive/2011/texmf (shift=doc/)
texdoc debug-texdocs: texdocs[2] = /usr/local/texlive/2011/../texmf-local/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[1] = /usr/local/texlive/2011/texmf-dist/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[1] using index: /usr/local/texlive/2011/texmf-dist (shift=doc/)
Sorry, no documentation found for twindex.
If you are unsure about the name, try searching CTAN's TeX catalogue at
http://ctan.org/search.html#byDescription.

Everything seems ok. As far as I can see texdoc searches /Users/Tobi/Library/texmf/doc recursive which includes the twindex path …

I have to correct myself, twindex is not found at$TEXMFHOME/twindex.pdf` too.

If I call ls -R in texmf the list contains all three places of twindex.pdf.

Whats wrong with my system?

Answer 1

texdoc doesn't call kpathsea directly to find the documentation files. Instead, it uses the $TEXDOCS variable, expands it with the help of kpathsea and browses the directories for documentation files by itself. This yields essentially the same results as a direct call of

kpsewhich -path=$TEXDOCS twindex.pdf

However, there is one important difference: If kpathsea encounters a directory where no ls-R database is required (i. e. a directory with no !! prefix in the path specification), it searchs the whole file system, regardless of whether there is a ls-R database for it or not. texdoc, however, relies on that database if present, so if a file is not in the database, it isn't found even if it is in the file system.

So I suspect your ls-R database for $TEXMFHOME is out of date. Try updating it using

mktexlsr /Users/Tobi/Library/texmf

(you have to specify the path manually as $TEXMFHOME isn't in $TEXMFDBS). Another possibility is to delete the file

/Users/Tobi/Library/texmf/ls-R

altogether, as a database file isn't required by either kpathsea or texdoc - like this, texdoc will access the file system directly.

Answer 2

As per TDS specification, the path should resemble those for the tex and fonts directories and be

texmf/doc/<category>/...

where

category identifies the general topic of documentation that resides below it; for example, a TeX format name (latex), program name (bibtex, tex), language (french, german), a file format (info, man), or other system components (web, fonts).

Therefore, assuming that your package is designed for LaTeX, place its documentation in the directory

texmf/doc/latex/<your package>

Answer 3

The full details of where texdoc looks are given in the texdoc manual, texdoc.pdf, (say texdoc texdoc in your Terminal). Roughly, it looks in trees given by $TEXDOCS given by

kpsewhich --var TEXDOCS

In my case this includes ~/Library/texmf but not ~/Library/texmf/doc — it also includes lots of other places so best to check out the detail

Answer 4

You can debug the paths used by texdoc calling it by

texdoc --debug=texdocs twindex

Using a document I have as ~/Library/texmf/doc/latex/xymtex/doc101/xymtex.pdf calling

texdoc --debug=texdocs xymtex

gives

texdoc debug-version: /usr/local/texlive/2011/texmf/scripts/texdoc/texdoclib.tlu version 0.83
texdoc debug-texdocs: texdocs[8] = ~/Library/texlive/2011/texmf-config/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[7] = ~/Library/texlive/2011/texmf-var/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[6] = ~/Library/texmf/doc (index_mandatory=false, recursion_allowed=true)
texdoc debug-texdocs: texdocs[6] using filesystem search
texdoc debug-texdocs: texdocs[5] = /usr/local/texlive/2011/texmf-config/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[4] = /usr/local/texlive/2011/texmf-var/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[3] = /usr/local/texlive/2011/texmf/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[3] using index: /usr/local/texlive/2011/texmf (shift=doc/)
texdoc debug-texdocs: texdocs[2] = /usr/local/texlive/2011/../texmf-local/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[2] using index: /usr/local/texlive/2011/../texmf-local (shift=doc/)
texdoc debug-texdocs: texdocs[1] = /usr/local/texlive/2011/texmf-dist/doc (index_mandatory=true, recursion_allowed=true)
texdoc debug-texdocs: texdocs[1] using index: /usr/local/texlive/2011/texmf-dist (shift=doc/)

Note: I've masked with ~ the real root of my home in the output.