LaTeX equivalent to R's `help foo`?

Question

From the R command line I can do help foo -- where foo is some R command-- and return a .html help file on foo. This holds even if foo is from some non-standard library I just loaded.

Q: What's the closest process to this in LaTeX?

Here I was helped and found that mthelp (texdoc on TeXLive systems) can return help files for packages, document classes, and commands. But missing were LaTeX macros (e.g. \section)

Q: What's the quickest/best way to get full documentation on standard latex commands (e.g., \section) or commands from packages that need to be loaded (e.g., \mathcal from amsfonts)

Until now, I've either been (1) hunting through Kopka and Daly, (2) using Help -> Keyword Search in WinEdt (returns LaTeX2e Help, which is only helpful for very standard LaTeX macros (e.g., \section). Even then, the documentation is very limited), (3) standard Google and forum searches, or (4) using manuals (sometimes struggling with mthelp to find the manual for the appropriate package containing the macro of interest)

Maybe I'm spoiled by R, but this process is terribly inefficient. I must be doing something wrong...right?

Answer 1

TeX isn't an object oriented programming language which can attach documentation data to classes and objects like in Python or most likely in R. There is no backtrace in which file/package/class a certain macro was defined or what its input specification is.

My way is (1) Google for unknown macros to find out in with package they are defined, (2) texdoc <package> + search for that macro, if this doesn't help (3) I look at the source code of the package, either by (3a) opening the source file or by (3b) using \show\macro on the macro in question. IMHO that's the closest you can get to something help macro. It shows you the definition of the macro which tells advanced users much of what they need to know.

In the case of macros with optional arguments this doesn't help much because \show only shows the special internal macros like \\macro and \macro (note the space in the macro name). I, of course, programmed myself a Perl+TeX script which shows me this definitions from the command line (texdef -p <package> <macro>). Publishing it is on my ToDo list.

However, if you only want the user description of the macro, i.e. how many and which arguments it needs, you are better of using an editor like Kile with command completion. This of course only works with commands the editor knows, which will be limited to the standard and some more common packages.

Answer 2

This is not really an answer, but way too long for a comment:

The problem with looking for documentation for the macro \foo is that it's (almost) impossible to know where \foo was defined. For example, \section is most likely defined by the document class your using, so if it's article, you would need to say texdoc article (or whatever the equivalent is in miktex), and if it's memoir, you use texdoc memoir. But if you are using some package that extends or changes the functionality of \section, the information from the article documentation might be insufficient, irrelevant or even misleading.

The best advice I can give is to keep your preamble clean, write a small comment about each and every package you use, and if you don't know why you \usepackage{foobar}, it's probably because you don't use it [1]. Something like

% babel - hyphenation rules and other localization stuff
\usepackage[danish]{babel}

% The geometry package makes it easy to set the margins
\usepackage{geometry}

If you at some point find out that you need to add the package mathrsfs to get a certain script math font (\mathscr), make sure to make a note of that near \usepackage{mathrsfs}. This way, you have a much better chance of knowing where to look for documentation.

[1] This is not quite true, but I believe it's important to have some idea about what each package is doing.

Answer 3

Unlike in R, in LaTeX you almost never use the built-in command line except when handling errors, and even errors are usually handled by LaTeX IDE's and editors. Almost every time you need help with some LaTeX command, you are inside a text editor. Perhaps that's why LaTeX does not provide the kind of help you are talking about. If there is any help for LaTeX commands, it is usually integrated into the editor you are using. For example in vim, if you have LaTeX support installed, all standard LaTeX commands (those that are available when using LaTeX with one of the standard classes and no additional packages) are directly accessible from vim help system, just as any vim commands. I can simply type :he \mbox and get help on the LaTeX \mbox command. Different editors have different capabilities, and different ways to access the help system.

As other answers point out, if you are using other classes and packages, it is usually hard to know where are your commands defined. With different classes and packages you get different commands, and sometimes a class or a package redefines one of the standard commands in its own way (for example, the exam class uses \part in a way that is completely different from its use in the standard LaTeX classes). That means that any help system would have to watch your file as you are typing it, and keep track of the packages that you are using. Again, the text editor is probably the best suited for that. Vim with LaTeX support does in a way keep track of your packages, and although it does not provide help on them, it will create a menu with the most important commands from each package it recognizes. In theory this could be extended so that the editor would load help files as you add more packages to your file, and extend its help system to cover those packages. It would probably be possible to write a program that would parse the .dtx files and try to extract information about commands defined in each of them. It probably would not be easy, and I would expect it to be somewhat unreliable.

Answer 4

You can display the parts of the source code containing a given string (e.g. a given macro) using the code below.

If you are already loading the packages that you need, you can search in them. The code (between \makeatletter and \makeatother) patches the \input primitive so that each time a file is read, it is also parsed to find the given string of characters in the file. If this string is found, it will be shown on your terminal, together with a given number of lines of context. It is not at all polished code (in particular, you can only search for one string in each run).

To search in a specific file, do \FindStringInFile {1}{5}{gathered}{amsmath.sty} (will crash if the file does not exist). To search in all the files that are loaded afterwards, do \FindStringInAnyLaterFile {1}{5}{math*}. The first and second arguments are the number of lines of context to display before and after the string.

In most simple cases, the code should not break the compilation of documents, but I make no guarantee at all.

\documentclass{minimal}

\makeatletter
% Standard macros
\def\FSIF@firstoftwo#1#2{#1}
\def\FSIF@secondoftwo#1#2{#2}
\def\FSIF@ifempty@NTF #1{%
  \expandafter\ifx \expandafter a\detokenize\expandafter{#1}a%
  \expandafter\FSIF@firstoftwo
  \else
  \expandafter\FSIF@secondoftwo
  \fi
}

