[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: GDP: chattiness in @seealso
From: |
Graham Percival |
Subject: |
Re: GDP: chattiness in @seealso |
Date: |
Fri, 16 Nov 2007 21:55:41 -0800 |
User-agent: |
Thunderbird 2.0.0.6 (X11/20071022) |
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