texinfo ChangeLog doc/texinfo.txi

[karl]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     karl <karl>     12/09/13 18:02:57

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        more about commas and multiple-argument macros

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1420&r2=1.1421
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.480&r2=1.481

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1420
retrieving revision 1.1421
diff -u -b -r1.1420 -r1.1421
--- ChangeLog   12 Sep 2012 23:35:58 -0000      1.1420
+++ ChangeLog   13 Sep 2012 18:02:57 -0000      1.1421
@@ -1,3 +1,9 @@
+2012-09-13  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Macro Details): yet more sticky points
+       regarding commas and multiple-argument macros.
+       Mail from Patrice, 25 Jul 2012 10:21:28.
+
 2012-09-13  Patrice Dumas  <address@hidden>
 
        * doc/refcard/txivarcheck (read_tp): filter out customization 

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.480
retrieving revision 1.481
diff -u -b -r1.480 -r1.481
--- doc/texinfo.txi     12 Sep 2012 23:35:58 -0000      1.480
+++ doc/texinfo.txi     13 Sep 2012 18:02:57 -0000      1.481
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.480 2012/09/12 23:35:58 karl Exp $
address@hidden $Id: texinfo.txi,v 1.481 2012/09/13 18:02:57 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.
 
@@ -14384,8 +14384,8 @@
 @cindex Running macros
 @cindex Macro invocation
 
-After a macro is defined (see the previous section), you can use
-(@dfn{invoke}) it in your document like this:
+After a macro is defined (see the previous section), you can
address@hidden (use) it in your document like this:
 
 @example
 @@@var{macroname} @address@hidden, @var{arg2}, @address@hidden
@@ -14410,7 +14410,7 @@
 @cindex Backslash, and macros
 Thus, the arguments and parameters are separated by commas and
 delimited by braces; any whitespace after (but not before) a comma is
-ignored.  The braces are required in the invocation, even when the
+ignored.  The braces are required in the invocation even when the
 macro takes no arguments, consistent with other Texinfo commands.  For
 example:
 
@@ -14428,17 +14428,17 @@
 @end display
 
 @cindex Comma, in macro arguments
-Passing strings containing commas as macro arguments requires special
-care, since they should be properly @dfn{quoted} to prevent
address@hidden from confusing them with argument separators.  To
-manually quote a comma, the most reliable method is to use the
address@hidden@@address@hidden@}} command.  For @code{makeinfo}, you can also 
prepend
-a backslash character, as in @samp{\,}, but this does not work with
address@hidden
-
-It's not always necessary to quote commas.  To facilitate use of
-macros, @command{makeinfo} implements a set of rules called
address@hidden quoting}:
+Passing macro arguments containing commas requires special care, since
+commas also separate the arguments.  To include a comma character in
+an argument, the most reliable method is to use the @code{@@address@hidden@}}
+command.  For @code{makeinfo}, you can also prepend a backslash
+character, as in @samp{\,}, but this does not work with @TeX{}.
+
address@hidden Automatic quoting of commas for some macros
address@hidden Quoting, automatic for some macros
+It's not always necessary to worry about commas.  To facilitate use of
+macros, @command{makeinfo} implements two rules for @dfn{automatic
+quoting} in some circumstances:
 
 @enumerate 1
 @item If a macro takes only one argument, all commas in its invocation
@@ -14508,14 +14508,14 @@
 
 Unfortunately, this has not been reliably implemented in @TeX{}.  When
 macros are used in the argument to other commands, for example, errors
-or incorrect output (the @samp{\} ``escape'' being included
-literally) are likely to result.
+or incorrect output (the @samp{\} ``escape'' being included literally)
+are likely to result.
 
-If the macro is defined to take exactly one argument, and is invoked
-without any braces, the entire rest of the line after the macro name
-is supplied as the argument.  (It's an error to specify the argument
-without braces if the macro takes either zero or more than one
-argument.)  For example:
+If a macro is defined to take exactly one argument, it can (but need
+not) be invoked without any braces; then the entire rest of the line
+after the macro name is used as the argument.  (Braces around the
+argument(s) are required in all other cases, i.e., if the macro takes
+either zero or more than one argument.)  For example:
 
 @example
 @@macro bar @address@hidden
@@ -14526,14 +14526,13 @@
 
 @noindent produces:
 
address@hidden Sorry for cheating, but let's not require macros to process the 
manual.
 @display
 Twice: aah & aah.
 @end display
 
