Re: GDP: chattiness in @seealso

[Eyolf Østrem]

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.

Agreed.

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

Eyolf

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