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

[David Kastrup]

Graham Percival <address@hidden> writes:

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

Sorry, but that does not even make sense.  I have no idea how you get
this absurd notion.  Care to come up with a quotation from one of my
postings that would support your interpretation?  Why would I argue
about the accuracy of references (snippet vs snippet page) when I was
supposedly assuming that @lsr produced a snippet?  What would I
presumably have been arguing against then?  Including the whole snippet
page for every @lsr?

I can't believe that you think I was imagining something that absurd and
braindead the object of my reasoning.

> No fault of his, since it was a stupidly-named macro in the first
> place.

Please use somebody else for supporting your strawmen.  I want to see a
quotation from a posting of mine that could even remotely support your
idea of what I wrote.

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

Oh sure.  Because everybody expects documentation to be perfectly
consistent in the amount of usefulness throughout and would complain if
some parts are better than average.

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

Sorry, I don't buy this.  Prohibiting improvement everywhere so that
people might not get the idea that it it possible is not useful.

In particular not with open source where there are nonprogrammers that
can be led to contribute manual pieces and similar when it strikes them
that the quality could be improved.

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

Yes, one would have options for half a dozen improvements in the .itely
files.  That's not a disadvantage.

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

I don't see that.  This will take the time people choose to invest.  It
is not like anything gets worse if people don't care.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum