Re: command contexts

[Patrice Dumas]

On Mon, Apr 09, 2012 at 10:39:06AM -0700, Karl Berry wrote:
> 
> 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.  

Indeed.

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

I am not sure that @setfilename is that special in the texi2any 
implementation, but given the importance for TeX, I agree it
makes sense to put it here too.

> @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{@@shortcaption} may only appear in @code{@@float}, but it cannot
contain general text, it has the same limitations as 'remaining
commands' below. 

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

-- 
Pat