Re: Documentation for Named References

[Joel E. Denny]

On Thu, 26 Nov 2009, Alex Rozenman wrote:

> Thank you for your comments. I pushed the attached commit to master and to
> branch-2.5.

Thanks.

I just noticed that, within chapter 3, your section "3.5.6 Using Named 
References" including its discussion of locations comes before chapter 3 
formally introduces locations.  What do you think of moving your section 
up a level and making it section 3.7 after "3.6 Tracking Locations"?

> > address@hidden Named References
> > > address@hidden Using Named References
> >
> 
> I just noticed that almost all sections have "short" node names and somehow
> more elaborated subsection names. Have I missed something here ?

I have noticed that too.  However, as you point out, not every section 
makes them different.  That says to me that it's not necessary.  
Moreover, I have not noticed any ill effects of keeping them the same, and 
I dislike pointless discrepancies as they usually lead to mistakes.  For 
example, in both the texinfo source and the generated manual, the section 
titles and node names "Locations Overview", "Tracking Locations", and 
"Locations" are sometimes used interchangeably to refer to the same 
sections.  That needs to be fixed, but I haven't gotten around to it.

> I also added $name, $[name], @name and @[name] into "symbols" section.

Thanks.

> +It often happens that named references are followed by a dot, dash or other
> +C punctuation marks and operators.  By default, Bison will read
> address@hidden as a reference to symbol value @code{$name} followed by
> address@hidden, i.e., an access to the @samp{suffix} field of the semantic
> +value.  In order to force Bison to recognize @code{name.suffix} in its 
> entirety
> +as the name of a semantic value, bracketed syntax @code{$[name.suffix]}
> +must be used.

I would have kept that @samp{suffix} as an @code because it refers to the 
name of a field.  Likewise, @code{$name} is the name of a semantic value, 
so @code seems to make sense.  In the preceding @samp{.suffix}, the dot is 
not part of the field name, so you're referencing literal programming 
text, so that's why I thought it should be @samp.  Actually, given the 
wording in this paragraph ("Bison will read" or "Bison to recognize"), the 
rest of the @code's seem to be meant to discuss literal programming text 
as well, so it may be more reasonable to make them @samp's, but I am not 
sure.  Would anyone with more texinfo experience care to chime in?  Akim?