[binutils-gdb] RISC-V: improve .insn documentation

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

commit cc3d3fbb879e9eb9e82551d06c04f210e93c4389
Author: Jan Beulich <[email protected]>
Date:   Fri May 15 09:46:15 2026 +0200

    RISC-V: improve .insn documentation
    
    First of all, the "type" form of .insn does not permit (not even
    optionally) a comma after the type, much like for ordinary insns a comma
    is not permitted between insn mnemonic and first operand. The example
    given actually properly shows that already.
    
    While there, also update the .word related text: Mapping symbols have been
    in use for quite some time.

Diff:
---
 gas/doc/c-riscv.texi | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/gas/doc/c-riscv.texi b/gas/doc/c-riscv.texi
index c6c4081c204..bd296c3de04 100644
--- a/gas/doc/c-riscv.texi
+++ b/gas/doc/c-riscv.texi
@@ -229,23 +229,22 @@ by rv32imac.
 @end table
 
 @cindex INSN directives
-@item .insn @var{type}, @var{operand} [,...,@var{operand_n}]
+@item .insn @var{type} @var{operand} [,...,@var{operand_n}]
 @itemx .insn @var{insn_length}, @var{value}
 @itemx .insn @var{value}
 This directive permits the numeric representation of an instructions
 and makes the assembler insert the operands according to one of the
 instruction formats for @samp{.insn} (@ref{RISC-V-Formats}).
 For example, the instruction @samp{add a0, a1, a2} could be written as
-@samp{.insn r 0x33, 0, 0, a0, a1, a2}.  But in fact, the instruction
-formats are difficult to use for some users, so most of them are using
-@samp{.word} to encode the instruction directly, rather than using
-@samp{.insn}.  It is fine for now, but will be wrong when the mapping
-symbols are supported, since @samp{.word} will not be shown as an
-instruction, it should be shown as data.  Therefore, we also support
-two more formats of the @samp{.insn}, the instruction @samp{add a0, a1, a2}
-could also be written as @samp{.insn 0x4, 0xc58533} or @samp{.insn 0xc58533}.
-When the @var{insn_length} is set, then assembler will check if the
-@var{value} is a valid @var{insn_length} bytes instruction.
+@samp{.insn r 0x33, 0, 0, a0, a1, a2}.  But in fact, the instruction formats
+are difficult to use for some users, so most of them are using @samp{.word} to
+encode the instruction directly, rather than using @samp{.insn}.  This goes
+wrong with the use of mapping symbols, since @samp{.word} will not be shown as
+an instruction; it is shown as data.  Therefore, we also support two more
+formats of @samp{.insn}.  Said instruction could also be written as
+@samp{.insn 0x4, 0xc58533} or @samp{.insn 0xc58533}.  When the
+@var{insn_length} form is used, the assembler will check if @var{value} is a
+valid @var{insn_length} bytes instruction.
 
 @cindex @code{.attribute} directive, RISC-V
 @item .attribute @var{tag}, @var{value}