Re: removing @lsr{} and only using @lsrdir{}

[Graham Percival]

On Thu, 24 Apr 2008 10:13:03 +0200
"Valentin Villenave" <address@hidden> wrote:

> 2008/4/24 Graham Percival <address@hidden>:
> 
> >  Counter-arguments welcome for the next three or four days.  :)
> 
> As a lazy user, I always prefer being pointed to a specific snippet
> rather than a bunch of snippets I won't take the time to read. There's
> no way @lsr can't be more useful than @lsrdir (btw, didn't we plan to
> rename @lsrdir in @lsrtag at some point?)

a) you need to explain to every person working on the docs what
the difference is between @lsr, @lsrdir, and why @lsr isn't the
same as @lilypondfile.  Not just the current GDP people, but
anybody in the future.  I bet you $20 (canadian currency, not that
fake US stuff :)  that we keep the two commands, some programmer
(whose time is much better spent fixing bugs) asks what the
difference is within the next two years.  @rlsr is much easier to
maintain.

b) we *want* users to skim through the snippet list.  LilyPond can
do things that most people never think of -- even I get surprised
from time to time when I see neat snippets.  (IIRC the last time
was about a month ago)

c) if a snippet is extremely relevant, we'll include it directly
with @lilypondfile.


Basically, do you personally want to add @lsr{} to all the
@seealso sections in Text?  More to the point, *why* add half a
dozen @lsr{} links that point to items already in the
@lsrdir{Text} list?

Also, remember that renamed snippets linked by @lsr{} won't produce a
build error -- in other words, we'll end up with a bunch of semi-broken
links (they'll still resolve to the Text list, just at the top of it)
without us knowing.

Everything about this screams "more trouble than it's worth" to me.

Cheers,
- Graham