Fix up recent texinfo regression

Hi!

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?

BTW, it also seems that we use see @xref{...}, or See @xref{...}, in various
places, that also looks wrong, for info that results in
see *note ...::,
but in *.pdf it is probably
see See ...,
Thus, perhaps we should check for this and remove the see/See words before
@xref, and if we want see instead of See in *.pdf, use @pxref.

2016-02-26  Jakub Jelinek  <jakub@redhat.com>

	* doc/extend.texi (__builtin_alloca, __builtin_alloca_with_align):
	Fix @xref usage.



	Jakub

On 02/26/2016 12:51 PM, Jakub Jelinek wrote:
> Hi!
>
> 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.

Martin

>
> BTW, it also seems that we use see @xref{...}, or See @xref{...}, in various
> places, that also looks wrong, for info that results in
> see *note ...::,
> but in *.pdf it is probably
> see See ...,
> Thus, perhaps we should check for this and remove the see/See words before
> @xref, and if we want see instead of See in *.pdf, use @pxref.
>
> 2016-02-26  Jakub Jelinek  <jakub@redhat.com>
>
> 	* doc/extend.texi (__builtin_alloca, __builtin_alloca_with_align):
> 	Fix @xref usage.
>
> --- gcc/doc/extend.texi.jj	2016-02-26 16:49:58.000000000 +0100
> +++ gcc/doc/extend.texi	2016-02-26 20:41:16.611200672 +0100
> @@ -10714,10 +10714,11 @@ it is the responsibility of its caller t
>   cause it to exceed the stack size limit.
>   The @code{__builtin_alloca} function is provided to make it possible to
>   allocate on the stack arrays of bytes with an upper bound that may be
> -computed at run time.  Since C99 @xref{Variable Length} Arrays offer
> +computed at run time.  Since C99 Variable Length Arrays offer
>   similar functionality under a portable, more convenient, and safer
>   interface they are recommended instead, in both C99 and C++ programs
>   where GCC provides them as an extension.
> +@xref{Variable Length}, for details.
>
>   @end deftypefn
>
> @@ -10761,10 +10762,10 @@ the argument doesn't cause it to exceed
>   The @code{__builtin_alloca_with_align} function is provided to make
>   it possible to allocate on the stack overaligned arrays of bytes with
>   an upper bound that may be computed at run time.  Since C99
> -@xref{Variable Length} Arrays offer the same functionality under
> +Variable Length Arrays offer the same functionality under
>   a portable, more convenient, and safer interface they are recommended
>   instead, in both C99 and C++ programs where GCC provides them as
> -an extension.
> +an extension.  @xref{Variable Length}, for details.
>
>   @end deftypefn
>
>
>
> 	Jakub
>

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.

	Jakub

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