[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation for Named References
From: |
Akim Demaille |
Subject: |
Re: Documentation for Named References |
Date: |
Wed, 30 Dec 2009 22:14:00 +0100 |
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.