texinfo ChangeLog doc/texinfo.txi

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     13/01/22 00:46:36

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Raw Formatter Commands): avoid using with Texinfo-level commands

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1527&r2=1.1528
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.531&r2=1.532

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1527
retrieving revision 1.1528
diff -u -b -r1.1527 -r1.1528
--- ChangeLog   20 Jan 2013 18:37:06 -0000      1.1527
+++ ChangeLog   22 Jan 2013 00:46:35 -0000      1.1528
@@ -1,3 +1,10 @@
+2013-01-21  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Raw Formatter Commands): be more emphatic
+       about some processing being done inside raw regions,
+       and the resulting unpredictable effects when Texinfo-level
+       things are done there.
+
 2013-01-20  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (Other Customization Variables)

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.531
retrieving revision 1.532
diff -u -b -r1.531 -r1.532
--- doc/texinfo.txi     20 Jan 2013 18:37:06 -0000      1.531
+++ doc/texinfo.txi     22 Jan 2013 00:46:35 -0000      1.532
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.531 2013/01/20 18:37:06 karl Exp $
address@hidden $Id: texinfo.txi,v 1.532 2013/01/22 00:46:35 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -13818,7 +13818,7 @@
 
 @item
 `Raw' formatter text for any output format, passed straight
-through with (almost) no interpretation of @@-commands.
+through with minimal (but not zero) interpretation of @@-commands.
 
 @item
 Format-independent variable substitutions, and testing if a variable
@@ -14003,22 +14003,25 @@
 @cindex Commands using raw @TeX{}
 @cindex Plain @TeX{}
 
-Ordinarily, the @code{@@address@hidden conditionals just described must be
-used only with normal Texinfo source.  For instance, most features of
-plain @TeX{} will not work within @code{@@iftex}, as they are
-overridden by Texinfo features.  The purpose of @code{@@iftex} is to
-provide conditional processing for the Texinfo source, not provide
-access to underlying formatting features.
+The @code{@@address@hidden conditionals just described must be used only
+with normal Texinfo source.  For instance, most features of plain
address@hidden will not work within @code{@@iftex}.  The purpose of
address@hidden@@address@hidden is to provide conditional processing for Texinfo
+source, not provide access to underlying formatting features.  For
+that, Texinfo provides so-called @dfn{raw formatter commands}.  They
+should only be used when truly required (most documents do not need
+them).
 
 @findex tex
 @cindex Category codes, of plain @TeX{}
-You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
-commands, by delineating a region with the @code{@@tex} and
address@hidden@@end tex} commands.  All plain @TeX{} commands and category
-codes are restored within an @code{@@tex} region.  The sole exception
-is that the @code{@@} character still introduces a command, so that
address@hidden@@end tex} can be recognized.  Texinfo processors will ignore
-such a region in their output unless @TeX{} output is being produced.
+The first raw formatter command is @code{@@tex}.  You can enter plain
address@hidden completely, and use @samp{\} in the @TeX{} commands, by
+delineating a region with the @code{@@tex} and @code{@@end tex}
+commands.  All plain @TeX{} commands and category codes are restored
+within an @code{@@tex} region.  The sole exception is that the
address@hidden@@} character still introduces a command, so that @code{@@end
+tex} can be recognized.  Texinfo processors will not output material
+in such a region, unless @TeX{} output is being produced.
 
 @findex \gdef @r{within @code{@@tex}}
 @findex \globaldefs @r{within @code{@@tex}}
@@ -14068,7 +14071,7 @@
 @dots{} @@end xml} for a region of raw address@hidden  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:
+example, the raw HTML text:
 
 @example
 @group
@@ -14079,7 +14082,7 @@
 @end example
 
 @noindent
-will be output in XML as
+will be included in the XML output as:
 
 @example
 @group
@@ -14099,7 +14102,19 @@
 The behavior of newlines in raw regions is unspecified.
 
 In all cases, in raw processing, @code{@@} retains the same meaning as
-in the remainder of the document.
+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 @code{@@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
address@hidden@@address@hidden conditionals and stay in Texinfo syntax.
+
 
 
 @node Inline Conditionals
@@ -22017,7 +22032,7 @@
 as:
 
 @example
-$Id: texinfo.txi,v 1.531 2013/01/20 18:37:06 karl Exp $
+$Id: texinfo.txi,v 1.532 2013/01/22 00:46:35 karl Exp $
 @end example
 
 (This is potentially useful in all sources that use version control,