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