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 _______________________________________________ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user