On Mon, 28 Apr 2008 08:50:32 +0200 David Kastrup <[EMAIL PROTECTED]> 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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
