Proposed doc update for Explicit Reg Vars 1/3

[Jeff Law]

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