[DOC PATCH] Rewrite docs for inline asm

[Hans-Peter Nilsson]

On Fri, 4 Apr 2014, dw wrote:
> Problem description:
> The existing documentation does an inadequate job of describing gcc's
> implementation of the "asm" keyword.  This has led to a great deal of
> confusion as people struggle to understand how it works. This entire section
> requires a rewrite that provides a structured layout and detailed descriptions
> of each of the parameters along with examples.
>
> ChangeLog:
> 2014-04-03 David Wohlferd (LimeGreenSocks@yahoo.com)
>            Andrew Haley (aph@redhat.com)
>            Richard Sandiford (rdsandiford@googlemail.com)
>
>            * extend.texi: Completely rewrite inline asm section / minor reorg
> of asm-related sections

(No other feedback since friday?)

Thanks for doing this!

There are some *minor* issues, like two-spaces-after-"." which
(IIRC) makes a semantic difference in texinfo, and missing use
of texinfo markup like @emph{not} instead of NOT.  Also, in the
ChangeLog is the first of many overly long lines.  Please keep
lines shorter than 80 chars like the rest of extend.texi,
somewhere between 70-79 chars?  Also, code snippets in texinfo
should use GNU formatting, including comments (full sentences
with capitalization and full stop).

Also,

+   : [d] "=rm" (d)
+   : [e] "rm" (*e)
+   : );

That last bit, the ": )" (empty last operand part) shouldn't be
in the documentation.  I'm not even sure it *should* work
(apparently it does, perhaps by accident).

The general bits seems like a big improvement, but what worries
me is the deleted text.  For example, the aspects of "Explicit
Reg Vars" when *directly feeding an asm* and how to write them
to avoid the named registers being call-clobbered between
assignment and the asm.  (Don't confuse this with the
asm-clobber operands which I think you covered fine.)  Those
details are maybe not thoughtfully described, but they can't be
just plainly removed as they also serve as gcc specification;
definitions as to what works and doesn't work!  (I don't know if
that was the only occurrence.)

Also, do we really want to document the trick in
 "m" ((@{ struct @{ char x[10]; @} *p = (void *) ptr ; *p; @}))
(note: reformatted GNU-style and confusing @{ @} dropped)
IIRC this is from Linux, but I don't think GCC ever promised the
described semantics, and I don't think we should document
something that works just by accident.  Do we want to make that
promise now?

> Bootstrapping and testing:
> I have tested "make html" to produce html files, but my configuration doesn't
> allow for the "make dvi" test.

That requirement is somewhat arcane but maybe "make pdf" would
work for you?  (Though may or may not use dvi as an intermediate
step.)  The point is to verify the layout; what goes into the
info files is often different to what goes into the printable
format.

brgds, H-P