Take the 2-minute tour ×
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.

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?

share|improve this question
    
I believe Andrey Vihrov's answer is the correct one. But just for information, texdoc 0.83 appears to find documents even without the <category> component. Which version of texdoc are you using (texdoc --version)? –  mpg Feb 27 '12 at 17:24
    
@mpg: I’m using 0.83. But Andrey’s answer doesn’t work … –  Tobi Feb 27 '12 at 17:35
1  
@Tobi: Try texdoc -d -v twindex and see if there is something relevant. –  Andrey Vihrov Feb 27 '12 at 20:45
1  
@Tobi TEXDOCS is a "virtual" environment variable that in general you don't set. In order to see its value (which is known to the TeX programs), do kpsewhich --var-value TEXDOCS. The fact that this has a comma separated list as value, compared to $PATH, where the value is a colon separated list, is irrelevant. –  egreg Mar 4 '12 at 13:54
2  
Stupid question: Did you update the ls-R-database for $TEXMFHOME? This isn't needed for kpathsea (it'll search the whole directory structure as there is no !! in front of /Users/Tobi/Library/texmf), but texdoc relies on the database. You can check the file /Users/Tobi/Library/texmf/ls-R for the appearance of your manual twindex.pdf. –  diabonas Mar 4 '12 at 16:43

4 Answers 4

up vote 5 down vote accepted
+100

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.

share|improve this answer
    
Thanks again! I removed the ls-R file and everything is fine now. But can I configure $TEXDOCS in a way that the documentations are found if they are not in the doc/ tree but in tex/latex/…? I guess I have to change the variable, but how? –  Tobi Mar 5 '12 at 13:22
    
@Tobi The variable can be changed in the configuration file $TEXMFROOT/texmf.cnf: Either by directly adding the line TEXDOCS = $TEXMF/doc//,$TEXMFHOME/tex/latex// or by using tlmgr to do that: tlmgr conf texmf TEXDOCS $TEXMF/doc//,$TEXMFHOME/tex/latex// –  diabonas Mar 5 '12 at 13:44
    
If I call the tlmgr the new paths will be appended to the exiting ones, right? –  Tobi Mar 5 '12 at 14:15
    
@Tobi tlmgr essentially adds the line to $TEXMF/texmf.cnf, which will override the existing path. That means both solutions require you to specify the complete path - I don't know whether it's possible to append new directories while keeping the existing ones. –  diabonas Mar 5 '12 at 14:30
    
@Tobi Thanks for the bounty! –  diabonas Mar 5 '12 at 14:32

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>
share|improve this answer
    
Sounds good but doesn’t help either. Please see my question edit. –  Tobi Feb 27 '12 at 17:36

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

share|improve this answer
    
It does looks into TEXMFHOME/doc for at least two reasons: 1. TEXMFHOME is part of a brace-expression that ends with /doc so /doc is appended to each component, and 2. the expression actually ends with // which means to search recursively. Try texdoc kpathsea for details :) –  mpg Feb 27 '12 at 17:17
    
Could you pleas post your full TEXDOCS variable so I can compare it with mine? –  Tobi Feb 29 '12 at 16:19

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.

share|improve this answer
    
I put the output to my question … –  Tobi Mar 5 '12 at 1:02

Your Answer

 
discard

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.