PR gas/3129

* doc/as.texinfo (Macro): Improve documentation about separating macro arguments from following text.

1 files changed, 64 insertions, 12 deletions

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 494381f..150ef30 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -4987,7 +4987,7 @@ definitions.  For example, these are all valid @code{.macro} statements:
 Begin the definition of a macro called @code{comm}, which takes no
 arguments.
 
-@item .macro plus1 p, p1
+@item  .macro plus1 p, p1
 @itemx .macro plus1 p p1
 Either statement begins the definition of a macro called @code{plus1},
 which takes two arguments; within the macro definition, write
@@ -5001,7 +5001,6 @@ After the definition is complete, you can call the macro either as
 @var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
 ,@var{b}} (with @samp{\p1} evaluating as the default, in this case
 @samp{0}, and @samp{\p2} evaluating to @var{b}).
-@end table
 
 @item .macro m p1:req, p2=0, p3:vararg
 Begin the definition of a macro called @code{m}, with at least three
@@ -5013,21 +5012,72 @@ When you call a macro, you can specify the argument values either by
 position, or by keyword.  For example, @samp{sum 9,17} is equivalent to
 @samp{sum to=17, from=9}.
 
+@end table
+
 Note that since each of the @var{macargs} can be an identifier exactly
 as any other one permitted by the target architecture, there may be
 occasional problems if the target hand-crafts special meanings to certain
-characters when they occur in a special position.  For example, if colon
+characters when they occur in a special position.  For example, if the colon
 (@code{:}) is generally permitted to be part of a symbol name, but the
-architecture specific code special-cases it when occuring as the final
+architecture specific code special-cases it when occurring as the final
 character of a symbol (to denote a label), then the macro parameter
 replacement code will have no way of knowing that and consider the whole
 construct (including the colon) an identifier, and check only this
-identifier for being the subject to parameter substitution.  In this
-example, besides the potential of just separating identifier and colon
-by white space, using alternate macro syntax (@xref{Altmacro}.) and
-ampersand (@code{&}) as the character to separate literal text from macro
-parameters (or macro parameters from one another) would provide a way to
-achieve the same effect:
+identifier for being the subject to parameter substitution.  So for example
+this macro definition:
+
+@example
+	.macro label l
+\l:
+	.endm
+@end example
+
+might not work as expected.  Invoking @samp{label foo} might not create a label
+called @samp{foo} but instead just insert the text @samp{\l:} into the
+assembler source, probably generating an error about an unrecognised
+identifier.
+
+Similarly problems might occur with the period character (@samp{.})
+which is often allowed inside opcode names (and hence identifier names).  So
+for example constructing a macro to build an opcode from a base name and a
+length specifier like this:
+
+@example
+	.macro opcode base length
+        \base.\length
+	.endm
+@end example
+
+and invoking it as @samp{opcode store l} will not create a @samp{store.l}
+instruction but instead generate some kind of error as the assembler tries to
+interpret the text @samp{\base.\length}.
+
+There are several possible ways around this problem:
+
+@table @code
+@item Insert white space
+If it is possible to use white space characters then this is the simplest
+solution.  eg:
+
+@example
+	.macro label l
+\l :
+	.endm
+@end example
+
+@item Use @samp{\()}
+The string @samp{\()} can be used to separate the end of a macro argument from
+the following text.  eg:
+
+@example
+	.macro opcode base length
+        \base\().\length
+	.endm
+@end example
+
+@item Use the alternate macro syntax mode
+In the alternative macro syntax mode the ampersand character (@samp{&}) can be
+used as a separator.  eg:
 
 @example
 	.altmacro
@@ -5035,9 +5085,11 @@ achieve the same effect:
 l&:
 	.endm
 @end example
+@end table
 
-This applies identically to the identifiers used in @code{.irp} (@xref{Irp}.)
-and @code{.irpc} (@xref{Irpc}.).
+Note - this problem of correctly identifying string parameters to pseudo ops
+also applies to the identifiers used in @code{.irp} (@xref{Irp}.) 
+and @code{.irpc} (@xref{Irpc}.) as well.
 
 @item .endm
 @cindex @code{endm} directive