GDP: LSR and @commonprop

[Graham Percival]

Ok, LSR is now at the stage where we can discuss this.

A brief history:
About two years ago, we had an extensive collection of neat tricks in 
the directory input/test/.  However, only about ten people in the world 
knew of its existence, so it wasn't really used.  This was a shame, 
since there were some very nice tricks in that collection.

I therefore started adding @commonprop sections to the docs.  That was a 
 mistake, because I didn't (and still don't) understand how all these 
tricks worked.  More importantly, when they stopped working, I had 
neither had the time, nor ability, to fix them.

About a year ago, I noticed that we had the LSR (which nobody was 
using), and that this would be a great way to fix my documentation 
mistake.  We could move these snippets into LSR -- that way, they could 
be easily searched, but more importantly, users could add new snippets 
and fix broken ones.  Also this would hopefully shut up all the "we need 
a wiki" people --they could web2.0-themselves to death with LSR.


Now we finally have everything in line to start moving tricks out of the 
manual and into LSR.  This is a good thing, for all the reasons I've 
mentioned.  It's been set up to produce the least possible amount of 
extra work for the devel team -- in fact, since it removes the most 
problematic things from the manual, it should result in much less work 
for the devel team.  You still have the archiving, git interface, and 
all that stuff.  Programmers don't have to add anything to LSR; all they 
need to do is add files to git in the right location.


My initial plan was to leave one or two snippets in each doc section. 
However, that naturally leads to arguments about which snippet should 
stay in the manual -- ie what's the one "really important" snippet for 
each portion of the manual?

My idea now is to avoid all of that discussion by moving *all* of the 
snippets into LSR.  You can see two examples here:

http://kainhofer.com/~lilypond/Documentation/user/lilypond/Accidentals.html#Accidentals
http://kainhofer.com/~lilypond/Documentation/user/lilypond/Key-signature.html#Key-signature

(yes, key signature still has a bunch of FIXMEs in there)


COMPLAINTS:
"we should keep everything in the main docs" -- we just don't have the 
documentation resources to maintain them.  I couldn't do it when I was 
spending 15 hours a week on lilypond, and I won't be doing that again. 
If I suddenly get double the amount of GDP helper time -- and an 
absolute guarantee that they will keep on working on the docs for the 
whole of 2008 -- then we might have the resources for this.

"since the snippet already has texinfo code, why not have them 
automatically inserted directly into the compiled manuals" -- I'd love 
to have this.  That way everybody would be happy.  @commonprop stuff 
would be maintained by the community instead of the doc person, but 
people who want everything inside one pdf would have it there.  This is 
a "MODERATELY IMPORTANT" item on the technical TODO list.  If you're 
interested in doing this yourself, great!  But don't ask me to do it; 
anything that I stick on a todo list is something that I won't do myself.
- and in any case, the first step is to move these snippets out of the 
.itely files and into LSR.


This is the plan, unless anybody comes up with a stunningly good reason 
against it.

Cheers,
- Graham