[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GDP: chattiness in @seealso

From: Mats Bengtsson
Subject: Re: GDP: chattiness in @seealso
Date: Fri, 16 Nov 2007 14:41:18 +0100
User-agent: Thunderbird (X11/20070716)

Graham Percival wrote:
At the very least, I want it clear which sentence refer to the Notation Reference, and which sentences refer to the other parts of the docs.

... I _really_ think this is completely unnecessary, though. And if you want to add full sentences to every single notation reference @ref{}, I assume you want to do the same for every @lsr{dir,snippet}, every @internalsref{}, etc ?

Mats, you're the yardstick for efficient NR use. What do you think of the compact vs. full sentence form of @seealso ? I don't want to approve any change that makes the NR harder to use for knowledgeable users, and IMO this is one such change.
In my opinion, the main issue is not how chatty the @seealso is but rather how
much information you include and where you place it. Regarding your current
version of "Durations", I think it's great to mention about and reference to all these issues that are related to the main topic of the section. One question is if this information should be below @seealso or in the main text. I have previously mainly thought of the @seealso as a kind of reference list ("bibliography") as it is used in scientific papers, i.e. a collection of all cross references mentioned in the main text. In "Durations", you instead use @seealso to introduce new concepts/issues that have not been mentioned in the main text and I kind of like the idea of putting
these in an item list, where they are easier to spot than in running text.
Still, for cross references that have already been mentioned in the main text,
it would seem chatty to repeat part of the information again in @seealso.
For the link to "Proportional duration", for example, it's probably necessary
to provide the concept in a full sentence, so the readers realize what the
link is all about. For "Writing rests", on the other hand, it's pretty obvious
from the section name itself.

I'm not sure what the conclusion is, but maybe we can reformulate the original
question into:
- Should we introduce some new concepts under @seealso or should this
 always be done in the main text?
- For issues that are somewhat peripheral and just need a short intro and a
cross reference, should they be described in running text or in an item list? - Under @seealso, can we find a nice layout that allows for a mix of pure links which already have self-explanatory names, with links that need a sentence of
- Is there a need to repeat all links from the main text also in @seealso?

A side comment: in "Durations" under @refbugs, the term "glyphs"
is used several times. Is this is term that is well-known to all readers, or
is it only known to hackers?


reply via email to

[Prev in Thread] Current Thread [Next in Thread]