Importing, updating, translating and building Lilypond snippets

[Phil Holmes]

Here's my summary of what I think needs to happen with the proposed 
management of the snippets:

A tarball of snippets can be downloaded from 
http://lsr.dsi.unimi.it/download/.  The tarball required is the one tagged 
as "docs": lsr-snippets-docs-yyyy-mm-dd.tar.gz.  This is unarchived and the 
contents simply copied somewhere convenient.  A script is run 
(makesnippets.py?) which iterates over all the directories in the extracted 
tarball and all the files in each directory.  It adds a line:

lsrtags = dir-1, dir-2

to each snippet, where dir-n is the directory name in which the snippet is 
found in the tarball.  Note that each snippet can be in multiple 
directories, and each directory name is a "tag" for the snippet.  The lsrtag 
line should come immediately after the "\header {" line in the snippet.  The 
snippet should be written to $LILYPOND_GIT/Documentation/snippets.

Note: there is a subdirectory of Documentation/snippets - 
Documentation/snippets/new.  This is updated versions of existing snippets 
or new snippets which will run on the current development build of lilypond, 
but will not run on the build being used by the snippet repository.

The script also runs convert-ly to update the snippets to the latest 
version.

It must be possible to check that the snippets extracted from the tarball do 
not contain new snippets which contain dangerous commands - for example 
#'(system "rm -rf /").  It would be possible to use git/gitk to check for 
changes, but it may be preferable to have a script similar to the one used 
in makelsr.py to run lilypond in safe mode to assist identifying snippets 
containing system commands. 
http://lilypond.org/doc/v2.15/Documentation/contributor/lsr-to-git covers 
some aspects of how this works in the current system at the bottom of the 
page.

Note that makelsr.py already does much of the processing required above - 
all that is needed is to remove some functionality.

The build process is then used to update, add translations and put the 
resulting snippets into $(top-build-dir)/Documentation/snippets/out.  I 
suggest that the make command should be 'make snippets' and that this is 
also run as part of the normal make.  It doesn't seem to make sense to me 
for it to run as part of make doc as well, since make is a required 
pre-cursor of make doc.

Make snippets will (run a script that will) iterate the snippets in 
$LILYPOND_GIT/Documentation/snippets and search 
$LILYPOND_GIT/Documentation/language/texidocs for a corresponding file - 
i.e. my-useful-snippet.ly would require a translation in 
my-useful-snippet.texidoc.  Where a translation is found, it is added to the 
.ly file under the lsrtag line, within the \header {} section.  If there is 
a snippet of the same name in snippets/new, this is used in preference to 
the snippet from the tarball.

The snippet with translations is then written to 
$(top-build-dir)/Documentation/snippets/out.  That's all that's required of 
make snippets.

The make and make doc functionality will need to be changed to pick up the 
snippets from to $(top-build-dir)/Documentation/snippets/out rather than 
$LILYPOND_GIT/Documentation/snippets as is currently used.

If make and make doc run successfully, the LSR meister should push 
Documentation/snippets to git.


--
Phil Holmes