[Tex/LaTex] LaTeX, package documentation look-up

documentationtex-coretexdeftexdoc

I am on OS X (10.6 Snow Leopard) using TeXLive-2011 to typeset a simple .tex file I am editing in Vim and trying to learn. My problem is: how do I…

  1. gradually learn about what TeX can do for me

  2. get detailed information about how I can use a specific command (e.g. get the full "command syntax" of url{…}

An example follows, to be specific and contextual:

A. I discovered there is a "url" command through a Google search, how can I get a "list of commands/packages"?

B. I update my "packages" using TeX Live Utility.app, is this the "right" way to do it?

C. To find out how to use "\url{…}" again I just "Googled", got to this address:

http://www.ctan.org/tex-archive/macros/latex/contrib/url

and in a file with an .sty extension, in a comment section, I discovered some usage hints:

Usage:    Conditions:
\url{ }   If the argument contains any "%" or "^^", or ends with
          "\", it can't be used in the argument to another command.
          The argument must not contain unbalanced braces.
\url|  |  ...where "|" is any character not used in the argument and not
          "{" or a space.  The same restrictions as above except that the
          argument may contain unbalanced braces.
\urldef\xyz\url{ }
\xyz      a defined-url: "\xyz" can be used anywhere, no matter what
          characters it contains.
\DeclareUrlCommand\abc{settings}: makes \abc{ } like \url{ }
See further instructions after "\endinput"

Could I have not got to this information in a simpler way?

Just by "somehow asking for help on url"? This is the crux of my problem, really. I wish there was something like "JavaDoc" or a "built-in help system" akin to what I get using Eclipse and installing JavaDoc jars and attaching source documentations. Point-and-click access to documentation about packages. If the Eclipse analogy is foreign to you, think Xcode built-in doc system or even the excellent MSDN-to-VS.NET integration. Is anything like that available for LaTeX? I can pre-generate things like what one does with Sphinx and Python if need be…

Best Answer

A. I discovered there is a "url" command through a Google search, how can I get a "list of commands/packages"?

The list of packages is on CTAN. But by itself it’s not very helpful – there are too many packages. Similarly, there’s no list of commands, that’s not meaningful since there are simply too many. The easiest way of finding out about a package/command is to google for general typesetting help in its domain (e.g. googling for latex plot) and taking it from there.

B. I update my "packages" using TeX Live Utility.app, is this the "right" way to do it?

Yes. This is by far the easiest and less painful way. If you need to install specific versions of packages which aren’t yet available via this interface (e.g. beta versions) you need to use the tlmgr command line interface instead.

Could I have not got to this information in a simpler way?
I wish there was something like "JavaDoc" or a "built-in help system" akin to what I get using Eclipse and installing JavaDoc jars and attaching source documentations

On the command line,

texdoc url

Generally, every package’s documentation can be accessed via texdoc <packagename>. Most packages come with a typeset documentation as a PDF. – Incidentally, I don’t know why most LaTeX beginners’ guides don’t mention this, or only mention it obliquely. This is by far the most useful thing I’ve ever learned about LaTeX. For instance, all core commands of LaTeX are documented in texdoc source2e (which is highly technical, but complete).

In fact, LaTeX’ documentation system is far more complete than JavaDoc or similar systems. Package writers are strongly encouraged to practice literal programming, i.e. they don’t comment/document their code. Rather, they write a documentation which contains the code (not the other way round, as in the case of JavaDoc). This usually means that package documentation is very comprehensive. For an extreme example, try texdoc tikz (an awesome package, by the way) – this is a beautifully typeset 700-page documentation with several tutorials and examples throughout.

Related Question