Re: [MI tracepoints 9/9] documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Fri, 26 Mar 2010 11:08:45 +0300
> Cc: Stan Shebs <stan@codesourcery.com>,
>  tromey@redhat.com,
>  gdb-patches@sources.redhat.com
> 
> On Thursday 25 March 2010 22:33:24 Eli Zaretskii wrote:
> 
> > > Date: Thu, 25 Mar 2010 11:12:09 -0700
> > > From: Stan Shebs <stan@codesourcery.com>
> > > CC: Eli Zaretskii <eliz@gnu.org>, tromey@redhat.com, 
> > >  gdb-patches@sources.redhat.com
> > > 
> > > > Is comma actually required per english gramamar, or this is
> > > > texinfo quirk?
> > > >   
> > > It's a little of both actually. :-)
> > 
> > Right.  But mostly, it's a Texinfo quirk.
> 
> Thanks for clarifying. I've checked in the below.

Thank you.

Just to explain a bit further, the reason for this Texinfo requirement
is that otherwise the Info browser will be unable to find the end of
hyperlinks produced from an @xref with more than one argument.  Info
file is mostly an ASCII file, so it sometimes needs to use punctuation
for this purpose.

For example, this Texinfo source:

  @xref{Define, dont-repeat}

produces this in Info:

  *Note dont-repeat: Define

It should be clear now that without some special, known in advance,
character after "Define", an Info browser would not know where the
hyperlink ends.  "Define" is the name of a node that this hyperlink
references, so the Info browser _must_ deduce it reliably.  Info uses
a comma or a period for this purpose because these leave the sentence
grammatically correct.  That is why `makeinfo' bitches at you when you
don't put a period or a comma after the right brace of an @xref.