Hans-Peter Nilsson: Did you have any follow up here? Or did this
response (below) address all your concerns?
I have made some minor corrections since this post:
- "make dvi" now builds my text without errors (can't say this for the
rest of extend.texi).
- All (instead of nearly all) the asm-related subjects are now in the
same menu.
- Minor cleanup of asm prototype for Extended Asm.
Before re-posting this ~60k patch, I thought I'd wait to see if you (or
anyone else) had any final comments. If you want to see a
human-readable version with all the current updates, it's at:
http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html
The first two sections on this menu ("Basic Asm" & "Extended Asm")
contain all the new text. The last four sections were just moved from
elsewhere to this menu to group all asm-related items together.
If there are no more comments by this time tomorrow, I'll re-post the
"final" patch.
Thanks,
dw
On 4/8/2014 10:29 PM, dw wrote:
On 4/8/2014 4:17 PM, Hans-Peter Nilsson wrote:
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 (limegreenso...@yahoo.com)
Andrew Haley (a...@redhat.com)
Richard Sandiford (rdsandif...@googlemail.com)
* extend.texi: Completely rewrite inline asm section /
minor reorg
of asm-related sections
(No other feedback since friday?)
Most people who had input probably responded in the RFD on the GCC
list (http://gcc.gnu.org/ml/gcc/2014-02/msg00511.html).
I haven't heard from the doc maintainers yet, but I understand that at
least one of them is out of town.
Thanks for doing this!
Thank you for the response and the feedback.
There are some *minor* issues, like two-spaces-after-"." which
(IIRC) makes a semantic difference in texinfo,
I wasn't aware this was a thing. All those years of typing classes
make this habit hard to break. Doing a search, it appears my changes
aren't the only place in extend.texi that does this. I've fixed mine.
and missing use
of texinfo markup like @emph{not} instead of NOT.
Hmm. If this is a standards thing, I suppose I should. Looks like I
only did it twice (and both in the same paragraph). Fixed.
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?
Sorry. Again, I didn't know this was a thing. texinfo doesn't seem
to mind, and the html pages I was generating didn't seem to care either.
I've fixed most of this. There are a couple of places I need someone
who is better at texinfo/formatting to help me out.
Also, code snippets in texinfo
should use GNU formatting, including comments (full sentences
with capitalization and full stop).
I've fixed up the things I can see, but I'm no expert in GNU
formatting. If there's more, I'll need someone to tell me what is
needed.
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).
I'd be tempted to debate this one, but I think I'm just going to
change it instead. Worms, cans, fixed.
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.)
I don't believe that section you are talking about was actually
deleted, but has instead been moved (along with "Asm Labels" and "Size
of an asm"). Looking at the new docs, instead of those sections being
buried with the ~60 other items like in the old docs
(http://gcc.gnu.org/onlinedocs/gcc-4.8.0/gcc/C-Extensions.html),
(nearly) all the asm-related subjects got moved here
(http://www.LimeGreenSocks.com/gcc/Using-Assembly-Language-with-C.html).
That's what the "minor reorg of asm-related sections" was about.
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?
I got that trick (formatting and all) from the existing docs. Such
being the case, the question is do we want to @emph{stop} promising
something that we used to? I have no preference here, other than the
general desire to maintain backward compatibility. I have not yet made
any change here.
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
I got it off the contrib page
(http://gcc.gnu.org/contribute.html#docchanges) when I was trying to
figure out the "proper" way to submit this. If this is no longer a
requirement, perhaps this should be updated.
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.
I can try again to get this working. I was hoping "make html" would
cover most of it. With luck, "make dvi" would have shown nothing
new. I was focusing on the text since I figured there were likely
plenty of people with correctly functioning build environments to give
this bit a test.
dw
