This is the mail archive of the
mailing list for the GCC project.
Re: Proposed doc update for Explicit Reg Vars 1/3
- From: Jeff Law <law at redhat dot com>
- To: David Wohlferd <dw at LimeGreenSocks dot com>, "gcc at gcc dot gnu dot org" <gcc at gcc dot gnu dot org>
- Cc: Sandra Loosemore <sandra at codesourcery dot com>, Segher Boessenkool <segher at kernel dot crashing dot org>
- Date: Mon, 19 Oct 2015 15:15:52 -0600
- Subject: Re: Proposed doc update for Explicit Reg Vars 1/3
- Authentication-results: sourceware.org; auth=none
- References: <561C2EDB dot 8020400 at LimeGreenSocks dot com>
On 10/12/2015 04:06 PM, David Wohlferd wrote:
That's probably exactly how it grew over time. As issues were
discovered, doc text was added, but nobody ever stepped back and look at
the section as a whole.
Note that there is nothing actually "wrong" with the existing text. It
does not provide inaccurate information or miss key details. The
problem is that (from a compiler user's point of view) the text is hard
to follow. It reads as though people just have just dropped in new text
as it occurs to them, without ever going back to put things in context,
add formatting, etc.
Probably an attempt to help guide which of the two pages one ought to
The current menu page has a couple of flaws:
1) It tries to condense the entire contents of the other 2 pages into a
single paragraph each. This loses a lot of detail and nuance, as well
as introducing unnecessary duplication of information with the subpages.
2) What the heck is a "reg var"? Why can't we just call this a
Instead of trying to fix/clarify/update the duplicated information, this
patch removes it, then provides enough information to differentiate the
two types of register variables, and finally directs people to the
appropriate subpages which already contain all the information from this
page (and more).
It also changes the section names (and refs within the docs) to avoid
the unnecessary abbreviations. As part of this, it also uses @anchor to
ensure that any external links to the old names will still resolve
correctly. Is this the standard? Or do we just let them fail?
For people who find the HTML easier to review:
Looks good to me.
IIRC, you didn't have commit access, so I'll go ahead and commit this