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

[Graham Percival]

On Mon, 28 Apr 2008 09:33:24 +0200
David Kastrup <address@hidden> wrote:

> Graham Percival <address@hidden> 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