Latex, tetex, emerge: Documentation using texdoc.

[gentsquash]

Gentoo 2.6.9 app-text/tetex 2.0.2-r4

[I'm not sure what forum is appropriate. Since the question's
answer may well depend on USE flags, I'll post this to "Portage".
I welcome corrections.]

Among other things, pkg "tetex" has LaTeX and a cmd `texdoc' to
display documentation about latex-pkgs (and maybe other stuff).
IIRC, a cmd such as

Code: Select all

texdoc amsmath

would find file "amsmath.dvi" and display it. If the file didn't
exist, then `texdoc' would search for "amsmath.dtx" and run latex
on it to produce "amsmath.sty" and "amsmath.dvi", then display
the latter. IIRC, `texdoc' also searched for doc files in HTML
and ".ps" formats.

A friend installed Gentoo for me a few weeks ago, and `texdoc'
worked, but only showed a local (on my computer) webpage with a
summary and links to remote webpages. In particular, it did not
have the typeset "amsmath.dvi" that showed how amsmath is to be used.

================
When a new `tetex' appeared on portage, I decided to try to get
the extra documentation and did (the equivalent of)

Code: Select all

USE=doc    emerge tetex

But now, `texdoc' finds no documentation at all --not even the
summary HTML page... I don't know if my "USE=doc" caused this, or
whether this is a difference between the older and the newer
`tetex'. In any case ...

Q1: How can I re-emerge tetex to at least recover the HTML
summaries?

Q2: Do I mis-remember?: Are there USE flags I can set so that the
".dtx" files will stay resident, and `texdoc' can produce the
documenting ".dvi" file?

[fifo]

Is the html/dvi documentation actually on your system, say in /usr/share/texmf/doc/help/Catalogue/entries/ or /usr/share/texmf/doc/latex/amsmath/ ? If so, can kpsewhich find it?

Code: Select all

$ kpsewhich -format='TeX system documentation' amsmath.html
/usr/share/texmf/doc/help/Catalogue/entries/amsmath.html

$ kpsewhich -format='TeX system documentation' amsldoc.dvi
/usr/share/texmf/doc/latex/amsmath/amsldoc.dvi

[gentsquash]

Is the html/dvi documentation actually on your
system, say in

/usr/share/texmf/doc/help/Catalogue/entries/ or
/usr/share/texmf/doc/latex/amsmath/ ?

Hmmm, Good question. The directory "/usr/share/texmf/doc/"
has only a self-symlink

Code: Select all

/usr/share/texmf/doc:
lrwxrwxrwx  1 root root Oct 29 tetex-2.0.2-r4 -> ../doc/tetex-2.0.2-r4

(and ?what? is its purpose?)

A system search with "locate amsmath.d" yields only

Code: Select all

/usr/share/texmf/source/latex/amsmath/amsmath.dtx

--Ah, Wait!, I've found something. Searching just for "amsmath"
yields many files, among which

Code: Select all

/usr/share/doc/tetex-2.0.2-r4/help/Catalogue/entries/amsmath.html
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/diffs-m.txt
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/testmath.dvi
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/amsldoc.cls
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/amsldoc.dvi
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/amsdtx.cls
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/subeqn.dvi
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/amsmath.faq
/usr/share/doc/tetex-2.0.2-r4/latex/amsmath/technote.dvi

So some documentation is present in .html .dvi and .txt files.

If so, can kpsewhich find it?

Code: Select all

$ kpsewhich -format='TeX system documentation' amsmath.html

Alas, no, the cmd returned nothing, despite "amsmath.html" being
present.

BTWay, the above "amsmath.faq" has

User documentation is found in the "User's Guide for the amsmath
Package" (amsldoc.dvi, .pdf, .ps, .tex).

So, presumably, `texdoc' ought to know how to find it.
I suppose my next step is to find the path-variables that tetex
(kpsewhich?) uses to unearth files. My set-up (which I haven't
looked at in years) *does* adjoin directories to the default
path(s), but it doesn't remove any. (...at least it BETTER NOT, if it
doesn't want to be sent to bed with no supper...)

I'll start examining, and will read with interest any suggestions
that you might have. Is there a Gentoo reference that details
how various USE flags affect how/with-what `tetex' is compiled?

[fifo]

The directory "/usr/share/texmf/doc/"
has only a self-symlink

Code: Select all

/usr/share/texmf/doc:
lrwxrwxrwx  1 root root Oct 29 tetex-2.0.2-r4 -> ../doc/tetex-2.0.2-r4

(and ?what? is its purpose?)

It's a symlink to /usr/share/doc/tetex-2.0.2-r4, which is where the actual documentation has been moved to. I don't think that's a problem.

If so, can kpsewhich find it?

Code: Select all

$ kpsewhich -format='TeX system documentation' amsmath.html

Here's the problem, since texdoc uses kpsewhich to search for the documentation. (texdoc is just a simple shell script, you can read what it does.) I don't know what's wrong though--it works fine for me. All I can do is point you at documentation here: 'info kpathsea'.

[niltonvolpato]

I was with the same problem. After gentoo people moved the tetex docs to /usr/share/doc, the texdoc could not find any documentation.
The solution i found was to change this line in /usr/share/texmf/web2c/texmf.cnf from:

Code: Select all

TEXDOCS = .;$TEXMF/doc//

to

Code: Select all

TEXDOCS = .;$TEXMF/doc//;/usr/share/doc/tetex-2.0.2-r5//

Adding the documentation location to the search path. (You may change this depending on your version)

And you must run mktexlsr after doing this to update the database.

-- Nilton

[the_bat]

Hi,

I had the same problem for a long time. For me, the reason seems to have been, that I installed preview-latex before the splitting out of the doc tree. This package owned the directory /usr/share/texmf/doc (found with equery belongs) and prevented it to get a symlink to ../doc/tetex-*.

The tetex ebuild silently ignored this problem ...

I fixed it by

1. unmerging preview-latex,
2. emerging tetex,
3. emerging preview-latex again

.

[serial_penguin]

I have the same problem with my tetex-2.0.2-r9 installation and I don't have preview-latex installed. The fix mentioned above of editing /usr/share/texmf/web2c/texmf.cnf and changing the TEXDOCS environment variable does work. That fix, in my situation, is to change

Code: Select all

TEXDOCS = .;$TEXMF/doc//

to

Code: Select all

TEXDOCS = .;$TEXMF/doc//;/usr/share/doc/tetex-2.0.2-r9//

and then doing a mktexlsr. However,

Code: Select all

$TEXMF/doc

is a symlink to

Code: Select all

/usr/share/doc/tetex-2.0.2-r9

The problem appears to be that the newer kpathsea library, in expanding environment variables, doesn't expand symlinks. I suppose there is some benefit to this, but it becomes awkward with tetex. This means that if extra packages are installed and if one wants easy access to the documentation then the TEXDOCS variable has to be changed for each installation or the variable could be changed once to

Code: Select all

TEXDOCS = .;$TEXMF/doc//;/usr/share/doc//

All of this seems to defeat the purpose behind the concept of a tetex tree. Are there any LaTeXers who have found an easy solution to this?