Re: Documentation for Named References

[Akim Demaille]

Great work Alex!


Le 27 nov. 2009 à 12:21, Joel E. Denny a écrit :

>>> 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 have been bothered by this too.  That's also why Bison's documentation uses 
the long versions of the @ref's Texinfo commands.  Another annoyance is that we 
cannot use the automatically generated @menus, they are so heavily tuned by 
hand...

That's the only Texinfo I practiced that goes into so much pain (I'm thinking 
about the three Autotools, M4, and a2ps mainly).  But it's also one of the most 
carefully written Texinfo document I know.  It's a very nice book in itself, 
not a plain reference manual. It features a very well done index, 
cross-reference sections, etc.  And there used to be a cheat-card (wow, it is 
still there!).

As some remains in the Texinfo source might still show, I believe at some point 
great attention was given by the FSF in order to make it a nice book to print 
and sell.  And indeed, when under Info, long names are painful, yet in printed 
copies too terse sentences are not veru nice looking.  Actually I don't know 
the first author, Charles Donnelly, maybe he is a technical writer?  But it 
always struck me that he is nowhere else credited in the package, not even a 
single line in the ChangeLog.

That's why I tried, as much as possible, to stick to the original conventions.  
But it's hard to keep that level of quality.  We need a genuine editor.  Or 
schedule some work for the documentation itself, not incremental changes driven 
by new features in Bison.

>> 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?

Your suggestion is exactly how I would have written too.  A case where I would 
have used @samp three times would have been

        Bison will read @samp{$name.suffix} as @samp{$name} and then 
@samp{.suffix}.

or even

        @samp{$name}, @samp{.}, and @samp{suffix}

(not trying to make sense about Bison here, just pointing out the difference 
between referring to inert lexical components, as opposed to semantic shift 
when you refer to the @code{suffix} field in the @code{$name} symbol value.)

But I guess mileages vary a lot in this area.  At least, in the case of 
bison.texinfo, that's what I have in mind.