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

[Graham Percival]

On Sun, 27 Apr 2008 20:43:20 +0200
John Mandereau <address@hidden> wrote:

> Le samedi 26 avril 2008 __ 03:53 -0700, Graham Percival a __crit :
> > right?  Why would the formatting be different in the Snippet
> > document than in the manuals?  Just make it
> > @emph{\NAME\}
> > or something like that.
> 
> No, because it would not enough to write a cross reference to an
> individual snippet -- a particular place in a Texinfo document can be
> cross-referenced only with @node or @anchor.  I know you don't want to
> point to individual snippets, but I think it's worthwhile.

No.  Since I said that I'd wait until Monday, and I guess it's
Monday somewhere in the world.

Most of David's arguments were actually in /favor/ of removing @lsr; he
just didn't realize that @lsr produced a reference instead of the
actual snippet. No fault of his, since it was a stupidly-named macro in
the first place.


- if a snippet is important, it gets a @lilypondfile.
- if it's not so important, people can find it in the snippet list.

If we start including references to snippets, readers will wonder why X
snippet got a reference, but Y snippet didn't.  So then we start adding
references to every snippet related to a doc subsubsection, which will
take over 10 hours.

More importantly, whenever we add 1 new snippet from LSR, we need to
look through the *entire* manual to find places that should reference
that snippet.  Essentially we've just thrown out the advantage of LSR
tags -- or rather, replaced the automatic LSR tag system with our own
inefficient non-automatic mechanism.  One new snippet could cause half
a dozen lines to be modified in the .itely files.

That's *completely* against the spirit of GDP: the whole idea was to
design the docs in such a way that the doc team could vanish for a year
and still have reasonable docs.  Provided that somebody spend 10
minutes once a month running makelsr.py, we have that.  If we add
references to specific snippets, that time balloons to 2 hours a month
-- *and* requires familiarity with the entire manual, which is an
extremely big no-no IMNSHO.


The automatic link checker isn't sufficient.  @lilypondfile will fail
*immediately* if somebody screws it up (or if a snippet is renamed).
The link checker will fail whenever somebody runs it -- that means that
the person fixing the typo'd snippet name won't be the person who made
that typo, which is again a bad thing.

Cheers,
- Graham