Re: Importing, updating, translating and building Lilypond snippets

[John Mandereau]

Hi,
Il giorno mar, 26/06/2012 alle 13.39 +0100, Phil Holmes ha scritto:
> 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.

Thanks for having summed up, here's a patch; I hope it works (I tested
it with 'make', running makelsr with unpacked LSR tarball, then 'make
doc', and could read translated texidocs in translations of Notation,
but with a shaky "make -j" I'm not 100 % sure) and takes into account
the discussions:

http://codereview.appspot.com/6352053

Cheers,
John