[5218] more on newlines and macro invocations; no more implicit blank line generation

[karl]

Revision: 5218
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5218
Author:   karl
Date:     2013-03-02 23:58:34 +0000 (Sat, 02 Mar 2013)
Log Message:
-----------
more on newlines and macro invocations; no more implicit blank line generation

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/NEWS
    trunk/doc/texinfo.txi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2013-03-02 01:34:20 UTC (rev 5217)
+++ trunk/ChangeLog     2013-03-02 23:58:34 UTC (rev 5218)
@@ -1,3 +1,9 @@
+2013-03-02  Karl Berry  <address@hidden>
+
+       * NEWS,
+       * doc/texinfo.txi (Macro Details): behavior of newlines in macro
+       definitions and line-delimited commands has changed.
+
 2013-03-02  Patrice Dumas  <address@hidden>
 
        * tp/Texinfo/Parser.pm: put the first line in 'pending' instead of 

Modified: trunk/NEWS
===================================================================
--- trunk/NEWS  2013-03-02 01:34:20 UTC (rev 5217)
+++ trunk/NEWS  2013-03-02 23:58:34 UTC (rev 5218)
@@ -86,16 +86,24 @@
   version worthwhile for users nevertheless.
 
 * Intentional incompatibilities:
-  . The previous makeinfo implementation accepted text inside @itemize,
-    @enumerate, etc., not within the scope of an @item.  This is
-    semantically inconsistent, leading to problems with some backends,
-    and thus now produces a warning.
+  . The previous makeinfo implementation accepted a block of text inside
+    @itemize, @enumerate, etc., without any @item.  This is semantically
+    inconsistent, leading to problems with some backends, and thus now
+    produces a warning.
     
-  . The previous makeinfo accepted ``irregular'' sectioning trees.  Now
+  . The previous makeinfo accepted ``irregular'' sectioning trees.  Now,
     when @node pointers are implicitly determined, the consistency of
     @menu and the sectioning tree is checked.  (If node pointers are
     explicitly specified in the document, the tree can still be irregular.)
   
+  . The previous makeinfo always added blank lines between function
+    definitions if they weren't already there.  Now blank lines are not
+    added.
+    
+  . The previous makeinfo did not consider ends of lines from expansion
+    of an @macro definition to end an @-command line-delimited argument
+    (@chapter, @center, etc.).  This is no longer the case.
+
 * pod2texi is a new (Perl) program that uses the capabilities of
   texi2any to translate Perl pod documentation to Texinfo.
   

Modified: trunk/doc/texinfo.txi
===================================================================
--- trunk/doc/texinfo.txi       2013-03-02 01:34:20 UTC (rev 5217)
+++ trunk/doc/texinfo.txi       2013-03-02 23:58:34 UTC (rev 5218)
@@ -14854,8 +14854,8 @@
 @noindent
 will produce the string @samp{foobarbaz}.
 
address@hidden Otherwise, a comma should be explicitly quoted, as above, to be
-treated as a part of an argument.
address@hidden Otherwise, a comma should be explicitly quoted, as above, for it
+to be treated as a part of an argument.
 @end enumerate
 
 @cindex Braces, in macro arguments
@@ -14942,13 +14942,13 @@
 in @command{makeinfo}:
 
 @itemize @bullet
address@hidden @code{@@macro} and @code{@@unmacro} lines.
address@hidden @code{@@macro} and @code{@@unmacro} lines;
 
address@hidden @code{@@if...} lines, including @code{@@ifset} and similar,
address@hidden @code{@@if...} lines, including @code{@@ifset} and similar;
 
address@hidden @code{@@set}, @code{@@clear}, @code{@@value}.
address@hidden @code{@@set}, @code{@@clear}, @code{@@value};
 
address@hidden @code{@@clickstyle} lines.
address@hidden @code{@@clickstyle} lines;
 
 @item @code{@@end} lines.
 @end itemize
@@ -14956,14 +14956,14 @@
 @noindent Unfortunately, @TeX{} may do some expansion in these situations,
 possibly yielding errors.
 
