texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/04/10 18:08:18

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        (Command Contexts, Reference Implementation): new nodes; (History): 
amend texi2any description

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1343&r2=1.1344
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.430&r2=1.431

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1343
retrieving revision 1.1344
diff -u -b -r1.1343 -r1.1344
--- ChangeLog   8 Apr 2012 17:02:13 -0000       1.1343
+++ ChangeLog   10 Apr 2012 18:08:18 -0000      1.1344
@@ -1,3 +1,11 @@
+2012-04-10  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (History): amend texi2any description per Patrice.
+       (Reference Implementation): new node with the rationale/role text.
+
+       * doc/texinfo.txi (Command Contexts): new node, giving a guide
+       (essentially from Patrice) as to which commands can be used where.
+
 2012-04-08  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (node): explain further that TeX requires both a

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.430
retrieving revision 1.431
diff -u -b -r1.430 -r1.431
--- doc/texinfo.txi     8 Apr 2012 17:02:23 -0000       1.430
+++ doc/texinfo.txi     10 Apr 2012 18:08:18 -0000      1.431
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.430 2012/04/08 17:02:23 karl Exp $
address@hidden $Id: texinfo.txi,v 1.431 2012/04/10 18:08: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.
 
@@ -615,11 +615,11 @@
 
 Generic Translator texi2any
 
-* Invoking texi2any::           How to run @command{texi2any} and 
@command{makeinfo} 
-                                from a shell.
+* Reference Implementation:: @command{texi2any}: the reference implementation.
+* Invoking texi2any::        Running the translator from a shell.
 * Pointer Validation::          How to check that pointers point somewhere.
 * Configuration Variables::     Configuring @command{texi2any}.
-* texi2html::                   Ancestor of @command{texi2any}.
+* texi2html::                An ancestor of @command{texi2any}.
 
 Configuration Variables
 
@@ -676,6 +676,7 @@
 @@-Command List
 
 * Command Syntax::    General syntax for varieties of @@-commands.
+* Command Contexts::  Guidelines for which commands can be used where.
 
 Sample Texinfo Files
 
@@ -1748,9 +1749,9 @@
 tirelessly recorded and reported mistakes and obscurities.  Zack
 Weinberg did the impossible by implementing the macro syntax in
 @file{texinfo.tex}.  Thanks to Melissa Weisshaus for her frequent
-reviews of nearly similar editions.  Dozens of others have contributed patches 
and
-suggestions, they are gratefully acknowledged in the @file{ChangeLog}
-file.  Our mistakes are our own.
+reviews of nearly similar editions.  Dozens of others have contributed
+patches and suggestions, they are gratefully acknowledged in the
address@hidden file.  Our mistakes are our own.
 
 @cindex Scribe
 @cindex Reid, Brian
@@ -1778,23 +1779,32 @@
 
 Moving forward, the original translator to create Info was written
 (primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
address@hidden and other functions.  After several
-years, Brian Fox reimplemented the conversion program in C, now called
address@hidden and other functions.  In the early 1990s,
+Brian Fox reimplemented the conversion program in C, now called
 @command{makeinfo}.
 
 @cindex Cons, Lionel
 @cindex Dumas, Patrice
 In 2012, the C @command{makeinfo} was itself replaced by a Perl
-implementation generically called @command{texi2any}, based on
+implementation generically called @command{texi2any}.  This version
+supports the same level of output customization as
 @command{texi2html}, an independent program originally written by
 Lionel Cons, later with substantial work by many others.  The many
 additional features needed to make @command{texi2html} a replacement
-for @command{makeinfo} were implemented by Patrice Dumas.
+for @command{makeinfo} were implemented by Patrice Dumas.  The first
+never-released version of @command{texi2any} was based on the
address@hidden code.  That implementation, however, was abandoned
+in favor of the current program, which parses the Texinfo input into a
+tree for processing.  It still supports nearly all the features of
address@hidden
 
-The new Perl program is much, much slower than the old C program.  We
-hope the speed gap will close in the future, but it may not ever be
-entirely comparable.  So why did we switch?  There were several
-important reasons.
+The new Perl program is much slower than the old C program.  We hope
+the speed gap will close in the future, but it may not ever be
+entirely comparable.  So why did we switch?  In short, we intend and
+hope that the present program will be much easier than the previous C
+implementation of @command{makeinfo} to extend to different output
+styles, back-end output formats, and all other customizations.  
+In more detail:
 
 @itemize @bullet
 @item HTML customization.  Many GNU and other free software packages
@@ -1813,12 +1823,11 @@
 
 @item Additional back-ends.  The @command{makeinfo} code had grown
 convoluted to the point where adding a new back-end was quite complex,
-requiring unfortunate interactions with existing back-ends.  In
-contrast, our Perl implementation can provide a clean tree-based
-structure for all back-ends to work from.  People have requested
-numerous different back-ends (@LaTeX{}, the latest (X)HTML, @dots{}),
-and they will now be much more feasible to implement.  Which leads to
-the last item:
+requiring complex interactions with existing back-ends.  In contrast,
+our Perl implementation provides a clean tree-based representation for
+all back-ends to work from.  People have requested numerous different
+back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
+be much more feasible to implement.  Which leads to the last item:
 
 @item Making contributions easier.  In general, due to the cleaner
 structure, the Perl program should be considerably easier than the C
@@ -1826,6 +1835,9 @@
 benefits.
 @end itemize
 
address@hidden Implementation}, for more on the rationale for and
+role of @command{texi2any}.
+
 
 @node Texinfo Mode
 @chapter Using Texinfo Mode
