[PATCH] Fix up recent texinfo regression

[Martin Sebor]

On 02/26/2016 01:55 PM, Jakub Jelinek wrote:
> On Fri, Feb 26, 2016 at 01:09:57PM -0700, Martin Sebor wrote:
>> On 02/26/2016 12:51 PM, Jakub Jelinek wrote:
>>> I've noticed today:
>>> ../../gcc/doc/extend.texi:10717: warning: `.' or `,' must follow @xref, not A
>>> ../../gcc/doc/extend.texi:10764: warning: `.' or `,' must follow @xref, not A
>>>
>>> After reading info texinfo on @xref and @pxref, I believe it is invalid
>>> to use @xref this way, in the middle of a sentence, and indeed it looks
>>> quite weird what is produced.  So the following patch attempts to fix it up
>>> by using @xref in a separate sentence.  Tested on x86_64-linux, ok for
>>> trunk?
>>
>> Thanks for fixing it up.  I noticed the warning yesterday and have
>> been meaning to look into it.
>>
>> Your change seems fine to me though I wonder if using a plain @ref{}
>> instead would do the right thing.  It's used in a bunch of places to
>> refer to the Common Function Attributes section (for example).  That
>> way the referenced text wouldn't need to be repeated.
>
> It would read as
> See C99 Section x.y [Variable Length], page NN Arrays offer
> in the pdf
> and
> See C99 *note Variable Length:: Arrays offer
> if I read the texinfo doc right.  Both look just too weird to me.

I agree, that wouldn't look right.  What you have should look
better.

FWIW, more out of curiosity of how it works than anything else
I pulled up the PDF manual to see what some uses of @ref{} get
rendered as.  It doesn't look like the "Section X.Y" part is
there, contrary to my reading of the Texinfo manual.  For
example, the reference below:

   See also the @ref{AVR Named Address Spaces} section for
   an alternate way to locate and access data in flash memory.

looks like this in the GCC 5.3.0 PDF manual:

   See also the [AVR Named Address Spaces], page 382 section for
   an alternate way...

It doesn't look quite right either but the "Section X.Y" text
isn't here (the text in brackets is the link to the section).

There is a way to replace the name of the referenced section
with arbitrary text.  I found an example of it here:

   Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
   locates data in flash

which renders as

   Notice that attribute [progmem], page 434 locates data in
   flash

So presumably, to get what I was going for, the reference would
have to be written like so:

   Since C99 @ref{Variable Length,,Variable Length Arrays} offer
   similar functionality

although it would still have the "page 123" text appended to it.
I don't see how to avoid that.  It's probably best to stick to
only basic uses in sentences of their own or in parenthetical
notes.

Martin