[tex-live] documentation

[Frank Küster]

karl at freefriends.org (Karl Berry) wrote:

>     Some docs are not linked properly (i.e. package geometry, fourier). I  
>     call texdoc, the browser starts up, but the link to the readme or to  
>     the doc file fails:
>
> Thanks for the report.  
>
> I admit I am not very familiar with texdoc.  From what I can see
> quickly, it calls kpsewhich -format='TeX system documentation' $name$ext
> ($name$ext will be, e.g., fourier.pdf).  So if the name doesn't match
> it's not going to be found.

Yes, it goes through a list of possible extensions.

> There is a list of explicit documentation files the file texdoctk.dat,
> but again, at a quick glance, that is only used by texdoctk and not
> texdoc.

Yes, only by texdoctk.  And this setup is not optimal either - I think
Thomas Ruedas once said he wanted to extend it and add support for more
than one texdoctk.dat (e.g. for stuff in TEXMFLOCAL).

> Would anyone like to extend texdoc to use that where possible, or
> otherwise deal with this stuff?  Seems like a lot could be done in this
> area, but I can't take it on.

To me, the easiest way to solve this seems to be the aliases mechanism.
With

fourier.pdf     fourier-doc-en.pdf

in $TEXMFDIST/aliases (or is it the other way round? Would need to
check) "texdoc fourier" would find the right documentation.  Somewhere
in the Debian BTS (and maybe in our teTeX patches) there's already a
list of possible documentation aliases, and actually I still have a mail
marked as "forward to the texlive list when it's time" when we discussed
this just before TL 2007 release.

It's a bit tricky in some cases, though, namely when there's more than
one file of documentation.  For example, Heiko has explicitly refused to
rename hyperref's manual.pdf to hyperref.pdf, because he thinks that the
other documents are important as well.  He wishes to be able to give the
documentation a new unified structure, but until this is done, he
prefers not to give the impression that it would be sufficient to read
only one document.

I fear we have to live with that and should not use aliases to work
around it.

Regards, Frank

-- 
Dr. Frank Küster
Single Molecule Spectroscopy, Protein Folding @ Inst. f. Biochemie, Univ. Zürich
Debian Developer (teTeX/TeXLive)