-Also, due to unavoidable limitations, quite a few macro-related
-constructs cause problems with @TeX{}, as follows.  If you get
-macro-related errors when producing the printed version of a manual,
-you might try expanding the macros with @command{makeinfo} by invoking
+Also, quite a few macro-related constructs cause problems with @TeX{};
+some of the caveats are listed below.  Thus, if you get macro-related
+errors when producing the printed version of a manual, you might try
+expanding the macros with @command{makeinfo} by invoking
 @command{texi2dvi} with the @samp{-E} option (@pxref{Format with
address@hidden).  Or eschew Texinfo macros altogether and use a
-language designed for macro processing, such as M4 (@pxref{External
-Macro Processors}).
address@hidden).  Or, more reliably, eschew Texinfo macros altogether
+and use a language designed for macro processing, such as M4
+(@pxref{External Macro Processors}).
 
 @itemize @bullet
 @item
@@ -14979,12 +14979,28 @@
 All macros are expanded inside at least one @TeX{} group.
 
 @item
+Macro arguments cannot cross lines.
+
address@hidden
+Macros containing a command which must be on a line by itself, such as
+a conditional, cannot be invoked in the middle of a line.  Similarly,
+macros containing line-oriented commands or text, such as
address@hidden@@example} environments, may behave unpredictably in @TeX{}.
+
address@hidden
+White space is ignored at the beginnings of lines.
+
address@hidden
+Macros can't be reliably used in the argument to accent commands
+(@pxref{Inserting Accents}).
+
address@hidden
 The backslash escape for commas in macro arguments does not work;
 @code{@@address@hidden@}} must be used.
 
 @item
 As a consequence, if a macro takes two or more arguments, and you want
-to pass an argument with the Texinfo command @code{@@,} (for a
+to pass an argument with the Texinfo command @code{@@,} (to produce a
 cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or
 another work-around.  Otherwise, @TeX{} takes the comma as separating
 the arguments.  Example:
@@ -15010,22 +15026,6 @@
 in @TeX{}, so there is no other solution.
 
 @item
-Macro arguments cannot cross lines.
-
address@hidden
-Macros can't be reliably used in the argument to accent commands
-(@pxref{Inserting Accents}).
-
address@hidden
-Macros containing a command which must be on a line by itself, such as
-a conditional, cannot be invoked in the middle of a line.  Similarly,
-macros containing line-oriented commands or text, such as
address@hidden@@example} environments, may behave unpredictably in @TeX{}.
-
address@hidden
-White space is ignored at the beginnings of lines.
-
address@hidden
 It is usually best to avoid comments inside macro definitions, but
 see the next item.
 
@@ -15109,10 +15109,36 @@
 and @code{@@end macro} (likewise for @code{@@rmacro}) must be
 correctly paired.  For example, you cannot start a macro definition
 within a macro, and then end that nested definition outside the macro.
-
 @end itemize
 
+In the @code{makeinfo} implementation before Texinfo 5.0, ends of
+lines from expansion of an @code{@@macro} definition did not end an
+@@-command line-delimited argument (@code{@@chapter}, @code{@@center},
+etc.).  This is no longer the case.  For example:
 
address@hidden
+@@macro address@hidden@}
+aaa
+bbb
+@@end macro
+@@center @@address@hidden@}
address@hidden example
+
+In the current @code{makeinfo}, this is equivalent to:
+
address@hidden
+@@center aaa
+bbb
address@hidden example
+
address@hidden with just @samp{aaa} as the argument to @code{@@center}.  In
+the earlier implementation, it would have been parsed as this:
+
address@hidden
+@@center aaa bbb
address@hidden example
+
+
 @node @t{@@alias}
 @section @samp{@@alias @address@hidden
 
@@ -17614,7 +17640,7 @@
 of the tree obtained by parsing the input texinfo document.
 
 @item parse
-Do only the Texinfo source parsing phase.  There is no output in that case.
+Do only Texinfo source parsing; there is no output.
 
 @item plaintexinfo
 Output the Texinfo source with all the macros, @code{@@include} and
@@ -17629,8 +17655,8 @@
 for file names and copyright text in HTML comments, for example.
 
 @item structure
-Do the Texinfo source parsing and determination of the document structure.
-There is no output in that case.
+Do only Texinfo source parsing and determination of the document
+structure; there is no output.
 
 @item texinfosxml
 @cindex SXML output