\@ifnextchar and friends documentation

Question

While reading this question and its answers I tried to find where, for instance, \@ifnextchar is documented. I'm afraid I couldn't... I looked in TeX: The Program and TeX for the Impatient which can be found in texdoc(link) and of course in Google, but found no real documentation. My question is where is it documented?

Actually a broader question is where similar internal commands of (La)TeX are documented? I encounter in TeX.SE many answers which involve core components of La(Tex) but I usually fail to find a rigorous documentation of these elements. This makes it more difficult to have deeper understanding of the answer, and in particular try to modify/adopt the solutions to slightly different problems. So the main question is: Where core command are documented?

Edit: Let me fine tune my question since most of the answer aimed mainly at the \@ifnextchr. What is a (the?) canonical documentation of both TeX and LaTeX, where magic like \@ifnextchr and similar @ involving elements are documented? Is it only TeXbook? What is the LaTeX equivalent of TeXbook?

Answer 1

The definitive source for the documentation of the LaTeX kernel is source2e.pdf, compiled from the .dtx files from which latex.ltx and the auxiliary files loaded at format creation time are extracted. The PDF file should be available in your TeX distribution (texdoc source2e).

For example \@ifnextchar is documented in section 11.3 of source2e.pdf

Its definition is in lines 253ff. of ltdefns.dtx, but it's best understood by examples.

\def\input{\@ifnextchar\bgroup\@iinput\@@input}

If the token following \input is an open brace, then execute \@iinput, otherwise execute \@@input (which is the primitive meaning of \input).

\DeclareRobustCommand\sqrt{\@ifnextchar[\@sqrt\sqrtsign}

If the token following \sqrt is an open (square) bracket, then execute \@sqrt (there's the optional argument), otherwise execute the simpler \sqrtsign: \def\@sqrt[#1]{\root #1\of} reduces \@sqrt[#1] to the Plain TeX derived construction.

Notice that the following token is not removed (unless it's a space token), so after \sqrt[3]{x} there will be

\@sqrt[3]{x}

that is then parsed correctly.

\@ifnextchar is used in the definition of \@ifstar:

\def\@ifstar#1{\@ifnextchar *{\@firstoftwo{#1}}}

So \def\xyz{\@ifstar\s@xyz\@xyz} will do, with a following *,

\xyz*
\@ifstar\s@xyz\@xyz*
\@ifnextchar *{\@firstoftwo{\s@xyz}}\@xyz*
\@firstoftwo{\s@xyz}*
\s@xyz

and, when there's no *,

\xyz t
\@ifstar\s@xyz\@xyz t
\@ifnextchar *{\@firstoftwo{\s@xyz}}\@xyz t
\@xyz t

so we see that \@ifstar does remove the * (with a clever trick). Here t stands for any token that's not a *.

It's quite important to note that \@ifnextchar uses \if to perform the test, so, for example,

\let\myasterisk=*
\xyz\myasterisk

will be the same as \xyz*.

Answer 2

\@ifnextchar is not a primitive TeX command but an internal macro of LaTeX. It is documented in source2e in section

11.3 Command definitions

Answer 3

You can take a look at »macros2e«. It's a quite comprehensive overview for often used macros (mostly by package writers). Type texdoc macros2e on the command line for instant access.

Answer 4

There is also an implementation in LaTeX3. The module l3token is introduced with:

\peek for looking ahead in the token stream

Here an example

\documentclass[10pt]{article}
\usepackage{expl3}
\ExplSyntaxOn
\cs_new:Npn \mytestfunction
 {
 test~the~next~token:~
 \peek_meaning_ignore_spaces:NTF \c_group_begin_token
  { TRUE } { FALSE }
 }
\ExplSyntaxOff
\begin{document}
\mytestfunction

\mytestfunction[]

\mytestfunction{}

\mytestfunction      {}
\end{document}

Answer 5

As @egreg said, source2e is the canonical source for LaTeX "core" macros. You can launch source2e from the command line with "texdoc source2e".

However, source2e is a giant document. You need to know how to use the index to find the definition of a macro. For example, here is the entry for \@ifnextchar (truncated):

\@ifnextchar . . . . . . . . . . . . . . . . . . . I3, I13, 23, a45, __ d253 __, d258, d274, i44, i206, k163, m13 ...

In the PDF you'll see that "d253" is underlined. The underline means the definition of the macro can be found in that section.

To find the definition of a given macro, look for it in source2e, then click the underlined section.

Regarding TeX, you can use "TeX for the Impatient" to look up "Plain TeX" macros. Again, at the command prompt, type "texdoc impatient". The index of that book follows the same conventions of source2e (which, in fact, follows the conventions of "The TeXbook"). The TeXbook is the definitive source for Plain TeX macros, but you need to buy a copy; it does not ship with any TeX distributions (in PDF form). So "TeX for the Impatient" serves well enough.

Unfortunately, there isn't a definitive way to tell where a particular macro is defined; i.e., if it is "Plain TeX," "LaTeX," or some other packages macro.

Answer 6

I'm not sure if this is the type of documentation you're after, but there is an alphabetical list of all tex commands (with descriptions) here. For example, the command from the op is found here