Re: [MI tracepoints 9/9] documentation

[Stan Shebs <stan at codesourcery dot com>]

Vladimir Prus wrote:
> On Thursday 25 March 2010 20:30:35 Vladimir Prus wrote:
>
>   
> > On Thursday 25 March 2010 07:05:57 Eli Zaretskii wrote:
> >
> >     
> > > > From: Tom Tromey <tromey@redhat.com>
> > > > Cc: gdb-patches@sources.redhat.com
> > > > Date: Wed, 24 Mar 2010 15:43:42 -0600
> > > >
> > > >         
> > > > > > > > > "Volodya" == Vladimir Prus <vladimir@codesourcery.com> writes:
> > > > > > > > >                   
> > > > Volodya> Sorry -- I think I did what I was asked to do, and I don't
> > > > Volodya> understand what this warning is trying to tell me. Assuming
> > > > Volodya> this is a valid warning, how do I fix it?
> > > >
> > > > According to the texinfo manual:
> > > >
> > > >      Caution: A period or comma *must* follow the closing brace of an
> > > >      `@xref'.  It is required to terminate the cross reference.  This
> > > >      period or comma will appear in the output, both in the Info file
> > > >      and in the printed manual.
> > > >
> > > > So I guess you ought to add a comma after the closing brace.
> > > >         
> > > Yes.
> > >       
> > So, 
> >
> > 	@xref{GDB/MI Frame Information} for description of this field.
> >
> > will become
> >
> > 	@xref{GDB/MI Frame Information}. for description of this field.
> >
> > ? I am not sure the result will be correct. What am I missing and how
> > do I express my original intent using texinfo?
> >     
>
> Oh, I've confused comma and period. Is comma actually required per english
> gramamar, or this is texinfo quirk?
>   
It's a little of both actually. :-) The comma is acceptable English 
usage in this context, but if the sentence and/or cross-reference are 
short, I think it reads poorly, sounding like a hesitation where no 
speaker would actually slow down.  But if the reference and sentence are 
both long, then you get a run-on sentence, and worse, possible ambiguity 
due to the juxtaposition of long cross-reference phrase and the 
remaining words of the sentence.  So the texinfo rule sacrifices some 
readability for reliability.

Stan