% Declare our variables
\newread\FSIF@read
\newcount\FSIF@line@int
\newcount\FSIF@pre@context@int
\newcount\FSIF@post@context@int
\newcount\FSIF@found@int
\gdef\FSIF@context{}
\def\FSIF@lines@found{}
\def\FSIF@line@part@i{}
\def\FSIF@line@part@ii{}
\def\FSIF@message@break{}

\def\FindStringInFile#1#2#3#4{%
  \FSIF@pre@context@int#1\relax
  \FSIF@post@context@int#2\relax
  \gdef\FSIF@context{}%
  \expandafter\FSIF@aux\expandafter{\detokenize{#3}}{#4}%
  \FSIF@show@context
}


\def\FSIF@show@context{%
  \begingroup
  \newlinechar\endlinechar
  \show\FSIF@context
  \endgroup
}

\def\FSIF@aux #1#2{% `#1` is now detokenized
    \begingroup
    % Setup for nice display
    \begingroup\lccode`\*\endlinechar
    \lowercase{\endgroup \def\FSIF@message@break{*--------------------%
        ---------- #2 ------------------------------*}}%
    % 
    % Define a macro delimited by `#1`
    \def\FSIF@line@split##1#1##2\FSIF@mark##3\FSIF@stop{%
        \def\FSIF@line@part@i{##1}%
        \def\FSIF@line@part@ii{##2}%
    }%
    %  
    % Prepare to read the file, line by line (detokenized)
    \FSIF@line@int 0\relax
    \immediate\openin\FSIF@read #2\relax
    \ifeof\FSIF@read\ERROR\fi
    \def\FSIF@lines@found{}%
    %
    % Save each line in a different control sequence, built with
    % `\FSIF@fileline{<file name>}{<line number>}`.
    % 
    % If the string was found, store the line number in 
    % `\FSIF@lines@found`
    \loop 
    \unless\ifeof\FSIF@read
    \readline\FSIF@read to \FSIF@line@buffer
    \advance\FSIF@line@int by 1\relax
    \expandafter\expandafter\expandafter\let
        \FSIF@fileline{#2}{\the\FSIF@line@int}\FSIF@line@buffer
    \expandafter \FSIF@line@split \FSIF@line@buffer 
        \FSIF@mark #1\FSIF@mark \FSIF@stop
    \FSIF@ifempty@NTF \FSIF@line@part@ii {}{% 
        \edef\FSIF@lines@found{\FSIF@lines@found\the\FSIF@line@int,}%
    }%
    \repeat
    % 
    \expandafter\edef\csname FSIF@#2@lineno\endcsname{\the\FSIF@line@int}%
    % 
    % Then add `\FSIF@context@int` context lines around each line.
    % There can be overlaps...
    \edef\FSIF@lines@found{\FSIF@lines@found
      \number\numexpr\the\FSIF@line@int+\the\FSIF@pre@context@int,}%
    %
    \FSIF@pop@lines@found
    \FSIF@line@int 0\relax
    \loop
    \advance\FSIF@line@int by 1\relax
    % If we've exhausted this found-line's context, see the next one.
    \ifnum\numexpr\the\FSIF@found@int+\the\FSIF@post@context@int
                  <\the\FSIF@line@int\relax
    \FSIF@pop@lines@found
    \fi
    % If we're not yet at a context, step to one.
    \ifnum\numexpr\the\FSIF@found@int-\the\FSIF@pre@context@int
                  >\the\FSIF@line@int\relax
    \FSIF@line@int\numexpr\the\FSIF@found@int-\the\FSIF@pre@context@int
    \xdef\FSIF@context{\FSIF@context\FSIF@message@break}%
    \fi
    % Now we're in a context, so store that line.
    \xdef\FSIF@context{\FSIF@context\FSIF@fileline{#2}{\the\FSIF@line@int}}%
    % If we've not reached the end, we're done.
    \ifnum\FSIF@line@int<\csname FSIF@#2@lineno\endcsname\relax
    \repeat
    \endgroup
}

\def\FSIF@fileline#1#2{\csname FSIF@#1@#2\endcsname}

\def\FSIF@pop@lines@found{%
  \expandafter\FSIF@pop@lines@found@aux \FSIF@lines@found\FSIF@stop}
\def\FSIF@pop@lines@found@aux #1,#2\FSIF@stop{%
  \FSIF@found@int#1\relax \def\FSIF@lines@found{#2}}


\def\FSIF@new@@@input{\expandafter\FSIF@new@@@input@aux\romannumeral-`\0}
\def\FSIF@new@@@input@aux#1 {%
  \expandafter\FSIF@aux\expandafter{\FSIF@string}{#1}%
  \FSIF@show@context
  \FSIF@old@@@input #1 }

\def\FindStringInAnyLaterFile#1#2#3{%
  \FSIF@pre@context@int#1\relax
  \FSIF@post@context@int#2\relax
  \edef\FSIF@string{\detokenize{#3}}%
  \gdef\FSIF@context{}%
  % patch `\@@input`.
  \let\FSIF@old@@@input\@@input
  \let\@@input\FSIF@new@@@input
}


\makeatother
%

\FindStringInFile {1}{5}{gathered}{amsmath.sty}

\FindStringInAnyLaterFile {1}{5}{math*}

\usepackage{amsmath}

\usepackage{breqn}

\begin{document}

An equation,
\begin{align*}
  x^2 + y^2 &= z^2 \\
  x^2 - y^2 &= t^2
\end{align*}

\end{document}