texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/08/21 16:26:19

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Init File Formatting of Commands): edit

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1114&r2=1.1115
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.293&r2=1.294

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1114
retrieving revision 1.1115
diff -u -b -r1.1114 -r1.1115
--- ChangeLog   18 Aug 2010 00:18:47 -0000      1.1114
+++ ChangeLog   21 Aug 2010 16:26:18 -0000      1.1115
@@ -1,3 +1,7 @@
+2010-08-21  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Init File Formatting of Commands): edit.
+
 2010-08-17  Karl Berry  <address@hidden>
 
        * doc/texinfo.tex (\commondummies),

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.293
retrieving revision 1.294
diff -u -b -r1.293 -r1.294
--- doc/texinfo.txi     17 Aug 2010 18:45:58 -0000      1.293
+++ doc/texinfo.txi     21 Aug 2010 16:26:18 -0000      1.294
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.293 2010/08/17 18:45:58 karl Exp $
address@hidden $Id: texinfo.txi,v 1.294 2010/08/21 16:26:18 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.
 
@@ -18636,7 +18636,7 @@
 * Init File Encodings::           Overriding input and output encodings.
 * texi2any's Three Passes::       @command{texi2any} works in three passes.
 * Init File Calling at Different Stages::  Calling functions at various times.
-* External formatting of commands::
+* Init File Formatting of Commands:: Overriding default formatting completely.
 * Program string customization::
 * Customizing generalized block command opening:: 
 * Four contexts::             Four different contexts for command expansion: 
@@ -19209,36 +19209,46 @@
 @end vtable 
 
 Because these are arrays, you should use @code{push} to add your
-functions to them, like this:
+functions to them, like this (a real example from the @LaTeX{}2HTML
+support):
 
 @example
-push (@@command_handler_init, \&my_init);
-push (@@command_handler_process, \&my_process);
-push (@@command_handler_finish, \&my_finish);
+push (@@command_handler_init,
+      \&Texi2HTML::LaTeX2HTML::init);
+push (@@command_handler_process,
+      \&Texi2HTML::LaTeX2HTML::latex2html);
+push (@@command_handler_finish,
+      \&Texi2HTML::LaTeX2HTML::finish);
 @end example
 
+For a real-life example, see the @LaTeX{}2HTML support.
 
address@hidden External formatting of commands
address@hidden External formatting of commands
+
address@hidden Init File Formatting of Commands
address@hidden Init File Formatting of Commands
+
address@hidden Init file formatting of commands
address@hidden Formatting of commands, in init file
address@hidden Commands, custom formatting
 
 It is possible to bypass completely the normal formatting of
-@@-commands with braces and the block commands holding raw input
-(@code{@@html}, @code{@@tex}, @code{@@address@hidden regions).  In that
-case the @@-commands and the text within are passed to a user defined
-function early, right after the document structure determination, in
-pass 1 (@pxref{texi2any's Three Passes}).  Another user defined
-function is called during the output expansion phase.
+@@-commands with braces and the block commands of ``raw'' input such
+as @code{@@html} and @code{@@tex} (@pxref{Raw Formatter Commands}).
+In these cases the @@-commands and the text within are passed to a
+user-defined function early, right after the document structure
+determination of address@hidden (@pxref{texi2any's Three Passes}).
+Another user-defined function is called during the output expansion
+phase.
 
 @vindex %command_handler
-The @@-commands that are keys of the @code{%command_handler} hash 
-are collected when determining the document structure 
-pass and expanded in the expansion
-pass using user defined functions. The associated value is a reference on
-a hash used to specify the user defined function references. 
-The key of the hash reference are @code{'init'} for the function
-reference called during the first pass, and @code{'expand'}
-during the expansion pass. Here is an example for an @@-command with
-braces, @code{math}, used for an expansion using @LaTeX{}toHTML:
+These user-defined functions are specified as values in the
address@hidden hash, with the key being the command to
+override.  The associated value is itself a hash reference, whose keys
+can be @code{'init'} for the function reference called during the
+first pass, and @code{'expand'} during the expansion pass.
+
+Here is an example for an @@-command with braces, @code{math}, used
+for in the @LaTeX{}toHTML support:
 
 @example
 address@hidden'math'@} =
@@ -19247,33 +19257,35 @@
      @};
 @end example
 
-
-And an example for a raw region @@-command:
address@hidden Raw region, overriding formatting of
+Handling a raw region @@-command is the same:
 
 @example
 address@hidden'tex'@} =
      @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
        'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
-     @};
address@hidden;
 @end example
 
-The function references are called like:
+These function references are called as follows, respectively:
 
 @deftypefn {Function Reference} $status address@hidden'$command'@}->@{'init'@} 
$command $text $count
address@hidden is the @@-command name, @var{$text} is the text appearing 
-within the @@-command. @var{$count} is a counter counting how many times
-this @@-command appeared. @var{$status} is a boolean which should be true if 
-the collecting was succesfull. If false the @@-command and the text is 
-discarded.
address@hidden is the @@-command name, @var{$text} is the text
+appearing within the @@-command, and @var{$count} counts how many
+times this @@-command has appeared.  @var{$status} is a boolean to return,
+true if the collection was succesful.  If it is false, the @@-command
+and the text are discarded.
 @end deftypefn
 
 @deftypefn {Function Reference} $result 
address@hidden'$command'@}->@{'expand'@} $command $count $state $text
address@hidden is the @@-command name, @var{$count} is a counter counting 
-how many times this @@-command appeared. @var{$state} is a reference on a 
-hash containing many informations about the context. @var{$text} should be
-empty. @var{$result} is the expanded resulting text.
address@hidden is the @@-command name, @var{$count} counts how many
+times this @@-command has appeared, and @var{$state} is a hash
+reference containing detailed information about the context;
address@hidden should be empty.  @var{$result} is the expanded resulting
+text.
 @end deftypefn
 
+
 @node Program string customization
 @subsection Program string customization
 
@@ -20668,7 +20680,7 @@
 hash @code{%accent_map} hash, even if no value is associated.
 @item
 Command with braces may be handled differently, as described in
address@hidden formatting of commands}, this is used 
address@hidden File Formatting of Commands}, this is used 
 for @code{@@math} if address@hidden is used, for example.
 @end itemize
 
@@ -21236,7 +21248,7 @@
 @end deftypefn
 
 If address@hidden is used, @code{@@tex} regions are handled differently,
-(@pxref{External formatting of commands}).
+(@pxref{Init File Formatting of Commands}).
 
 The @code{@@cartouche} command formatting is controlled by the
 function reference:
@@ -24372,7 +24384,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.293 2010/08/17 18:45:58 karl Exp $
+$Id: texinfo.txi,v 1.294 2010/08/21 16:26:18 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -24451,7 +24463,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.293 2010/08/17 18:45:58 karl Exp $
address@hidden $Id: texinfo.txi,v 1.294 2010/08/21 16:26:18 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi