Policy decision needed about Documentation/snippets/new

[John Mandereau]

Hi,

I'm trying to make match instructions in the CG to what makelsr script
does, in order to avoid future mess with Documentation/snippets/new, and
I see two good alternatives.  Please give your motivated opinion, as I'm
not sure which one I prefer.

Note that in the case you change a single or a couple of snippets in
Documentation/snippets/new and don't want to update everything by
downloading and unpacking a tarball from LSR website, there are
currently contradictory instructions:
* one page tells to run makelsr.py
http://lilypond.org/doc/v2.15/Documentation/contributor/adding-and-editing-snippets
* the other one tells to manually edit the snippet in both
Documentation/snippets/new and Documentations/snippets
http://lilypond.org/doc/v2.15/Documentation/contributor/fixing-snippets-in-lilypond-sources

So here are the alternatives.

1) Current behaviour (broken and not well documented, but can be easily
fixed)

.ly files in Documentation/snippets/new are not used directly by
documentation build, they are run through makelsr.py, which adds a "Do
not edit" comment and convert-ly the file into Documentation/snippets.
Any fix or change to Documentation/snippets/new that isn't concerned
with syntax changes could be done by making the change simultaneously in
Documentation/snippets and Documentation/snippets/new, but we wouldn't
document it and require instead to run makelsr.py without arguments
after a fresh "make" (without "make doc") and with LILYPOND_BUILD_DIR
set correctly.

The advantage of this alternative is that the only changes to be made
are a few lines in makelsr.py and the CG.  Its disadvantage is that
developers may edit just Documentation/snippets/new, thus leaving
changes untested for a few days or weeks; for example, IIUC
4ab6e4df934e57c51dbbdbf2c209273c6cb5b888 (May 9 2012) 
was not used in doc build until 9fe18536fe333c167fe1bd87f76a30b20f603dd0
(June 19 2012), and missed release 2.15.39. There are other older
examples of this.

2) Other behaviour

In doc build, makesnippets runs in both Documentation/snippets and
Documentation/snippets/out, and lilypond-book looks for .ly files in
Documentation/snippets/new/out before Documentation/snippets/out.
Snippets in Documentation/snippets/new should no longer be
copied/handled by makelsr.py to Documentation/snippets.

In case of addition of new files or file renames in
Documentation/snippets/new, makelsr.py should still be run to update the
snippet lists.

The advantage of this scheme is that there is no longer a dumping ground
of files that aren't used directly in doc build.  The disadvantage of
this is that we must pay greater attention to lilypond-book include path
order, so that Documentation/snippets/new is examined before
Documentation/snippets.

Cheers,
John