[binutils-gdb] S12Z (doc): Minor improvements to text and formatting.

[John Darrington <jmd at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=3e2cf42fe5c305ebb5a4a69427a37e950385ea60

commit 3e2cf42fe5c305ebb5a4a69427a37e950385ea60
Author: John Darrington <john@darrington.wattle.id.au>
Date:   Sat May 18 08:25:18 2019 +0200

    S12Z (doc): Minor improvements to text and formatting.
    
    gas/
    	* doc/c-s12z.texi: Miscellaneous adjustments.

Diff:
---
 gas/doc/c-s12z.texi | 100 ++++++++++++++++++++++++----------------------------
 1 file changed, 47 insertions(+), 53 deletions(-)

diff --git a/gas/doc/c-s12z.texi b/gas/doc/c-s12z.texi
index 29c0d86..b908747 100644
--- a/gas/doc/c-s12z.texi
+++ b/gas/doc/c-s12z.texi
@@ -16,55 +16,63 @@ dependent features.
 
 @cindex S12Z support
 @menu
-* S12Z-Opts::                   S12Z Options
-* S12Z-Syntax::                 Syntax
-* S12Z-Directives::             Assembler Directives
-* S12Z-Opcodes::                Opcodes
+* S12Z Options::                S12Z Options
+* S12Z Syntax::                 Syntax
 @end menu
 
-@node S12Z-Opts
+@node S12Z Options
 @section S12Z Options
 
 @cindex options, S12Z
 @cindex S12Z options
 
-The S12Z version of @code{@value{AS}} has the following options:
+The S12Z version of @code{@value{AS}} recognizes the following options:
 
+@table @samp
+
+@item -mreg-prefix=@var{prefix}
 @cindex @samp{-mreg-prefix=@var{prefix}} option, reg-prefix
 You can use the @samp{-mreg-prefix=@var{pfx}} option to indicate
-that the assembler expects each register name to be prefixed with the
+that the assembler should expect all register names to be prefixed with the
 string @var{pfx}.
 
 For an explanation of what this means and why it might be needed,
-see @ref{Register Notation}.
+see @ref{S12Z Register Notation}.
+@end table
 
-@node S12Z-Syntax
+@node S12Z Syntax
 @section Syntax
 
 
 @menu
-* Register Notation::                How to refer to registers
+* S12Z Syntax Overview::                  General description
+* S12Z Addressing Modes::                 Operands and their semantics
+* S12Z Register Notation::                How to refer to registers
 @end menu
 
 
 @cindex S12Z syntax
 @cindex syntax, S12Z
 
+@node S12Z Syntax Overview
+@subsection Overview
+
 In the S12Z syntax, the instruction name comes first and it may
-be followed by one or by several operands.
+be followed by one, or by several operands.
 In most cases the maximum number of operands is three.
+Operands are separated by a comma (@samp{,}).
+A comma however does not act as a separator if it appears within parentheses
+(@samp{()}) or within square brackets (@samp{[]}).
+@code{@value{AS}} will complain if too many, too few or inappropriate operands
+are specified for a given instruction.
+
 Some instructions accept and (in certain situations require) a suffix
 indicating the size of the operand.
 The suffix is separated from the instruction name by a period (@samp{.})
 and may be one of @samp{b}, @samp{w}, @samp{p} or @samp{l} indicating
 `byte' (a single byte), `word' (2 bytes), `pointer' (3 bytes) or `long' (4 bytes)
 respectively.
-Operands are separated by a comma (@samp{,}).
-A comma however does not act as a separator if it appears within parentheses
-(@samp{()}) or within square brackets (@samp{[]}).
-@code{@value{AS}} will complain if too many, too few or inappropriate operands
-are specified for a given instruction.
-The MRI mode is not supported for this architecture.
+
 Example:
 
 @smallexample
@@ -80,7 +88,6 @@ Example:
 @end smallexample
 
 @cindex line comment character, S12Z
-@cindex S12Z line comment character
 The presence of a @samp{;} character anywhere
 on a line indicates the start of a comment that extends to the end of
 that line.
@@ -98,8 +105,12 @@ directive (@pxref{Comments}) or a preprocessor control command
 The S12Z assembler does not currently support a line separator
 character.
 
+
+@node S12Z Addressing Modes
+@subsection Addressing Modes
 @cindex S12Z addressing modes
 @cindex addressing modes, S12Z
+
 The following addressing modes are understood for the S12Z.
 @table @dfn
 @item Immediate
@@ -110,7 +121,7 @@ The following addressing modes are understood for the S12Z.
 
 Bit field instructions in the immediate mode require the width and offset to
 be specified.
-The @var{width} pararmeter specifies the number of bits in the field.
+The @var{width} parameter specifies the number of bits in the field.
 It should be a number in the range [1,32].
 @var{Offset} determines the position within the field where the operation
 should start.
@@ -204,25 +215,25 @@ Otherwise it is treated as unsigned.
 For example:
 
 @smallexample
-	trap    #197
-	bra     *+49
-	bra     .L0
-	jmp     0xFE0034
-	jmp     [0xFD0012]
-	inc.b   (4,x)
-	dec.w   [4,y]
-	clr.p   (-s)
-	neg.l   (d0, s)
-	com.b   [d1, x]
-	jsr     (45, d0)
-	psh     cch
+	trap    #197        ;; Immediate mode
+	bra     *+49        ;; Relative mode
+	bra     .L0         ;;     ditto
+	jmp     0xFE0034    ;; Absolute direct mode
+	jmp     [0xFD0012]  ;; Absolute indirect mode
+	inc.b   (4,x)       ;; Constant offset indexed mode
+	jsr     (45, d0)    ;;     ditto
+	dec.w   [4,y]       ;; Constant offset indexed indirect mode
+	clr.p   (-s)        ;; Pre-decrement mode
+	neg.l   (d0, s)     ;; Register offset direct mode
+	com.b   [d1, x]     ;; Register offset indirect mode
+	psh     cch         ;; Register mode
 @end smallexample
 
-@node Register Notation
+@node S12Z Register Notation
 @subsection Register Notation
 
 @cindex register notation, S12Z
-Without a register prefix (@pxref{S12Z-Opts}), S12Z assembler code is expected in the traditional
+Without a register prefix (@pxref{S12Z Options}), S12Z assembler code is expected in the traditional
 format like this:
 @smallexample
 lea s, (-2,s)
@@ -250,13 +261,9 @@ Consider the following assembler instruction:
 st d0, d1
 @end smallexample
 @noindent
-This instruction is most likely to
-mean ``Store the value in the register D0 into the register D1'' and that is the
-default way in which @code{@value{AS}} interprets it.
-However it could also be intended to mean
-``Store the value in the register D0 into the memory referenced by the symbol
-named @samp{d1}''.
-If that is what is intended then @code{@value{AS}} must be invoked with
+The destination operand of this instruction could either refer to the register
+@samp{D1}, or it could refer to the symbol named ``d1''.
+If the latter is intended then @code{@value{AS}} must be invoked with
 @samp{-mreg-prefix=@var{pfx}} and the code written as
 @smallexample
 st @var{pfx}d0, d1
@@ -265,16 +272,3 @@ st @var{pfx}d0, d1
 where @var{pfx} is the chosen register prefix.
 For this reason, compiler back-ends should choose a register prefix which
 cannot be confused with a symbol name.
-
-
-@node S12Z-Directives
-@section Assembler Directives
-
-@cindex assembler directives, S12Z
-
-@node S12Z-Opcodes
-@section Opcodes
-
-@cindex S12Z opcodes
-@cindex opcodes, S12Z
-@cindex instruction set, S12Z