@@ -16484,7 +16496,7 @@
 and you can get it over the Internet or on physical media.  See
 @url{http://tug.org/texlive}.
 
address@hidden let's try to keep that text in sync with www.gnu.org/prep/FTP
address@hidden please keep that text in sync with www.gnu.org/prep/FTP
 
 
 @node Generic Translator texi2any
@@ -16518,30 +16530,61 @@
 anything which may be specified on the command line may also be
 specified within a initialization file.
 
-We call it ``the'' translator for Texinfo instead of just ``a''
-translator, even though of course it's technically and legally
-possible for other implementations to be written.  The reason is that
-alternative implementations are highly likely to have subtle (or
-not-so-subtle) differences in the language, and thus Texinfo documents
-become dependent on the processor, which is bad for everyone.  Indeed,
-it was the existence of the @command{texi2html} implementation which
-spawned the merging back into the one program we have now.  We
-now consider @command{texi2any} as the reference implementation.
-
-We intend and hope that the present program should be easier than the
-previous C implementation of @command{makeinfo} to extend to different
-output styles, back-end output formats, and all other customizations.
-
-The rest of this chapter gives the rest of the details.
+The rest of this chapter goes into the details.
 
 @menu
-* Invoking texi2any::           How to run @command{texi2any} from a shell.
+* Reference Implementation:: @command{texi2any}: the reference implementation.
+* Invoking texi2any::        Running the translator from a shell.
 * Pointer Validation::          How to check that pointers point somewhere.
 * Configuration Variables::     Configuring @command{texi2any}.
-* texi2html::                   Ancestor of @command{texi2any}.
+* texi2html::                An ancestor of @command{texi2any}.
 @end menu
 
 
address@hidden Reference Implementation
address@hidden @command{texi2any}: A Reference Implementation
+
address@hidden @command{texi2any}, as reference implementation
address@hidden Reference implementation
address@hidden Implementation, @command{texi2any} as reference
+
+Above, we called @command{texi2any} ``the'' translator for Texinfo
+instead of just ``a'' translator, even though of course it's
+technically and legally possible for other implementations to be
+written.  The reason is that alternative implementations are highly
+likely to have subtle (or not-so-subtle) differences in behavior, and
+thus Texinfo documents would become dependent on the processor.
+Therefore, it is important to have a reference implementation that
+defines parts of the language not fully specified by the manual (often
+intentionally so).  It is equally important to have consistent
+command-line options and other behavior for processors.
+
address@hidden Tree representation of documents
address@hidden Syntax tree representation of documents
address@hidden Abstract syntax tree representation of documents
+For this reason, the once-independent @command{texi2html} Perl Texinfo
+processor was made compatible with the C implementation of
address@hidden, to avoid continuing with two different
+implementations (@pxref{History}).  The current reference
+implementation, @command{texi2any}, inherited the design of
+customization and other features from @command{texi2html} (for more on
address@hidden compatibility, @pxref{texi2html}).  However,
address@hidden is a full reimplementation: it constructs a tree-based
+representation of the input document for all back-ends to work from.
+
address@hidden Texinfo language tests
address@hidden Tests, of Texinfo language
+Extensive tests of the language were developed at the same time as
address@hidden; we plead with anyone thinking of writing a program
+to parse Texinfo input to at least make use of these tests.  
+
+With the release of @command{texi2any} as the reference
+implementation, development of both the C implementation of
address@hidden and @command{texi2html} has been halted.  Going
+forward, we ask authors of Texinfo documents to use only
address@hidden
+
+
 @node Invoking texi2any
 @section Running @command{texi2any}/@code{makeinfo} from a Shell
 @anchor{Invoking makeinfo}
@@ -19874,6 +19917,7 @@
 
 @menu
 * Command Syntax::    General syntax for varieties of @@-commands.
+* Command Contexts::  Guidelines for which commands can be used where.
 @end menu
 
 @sp 1
@@ -21259,6 +21303,51 @@
 paragraphs automatically.
 
 
address@hidden Command Contexts
address@hidden @@-Command Contexts
+
address@hidden 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},
address@hidden@@node}, and @code{@@setfilename}.
+
address@hidden@@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.
address@hidden@@footnote} content likewise.
+
+@@-commands with braces marking text (such as @code{@@strong},
address@hidden@@sc}, @code{@@asis}) may contain raw formatter commands such as
address@hidden@@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},
address@hidden@@exdent} and @code{@@item} in @code{@@table} lines, @@-commands
+that makes only sense in a paragraph are not accepted, such as
address@hidden@@indent}.
+
+In addition to the above, sectioning commands cannot contain
address@hidden@@anchor} or @code{@@footnote}.
+
+In the addition to the above, remaining commands (@code{@@node},
address@hidden@@anchor}, @code{@@printindex}, @code{@@ref}, @code{@@math},
address@hidden@@cindex}, @code{@@url}, @code{@@image}, and so on) cannot
+contain cross reference commands (@code{@@ref}, @code{@@xref},
address@hidden@@pxref} and @code{@@inforef}).
+
+For precise and complete information, we suggest looking into the test
+suites in the sources, which exhaustively try the combinations.
+
+
 @node Tips
 @appendix Tips and Hints
 
@@ -21800,7 +21889,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.430 2012/04/08 17:02:23 karl Exp $
+$Id: texinfo.txi,v 1.431 2012/04/10 18:08: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}