Re: GDP: chattiness in @seealso

[Graham Percival]

Mats Bengtsson wrote:
> 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?

Let's go with "main text".  I'm not completely dead-set on this option, 
but I don't think anybody is going to seriously argue against it.

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

The problem with an item list is that it raises questions about anything 
which is _not_ on the list.  For example, @ref{Ties} doesn't appear in 
the item list in Durations.  And if we move all the explanations away 
from the @seealso, it would seem really weird to include @ref{Ties} in 
the main text, then again in an item list in the main text, then _again_ 
in the complete reference list in @seealso.

So right now my vote is to describe anything which needs describing in 
the main text.

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

I can't think of any /nice/ layout.  A list that alternates 
full-sentences and single-word references is going to look weird.  A 
typical comma-separated horizontal list would still look slightly 
awkward even with the parenthetical remarks.


With all that in mind, I'm proposing that we move all sentences into the 
main text, and have a simple
@seealso

Notation Reference: @ref{foo}, @ref{bar}.



> - Is there a need to repeat all links from the main text also in @seealso?

Perhaps not a need, but I feel a strong desire to do so.  It's a simple 
enough job for the Formatters.


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

I deliberately decided not to spend time agonizing over this.  I just 
dumped Han-Wen's email in that section.  As a general rule, the @refbugs 
will be more technical, harder to understand, and may possibly be a 
simple copy&paste from a hacker's email or bug respose.

Making @refbugs easier to read might be something to schedule in the 
third round of GDP, but certainly not before that.  (first round: making 
GDP presentable again.  Second round: making GDP significantly better 
than 2.11 in all respects.  Third round: perfection)

Cheers,
- Graham