[Patch docs 4/5] Update "Output Template/Statement" from md.texi

[James Greenhalgh <james dot greenhalgh at arm dot com>]

Hi,

This patch updates the text in the "Output Template" and "Output
Statement" sections of md.texi.

I was aiming to:

  * Remove outdated details of the compiler.
  * Remove long or obscure words that, while accurate, only served to
    obfuscate a simple idea.
  * Refer to similar things in a consistent fashion - in particular
    trying to keep consistent use of "insn" and "pattern".
  * Remove superflous examples, or waffling.

OK?

Thanks,
James

---
2015-01-06  James Greenhalgh  <james.greenhalgh@arm.com>

	* doc/md.texi (Output Template): Update text.
	(Output Statement): Likewise.

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index a589f5b..3b853c8 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -519,7 +519,7 @@ Like @code{match_op_dup}, but for @code{match_parallel} instead of
 @cindex percent sign
 The @dfn{output template} is a string which specifies how to output the
 assembler code for an instruction pattern.  Most of the template is a
-fixed string which is output literally.  The character @samp{%} is used
+fixed string which is output verbatim.  The character @samp{%} is used
 to specify where to substitute an operand; it can also be used to
 identify places where different variants of the assembler require
 different syntax.
@@ -528,9 +528,29 @@ In the simplest case, a @samp{%} followed by a digit @var{n} says to output
 operand @var{n} at that point in the string.
 
 @samp{%} followed by a letter and a digit says to output an operand in an
-alternate fashion.  Four letters have standard, built-in meanings described
-below.  The machine description macro @code{PRINT_OPERAND} can define
-additional letters with nonstandard meanings.
+alternate fashion.  Four letters and two punctuation characters have
+standard, built-in meanings described below.  The target macro
+@code{PRINT_OPERAND} can define additional letters or punctuation
+characters with nonstandard meanings.
+
+One use of nonstandard letters or punctuation following @samp{%} is to
+distinguish between different assembler dialects for the same machine.
+This is used in the m68k target to distinguish between Motorola and MIT
+assebler syntax.
+
+Motorola syntax requires periods in most opcode names, while MIT syntax
+does not. For example, the opcode @samp{movel} in MIT syntax is written as
+@samp{move.l} in Motorola syntax.  The same file of patterns is used for
+both kinds of output syntax, but the character sequence @samp{%.} is used
+in each place where Motorola syntax requires a period.  The
+@code{PRINT_OPERAND} macro is defined to ouput a period when compiling
+for the Motorola syntax, and to output nothing when compiling for the MIT
+syntax.
+
+Alternatively, if the target macro @code{ASSEMBLER_DIALECT} is defined,
+an output template of the form @samp{@{option0|option1|option2@}} can be
+used to output different variants of assembler language syntax
+(@pxref{Instruction Output}).
 
 @samp{%c@var{digit}} can be used to substitute an operand that is a
 constant value without the syntax that normally indicates an immediate
@@ -549,8 +569,8 @@ as if it were a memory reference.
 instruction.
 
 @samp{%=} outputs a number which is unique to each instruction in the
-entire compilation.  This is useful for making local labels to be
-referred to more than once in a single template that generates multiple
+entire compilation.  This is useful for creating local labels which may
+be referred to more than once in a single template that generates multiple
 assembler instructions.
 
 @samp{%} followed by a punctuation character specifies a substitution that
@@ -566,82 +586,68 @@ The template may generate multiple assembler instructions.  Write the text
 for the instructions, with @samp{\;} between them.
 
 @cindex matching operands
