On Mon, 28 Apr 2008 09:33:24 +0200 David Kastrup <[EMAIL PROTECTED]> wrote:
> Graham Percival <[EMAIL PROTECTED]> writes: > > > Using @lilypondfile forces the doc-writer to make sure the snippet > > is actually there. > > You mean the documentation compiler does not complain about undefined > references? Why wouldn't it? It complains about undefined references *in the same file*. The snippets are in a separate "manual" than the user manual. We have a total of 6 manuals. > > 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. > > Uh, we are talking about the kind of musicians that write their music > using lilypond, aren't we? And ever since we started having GUB on windows, the standard has been dropping. (just kidding, Trevor and Valentin. You guys are great! :) All kidding aside, approximately 20% of documentation helpers know how to use patch. When I began GDP, I deliberately did *not* require helpers to submit patches or use the source tree. Instead, I keep a directory of doc source files, which they download and send back (edited) to me in their entirity. More work for me... but if I didn't do it, we'd lose 80% of our doc improvements. Including our main doc writer, Trevor Daniels. (he's using git now, but I suspect that if I'd asked him to use git from the beginning, he wouldn't have gotten involved... especially since I think he had to get the wingit devel team to modify wingit to allow him to connect to our git repo) > > 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. > > That's dandy. But it is nonsensical to portrait as a non-choice what > is, after all, a tradeoff. And I don't even see where the advantage > lies in prohibiting a particular improvement everywhere for the > purported sake of consistency. I'm sorry if I ever portrayed it as a non-choice. It's totally a trade-off. When/if I wrote "it's obviously a silly idea" (or however I portrayed it as a non-choice), I was thinking of our progress. 8 months into the 12-month GDP, we've finished two sections of the NR. 2/16 of the NR 1+2 sections. - Graham _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
