Re: [MI tracepoints 9/9] documentation

[Stan Shebs <stan@codesourcery.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