Info Node: (texinfo)Raw Formatter Commands

CFHT HOME texinfo: Raw Formatter Commands

up: Conditionals next: Inline Conditionals prev: Conditional Not Commands Back to Software Index 

18.3 Raw Formatter Commands
===========================

The '@if...' conditionals just described must be used only with normal
Texinfo source.  For instance, most features of plain TeX will not work
within '@iftex'.  The purpose of '@if...' is to provide conditional
processing for Texinfo source, not provide access to underlying
formatting features.  For that, Texinfo provides so-called "raw
formatter commands".  They should only be used when truly required (most
documents do not need them).

  The first raw formatter command is '@tex'.  You can enter plain TeX
completely, and use '\' in the TeX commands, by delineating a region
with the '@tex' and '@end tex' commands.  All plain TeX commands and
category codes are restored within an '@tex' region.  The sole exception
is that the '@' character still introduces a command, so that '@end tex'
can be recognized.  Texinfo processors will not output material in such
a region, unless TeX output is being produced.

  In complex cases, you may wish to define new TeX macros within '@tex'.
You must use '\gdef' to do this, not '\def', because '@tex' regions are
processed in a TeX group.  If you need to make several definitions, you
may wish to set '\globaldefs=1' (its value will be restored to zero as
usual when the group ends at '@end tex', so it won't cause problems with
the rest of the document).

  As an example, here is a displayed equation written in plain TeX:

     @tex
     $$ \chi^2 = \sum_{i=1}^N
              \left (y_i - (a + b x_i)
              \over \sigma_i\right)^2 $$
     @end tex

The output of this example will appear only in a printed manual.  If you
are reading this in a format not generated by TeX, you will not see the
equation that appears in the printed manual.

  Analogously, you can use '@ifhtml ... @end ifhtml' to delimit Texinfo
source to be included in HTML output only, and '@html ... @end html' for
a region of raw HTML.

  Likewise, you can use '@ifxml ... @end ifxml' to delimit Texinfo
source to be included in XML output only, and '@xml ... @end xml' for a
region of raw XML.  Regions of raw text in other formats will also be
present in the XML output, but with protection of XML characters and
within corresponding elements.  For example, the raw HTML text:

     @html
     <br />
     @end html

will be included in the XML output as:

     <html>
     &lt;br /&gt;
     </html>

  Again likewise, you can use '@ifdocbook ... @end ifdocbook' to delimit
Texinfo source to be included in Docbook output only, and '@docbook ...
@end docbook' for a region of raw Docbook.

  The behavior of newlines in raw regions is unspecified.

  In all cases, in raw processing, '@' retains the same meaning as in
the remainder of the document.  Thus, the Texinfo processors recognize
and even execute, to some extent, the contents of the raw regions,
regardless of the final output format.  Therefore, specifying changes
that globally affect the document inside a raw region leads to
unpredictable and generally undesirable behavior.  For example, giving
the '@kbdinputstyle' command inside a raw region.

  The remedy is simple: don't do that.  Use the raw formatter commands
for their intended purpose, of providing material directly in the
underlying format.  When you simply want to give different Texinfo
specifications for different output formats, use the '@if...'
conditionals and stay in Texinfo syntax.
automatically generated by info2www version 1.2