Re: GDP: chattiness in @seealso

[Mats Bengtsson]

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

  /Mats