LaTeX, package documentation look-up

Question

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...

Answer 1

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.

Answer 2

Besides texdoc, which gives you quick access to packages documentation, there's also a great tool called texdef. Quoting the description on CTAN:

The (Perl) script displays the definition of (La)TeX command sequences/macros. Various options allow the selection of the used class and package files and other things which can have influence on the definition (before/after the preamble, inside an environment, …).

The usage is simple: issuing

texdef --tex latex --package url --source url

gives the source of the definition of the command

% url.sty, line 194:
\DeclareUrlCommand\url{}

which points to the definition of \DeclareUrlCommand, so

texdef --tex latex --package url --source DeclareUrlCommand
% url.sty, line 190:
\def\DeclareUrlCommand#1#2{\def#1{\leavevmode\begingroup #2\Url}}

Check the author's (Martin Scharrer) announcement of the tool in his answer to Where do I find out how a command/environment is defined?. See also N.N.'s answer to Display source for a command.

Answer 3

At www.ctan.org you can search for packages by keyword, by a hierarchical characterization and by a text search of the descriptions. (However, this seems to be little used; that I can tell, everyone just googles.)

Answer 4

For all those who use OS X and Alfred: I built a plugin that makes texdoc available from the Alfred input window.

Here you can get the extension

alfred-td.zip

Just unzip and drop to Alfred’s extension window.
Note that it only works with Alfred’s Powerpack (£12).
_{Disclaimer: I’m not associated with the application. I’m just a convinced user, who build an extension and like to promote the app :-)}

Related question: Use texdoc within a shell script (in Alfred.app) doesn’t work