[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi
From: |
karl |
Subject: |
texinfo ChangeLog doc/texinfo.txi |
Date: |
Thu, 13 Sep 2012 18:02:58 +0000 |
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}
- texinfo ChangeLog doc/texinfo.txi, (continued)
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/04
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/06
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/06
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/07
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/07
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/08
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/09
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/09
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/10
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/12
- texinfo ChangeLog doc/texinfo.txi,
karl <=
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/15
- texinfo ChangeLog doc/texinfo.txi, karl, 2012/09/23