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 _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
