Re: [PATCH] Fix up recent texinfo regression

[Martin Sebor <msebor at gmail dot com>]

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