On Wed, Jul 18, 2012 at 03:08:55PM +0200, John Mandereau wrote: > 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
This is the correct option. > 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. Yes, this is the correct option [for now]. > 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. The LSR editor should be running makelsr.py at least once a week. A high-achiever could even work it into the release instructions for added safety, although that of course may require a few rounds before it's completely correct (because I refuse to let the release checklist to get out-of-date with the "reality on the ground" like other parts of the CG). > 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. I thought your big makelsr patch already did this? Anyway, I'm not opposed to it, but I think the first step is to ensure that the CG presents a working set of steps. For that reason, I think we should document the first option, and if/when the build supports this alternate behaviour, change the CG then. - Graham _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
