[Top][All Lists]

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

Re: GDP: chattiness in @seealso

From: Eyolf Østrem
Subject: Re: GDP: chattiness in @seealso
Date: Fri, 16 Nov 2007 01:39:00 +0100
User-agent: Mutt/1.5.15-muttng (2007-04-06)

On 15.11.2007 (16:19), 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 ?

No, not really. My only concern -- since you asked for general principles
-- is that there shouldn't be a rule to preclude explanation where it is
desirable. This will be the case, I imagine, with references to some
complicated function in an altogether general section, or in other cases
where the reference in its barest form is less than obvious. In many cases,
I agree that an extra description will be fluff and should be avoided.

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

How do you define a knowledgeable user in this respect? One who is
knowledgeable in using the docs will know to look for links in the seealso
sections, and I can't see how it would make it more difficult to use it
with an extra pointer or two (like "Remember to bring the towel from your
hotel room") -- and one as knowledgeable about LP as Mats probably won't
need those links in any case :)

sorry, the question wasn't for me, so I'll shut up.


Life, like beer, is merely borrowed.
                -- Don Reed

reply via email to

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