Proposed doc update for Explicit Reg Vars 1/3

[David Wohlferd]

Having updated the docs for Basic asm, Extended asm, and Asm Labels, I 
am now sending my patches for the last of the inline asm sections: 
Explicit Reg Vars.

My first attempt to update this got postponed (see 
https://gcc.gnu.org/ml/gcc-patches/2014-06/msg02369.html).  This patch 
addresses the previous concerns.

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.

Using Explicit Register variables is a feature that doesn't get a lot of 
attention (why should it?), which probably explains why no one has taken 
time to polish it up.  But now it has annoyed someone who is willing to 
work on it.

The are 3 web pages associated with Explicit Reg Vars (Menu, Global, and 
Local), so I am sending this as 3 patches.  The first patch (attached) 
is the menu page.

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 
"register variable"?

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:

Here's the current text: 
https://gcc.gnu.org/onlinedocs/gcc/Explicit-Reg-Vars.html
And here's the new: 
http://limegreensocks.com/gcc/Explicit-Register-Variables.html

dw


-------------- next part --------------
A non-text attachment was scrubbed...
Name: exp1.patch
Type: text/x-patch
Size: 6295 bytes
Desc: not available
URL: <https://gcc.gnu.org/pipermail/gcc/attachments/20151012/1a6fd53d/attachment.bin>