-If the macro is defined to take exactly one argument, and is invoked
-with braces, the braced text is passed as the argument, regardless of
-commas.  For example:
+Likewise, if a macro is defined to take exactly one argument, and is
+invoked with braces, the braced text is passed as the argument, also
+regardless of commas.  For example:
 
 @example
 @@macro bar @address@hidden
@@ -14589,7 +14588,7 @@
 @item @code{@@end} lines.
 @end itemize
 
address@hidden @TeX{} may or may not do some expansion in these situations,
address@hidden Unfortunately, @TeX{} may do some expansion in these situations,
 possibly yielding errors.
 
 Also, due to unavoidable limitations, quite a few macro-related
@@ -14606,19 +14605,44 @@
 As mentioned earlier, macro names must consist entirely of letters.
 
 @item
-Macros may take at most nine arguments.
-
address@hidden
 It is not advisable to redefine any @TeX{} primitive, plain, or
-Texinfo command name as a macro. Unfortunately this is a very large
-set of names, and the possible resulting errors are unpredictable.
+Texinfo command name as a macro. Unfortunately this is a large and
+open-ended set of names, and the possible resulting errors are
+unpredictable.
 
 @item
 All macros are expanded inside at least one @TeX{} group.
 
 @item
-Commas in macro arguments, even if escaped by a backslash, don't
-always work.
+The backslash escape for commas in macro arguments does not work;
address@hidden@@address@hidden@}} must be used.
+
address@hidden
+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
+cedilla, @pxref{Inserting Accents}), you have to use @code{@@value} or
+another work-around.  Otherwise, @TeX{} takes the comma as separating
+the arguments.  Example:
+
address@hidden
+@@macro address@hidden, address@hidden
+\argfirst\+\argsecond\.
+@@end macro
+@@set fc Fran@@,cois
+@@address@hidden@@address@hidden@address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+Fran@,cois+.
address@hidden display
+
+The natural-seeming @code{@@address@hidden@@,address@hidden passes the two
+arguments @samp{Fran@@} and @samp{cois} to the macro, and nothing good
+results.  And, as just mentioned, although the comma can be escaped
+with a backslash for @code{makeinfo} (@samp{@@\,}), that doesn't work
+in @TeX{}, so there is no other solution.
 
 @item
 Macro arguments cannot cross lines.
@@ -14637,15 +14661,15 @@
 White space is ignored at the beginnings of lines.
 
 @item
-It is (usually) best to avoid comments inside macro definitions, but
+It is usually best to avoid comments inside macro definitions, but
 see the next item.
 
 @item
 In general, the interaction of newlines in the macro definitions and
-invocations depends on the precise commands and context, despite the
-previous statements.  You may be able to work around some problems
-with judicious use of @code{@@c}.  Suppose you define a macro that is
-intended to always be used on a line by itself:
+invocations depends on the precise commands and context,
+notwithstanding the previous statements.  You may be able to work
+around some problems with judicious use of @code{@@c}.  Suppose you
+define a macro that is always used on a line by itself:
 
 @example
 @@macro linemac
@@ -14657,10 +14681,10 @@
 bar
 @end example
 
-Without the @code{@@c}, there will be an unwanted blank line between
+Without the @code{@@c}, there will be a unwanted blank line between
 the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
-from the macro definition, one from after the invocation), causing a
-paragraph break.
+from the macro definition, one from after the invocation), causing an
+unwanted paragraph break.
 
 On the other hand, you wouldn't want the @code{@@c} if the macro was
 sometimes invoked in the middle of a line (the text after the
@@ -14702,7 +14726,6 @@
 \gdef\ctorx#1,#2,@address@hidden involving #2 address@hidden@}
 @@end tex
 @end example
-
 @end itemize
 
 The @command{makeinfo} implementation also has the following
@@ -14717,10 +14740,10 @@
 
 @item
 Macros that completely define macros are ok, but it's not possible to
-have incorrectly nested macro definitions.  That is, @code{@@macro}
+have incompletely nested macro definitions.  That is, @code{@@macro}
 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 the nested definition outside the macro.
+within a macro, and then end that nested definition outside the macro.
 
 @end itemize
 
@@ -21841,7 +21864,7 @@
 or other version control systems, which expand it into a string such
 as:
 @example
-$Id: texinfo.txi,v 1.480 2012/09/12 23:35:58 karl Exp $
+$Id: texinfo.txi,v 1.481 2012/09/13 18:02:57 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}