-When the RTL contains two operands which are required by constraint to match
-each other, the output template must refer only to the lower-numbered operand.
-Matching operands are not always identical, and the rest of the compiler
-arranges to put the proper RTL expression for printing into the lower-numbered
-operand.
-
-One use of nonstandard letters or punctuation following @samp{%} is to
-distinguish between different assembler languages for the same machine; for
-example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
-requires periods in most opcode names, while MIT syntax does not.  For
-example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
-syntax.  The same file of patterns is used for both kinds of output syntax,
-but the character sequence @samp{%.} is used in each place where Motorola
-syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
-defines the sequence to output a period; the macro for MIT syntax defines
-it to do nothing.
+When the RTL contains two operands which are required by their constraints
+to match each other, the output template must refer only to the
+lower-numbered operand.  Matching operands are not always identical,
+and only the lower-numbered operand is guaranteed to contain the
+RTL expression for printing.
 
 @cindex @code{#} in template
 As a special case, a template consisting of the single character @code{#}
-instructs the compiler to first split the insn, and then output the
-resulting instructions separately.  This helps eliminate redundancy in the
-output templates.   If you have a @code{define_insn} that needs to emit
-multiple assembler instructions, and there is a matching @code{define_split}
-already defined, then you can simply use @code{#} as the output template
-instead of writing an output template that emits the multiple assembler
-instructions.
+instructs the compiler to use a matching @code{define_split} expression
+to split the insn.  This will generate a new sequence of insns, which
+will then be output according to their own templates.  This helps eliminate
+redundancy in the output templates.
 
-If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
-of the form @samp{@{option0|option1|option2@}} in the templates.  These
-describe multiple variants of assembler language syntax.
-@xref{Instruction Output}.
-
-@node Output Statement
-@section C Statements for Assembler Output
-@cindex output statements
-@cindex C statements for assembler output
-@cindex generating assembler output
+@subsection Output Templates with Multiple Operand Constraints
+@cindex multiple output templates
 
 Often a single fixed template string cannot produce correct and efficient
 assembler code for all the cases that are recognized by a single
 instruction pattern.  For example, the opcodes may depend on the kinds of
-operands; or some unfortunate combinations of operands may require extra
-machine instructions.
+operands; or some combinations of operands may require extra machine
+instructions.
 
 If the output control string starts with a @samp{@@}, then it is actually
 a series of templates, each on a separate line.  (Blank lines and
 leading spaces and tabs are ignored.)  The templates correspond to the
-pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
-if a target machine has a two-address add instruction @samp{addr} to add
-into a register and another @samp{addm} to add a register to memory, you
-might write this pattern:
+pattern's constraint alternatives (@pxref{Multi-Alternative}).
+
+For example, if a target machine has a two-address add instruction
+@samp{addreg} to add into a register and another @samp{addmem} to add
+a register to memory, this pattern could be used to describe the
+instructions.
 
 @smallexample
 (define_insn "addsi3"
   [(set (match_operand:SI 0 "general_operand" "=r,m")
         (plus:SI (match_operand:SI 1 "general_operand" "0,0")
-                 (match_operand:SI 2 "general_operand" "g,r")))]
+                 (match_operand:SI 2 "general_operand" "r,r")))]
   ""
   "@@
-   addr %2,%0
-   addm %2,%0")
+   addreg %2,%0
+   addmem %2,%0")
 @end smallexample
 
+@node Output Statement
+@section C Statements for Assembler Output
+@cindex output statements
+@cindex C statements for assembler output
+@cindex generating assembler output
 @cindex @code{*} in template
 @cindex asterisk in template
+
 If the output control string starts with a @samp{*}, then it is not an
 output template but rather a piece of C program that should compute a
-template.  It should execute a @code{return} statement to return the
-template-string you want.  Most such templates use C string literals, which
-require doublequote characters to delimit them.  To include these
-doublequote characters in the string, prefix each one with @samp{\}.
+template string and return it.  Most such templates use C string
+literals, which require doublequote characters to delimit them.  To
+include these doublequote characters in the string, prefix each one
+with @samp{\}.
 
-If the output control string is written as a brace block instead of a
-double-quoted string, it is automatically assumed to be C code.  In that
-case, it is not necessary to put in a leading asterisk, or to escape the
-doublequotes surrounding C string literals.
+The output control string may also be written as a brace block instead of a
+double-quoted string.  In this case, it is also treated as C code.  When
+using the brace block form, it is not necessary to write the leading
+asterisk, or to escape the doublequotes surrounding C string literals.
 
 The operands may be found in the array @code{operands}, whose C data type
 is @code{rtx []}.
@@ -663,12 +669,11 @@ vector may be @code{operands}, or it may be another array of @code{rtx}
 that you declare locally and initialize yourself.
 
 @findex which_alternative
-When an insn pattern has multiple alternatives in its constraints, often
-the appearance of the assembler code is determined mostly by which alternative
-was matched.  When this is so, the C code can test the variable
-@code{which_alternative}, which is the ordinal number of the alternative
-that was actually satisfied (0 for the first, 1 for the second alternative,
-etc.).
+Where an insn pattern has multiple alternatives in its constraints, the
+appearance of the assembler code is often determined by which alternative
+was matched.  The variable @code{which_alternative} contains this
+information, and gives the ordinal number of the alternative that was
+chosen (0 for the first, 1 for the second alternative, etc.).
 
 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
 for registers and @samp{clrmem} for memory locations.  Here is how
@@ -701,8 +706,8 @@ as follows, having the output control string start with a @samp{@@}:
 @end group
 @end smallexample
 
-If you just need a little bit of C code in one (or a few) alternatives,
-you can use @samp{*} inside of a @samp{@@} multi-alternative template:
+Where C code in only needed in one (or a few) alternatives, you can
+use @samp{*} inside of a @samp{@@} multi-alternative template:
 
 @smallexample
 @group