command contexts

[Karl Berry]

Patrice -- some time ago you wrote up a nice summary of which commands
are allowed where, after Vincent nagged about it.  I amended the
English, etc., as below.  Let me know what you think.

I introduced the term "general text" since when you said "anything" I
presume you didn't really mean that something like

@caption
@section foo
@end caption

was supposed to work.  Wouldn't make sense, as far as I could imagine ...

Thanks,
karl


@node Command Contexts
@section @@-Command Contexts

@cindex Contexts, of @@-commands

Here we describe approximately which @@-commands can be used in which
contexts.  It merely gives the general idea and is not exhaustive or
meant to be a complete reference.  Discrepancies between the
information here and the @code{makeinfo} or @TeX{} implementations
are most likely to be resolved in favor of the implementation.

By @dfn{general text} below, we mean anything except sectioning and
other such outer-level document commands, such as @code{@@section},
@code{@@node}, and @code{@@setfilename}.

@code{@@c}, @code{@@comment} and @code{@@if ... @@end if} conditional
commands may appear anywhere (except the conditionals must still be on
lines by themselves).  @code{@@caption} and @code{@@shortcaption} may
only appear in @code{@@float} but may contain general text.
@code{@@footnote} content likewise.

@@-commands with braces marking text (such as @code{@@strong},
@code{@@sc}, @code{@@asis}) may contain raw formatter commands such as
@code{@@html} but no other block commands (other commands terminated
by @code{@@end}) and may not be split across paragraphs, but may
otherwise contain general text.

In addition to the block command restriction, on @code{@@center},
@code{@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands
that makes only sense in a paragraph are not accepted, such as
@code{@@indent}.

In addition to the above, sectioning commands cannot contain
@code{@@anchor} or @code{@@footnote}.

In the addition to the above, remaining commands (@code{@@node},
@code{@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math},
@code{@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot
contain cross reference commands (@code{@@ref}, @code{@@xref},
@code{@@pxref} and @code{@@inforef}).

For precise and complete information, we suggest looking into the test
suites in the sources, which exhaustively try the combinations.