Usage of central documentation system for TeXLive distribution (texdoc)

Question

Recently, when peeking over the shoulder of someone who has years of experience working with TeX, I saw him type something into the terminal that caused a pdf with the documentation for a LaTeX package we were working with to open. I asked if he had a central utility for finding the documentation for a package, his answer was: "Yes, it's called texdoc, look into it." We then kept doing our thing, and since his time for me is limited, I didn't further inquire and figured I'd find out on my own.

And so I tried, but can't seem to get the hang of it. I have a full working installation of TeX Live 2012 set up, and get this output:

$ texdoc
/usr/local/texlive/2012/bin/i386-linux/texdoc:7: module 'texdoc.main' not found:
no field package.preload['texdoc.main']
[kpse lua searcher] file not found: 'texdoc.main'
[kpse C searcher] file not found: 'texdoc.main'
[kpse All-in-one searcher] file not found: 'texdoc'

So apparently something is missing or not configured, as far as I can tell. I made sure that I had also installed the documentation, and tlmgr confirmed this. Considering this mentor of mine is already an older gentleman, is this software maybe outdated? Or (what seems more plausible) am I just doing it wrong?

Follow-up problem 1 [solved]

Thanks to David Carlisle's answer, I seem to have resolved the issue of texdoc not working properly. However, now all I get is the following:

~$ texdoc geometry
Sorry, no documentation found for geometry.
If you are unsure about the name, try searching CTAN's TeX catalogue at
http://ctan.org/search.html#byDescription.

EDIT/SOLVED: Since I had installed the medium scheme originally, there was no documentation for all the packages that were downloaded then. A reinstallation of TeXLive fixed that problem.

Answer 1

something is wrong with your installation:

texdoc longtable

is supposed to open the longtable package and

texdoc

on its own is supposed to echo some usage help that starts out like

$ texdoc
Usage: texdoc [OPTION]... NAME...
  or:  texdoc ACTION

Try to find appropriate TeX documentation for the specified NAME(s).
Alternatively, perform the given ACTION and exit.

Current settings: --view, --interact (default).

Options:
  -w, --view            Use view mode: start a viewer. (default)
  -m, --mixed           Use mixed mode (view or list).

However google suggests that error has been seen before.

This thread ends with a happy ending, perhaps your problem is similar:

http://tug.org/pipermail/texdoc/2011q3/000281.html

Answer 2

I followed David Carlisle's advice and navigated to the link he provided. I am posting my solution as a separate answer to have it "on-site" and not only as a link.

It turns there were a couple of things wrong with my installation of TeX Live:

• I hadn't installed the perl-tk package on my Unix-based system, which is apparently a good thing to have when you work with a manual TeX Live installation; most importantly it enables the GUI for the tlmgr or "TeX Live Manager". On Debian-derived systems (all *buntus), this is quickly fixed by running

  sudo apt-get install perl-tk
  

  in a terminal.

• I still had an old preinstalled version of luatex roaming around in my system. This is relevant, since texdoc is a Lua script or uses a Lua script in some way (Lua is a programming language, refer to the link in David Carlisle's answer and read the complete email exchange to read more about this). Since my PATH variable was set up as

  PATH="...:/usr/bin/:....:/usr/local/texlive/2012/bin/i386-linux"
  

  when I executed texdoc my system first found the old version of luatex which wasn't finding the necessary files since it lived in another directory than my actual TeX Live installation. This was fixed by two easy steps:

  1. Removing all traces of the old TeX Live distribution preinstalled on my system (by running sudo apt-get remove texlive-* on Debian-based systems)
  2. Correcting the PATH environment variable so that my TeX Live installation directory precedes any other directory where there may be TeX-related binaries. This is done by changing either the file .pam_environment (for the current user session) or by editing `/etc/environment" with sudo privileges (for all users).

After completing these steps, everything worked as expected: texdoc tried to find the documentation for the package you tell it to... it just couldn't find anything. This was because I had originally installed the medium scheme and this included no documentation. A reinstall of TexLive, using the scheme complete, resolved this issue.

Answer 3

For what it's worth --- and for those who do not have a TeX Live installation --- there is also an online version developed and maintained by frequent contributors to this site. Like texdoc itself, a very useful resource that should not be overlooked.

The interface is so simple that it needs no explanation, but the basic principle is that the URL http://texdoc.net/pkg/<packagename> should link you to the package's (main) documentation. Thus,

http://texdoc.net/pkg/geometry

offers me the chance to download the geometry documentation. (I assume if you have your browser set up with a pdf plug-in, it will just display the PDF.)