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

[Graham Percival]

On Mon, 28 Apr 2008 08:50:32 +0200
David Kastrup <address@hidden> wrote:

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

From
http://lists.gnu.org/archive/html/lilypond-devel/2008-04/msg00222.html

> That makes the situation decidedly _worse_ since it encourages
> referring to the pitches section for looking for an example for a
> particular pitch construct without making the documentation author
> double-check that this construct is actually present somewhere among
> the examples.

Using @lilypondfile forces the doc-writer to make sure the snippet is
actually there.

> If somebody decides to untag some snippet as being too contrived, the
> documentation compiler won't complain when this snippet is the one
> intended to explain a particular construct.

Using @lilypondfile forces the documentation compiler to complain if an
important snippet is removed.

> Having to specify a particular snippet makes sure that this snippet
> (and thus the construct) indeed appears in the docs, and that its
> absence will be noticed when compiling the documentation.

And this is done if you use @lilypondfile, but is *not* done if you use
@lsr.


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

Given that I've spent about 20 hours teaching new people how to
contribute to our docs, this argument falls down.  Maybe git, texinfo,
diff, and patch are second-nature to you, but most non-programmers are
completely lost when it comes to such tools.  Some musicians can learn
such tools in an hour or so, but most require hours.

Contributing documentation to lilypond is not a trivial task which a
random user can do whenever it strikes his fancy.  If there's somebody
willing to take care of the technical details -- ie somebody who's
already spent the 5 hours to learn the tools involved -- then small
changes can be made in a few minutes if the random user sends a
detailed email.

The whole idea of LSR is that it allows non-programmers -- and even
non-technical people -- to contribute to the docs *without* touching
the .itely files.  All they need is a web browser; no knowledge of text
editors, git source repositories, installing texinfo, compiling
lilypond, or diff  is required.


This discussion is over.  In four months when I'm gone, if lilypond has
tons of people wanting to work on the docs and the devel team can't
find enough work for them, then by all means start adding such
references.  But I really doubt that we'll ever have so much help that
the tradeoff is worth it.

I apologize for using your name in my previous email.

- Graham