On 10/12/2015 04:06 PM, David Wohlferd wrote:
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.
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.
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.
Probably an attempt to help guide which of the two pages one ought to
look at.
2) What the heck is a "reg var"? Why can't we just call this a
"register variable"?
No reason.
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
for you.
Thanks!
jeff
