* Approving snippets::
* LSR to Git::
* Fixing snippets in LilyPond sources::
+* Updating LSR to a new version::
@end menu
@uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
is a collection of lilypond examples. A subset of these examples
are automatically imported into the documentation, making it easy
-for users to contribute to the docs without learning git and
-texinfo.
+for users to contribute to the docs without learning Git and
+Texinfo.
@node Adding and editing snippets
@section Adding and editing snippets
-When you create (or find!) a nice snippet, please add it to LSR. Go
-to @uref{http://lsr.dsi.unimi.it/, LSR} and log in (if you haven't
-already, create an account). Follow the instructions on the website.
+@subheading General guidelines
+
+When you create (or find!) a nice snippet, if it supported by LilyPond
+version running on LSR, please add it to LSR. Go to
+@uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
+already, create an account. Follow the instructions on the website.
These instructions also explain how to modify existing snippets.
-If you think the snippet is particularly informative and you think
-it should be included in the documentation, tag it with @qq{docs}
-and one or more other categories.
+If you think the snippet is particularly informative and you think it
+should be included in the documentation, tag it with @qq{docs} and one
+or more other categories, or ask somebody who has editing permissions to
+do it on the development list.
Please make sure that the lilypond code follows the guidelines in
@ref{LilyPond formatting}.
+If a new snippet created for documentation purposes compiles with
+LilyPond version currently on LSR, it should be added to LSR, and a
+reference to the snippet should be added to the documentation.
+
+If the new snippet uses new features that are not available in the
+current LSR version, the snippet should be added to @file{input/new} and
+a reference should be added to the manual.
+
+Snippets created or updated in @file{input/new} should be copied to
+@file{input/lsr} by invoking at top of the source tree
+
+@example
+scripts/auxiliar/makelsr.py
+@end example
+
+Be sure that @command{make doc} runs successfully before submitting a
+patch, to prevent breaking compilation.
+
+@subheading Formatting snippets in @file{input/new}
+
+When adding a file to this directory, please start the file with
+
+@example
+\version "2.x.y"
+\header @{
+ lsrtags = "rhythms,expressive-marks" % use existing LSR tags other than
+% 'docs'; see makelsr.py for the list of tags used to sort snippets.
+ texidoc = "This code demonstrates ..." % this will be formated by Texinfo
+ doctitle = "Snippet title" % please put this at the end so that
+ the '% begin verbatim' mark is added correctly by makelsr.py.
+@}
+@end example
+
+and name the file @file{snippet-title.ly}.
+
@node Approving snippets
@section Approving snippets
@end enumerate
+Note that whenever there is one snippet from @file{input/new} and the
+other from LSR with the same file name, the one from @file{input/new}
+will be copied by @command{makelsr.py}.
+
@node Fixing snippets in LilyPond sources
@section Fixing snippets in LilyPond sources
In any case, commit all changes to Git.
@end enumerate
+
+
+
+@node Updating LSR to a new version
+@section Updating LSR to a new version
+
+To update LSR, perform the following steps:
+
+@enumerate
+
+@item
+Download the latest snippet tarball, extract it, and run
+@code{convert-ly} on all files using the command-line option
+@code{--to=VERSION} to ensure snippets are updated to the
+correct stable version.
+
+@item
+Copy relevant snippets (i.e., snippets whose version is equal to or
+less than the new version of LilyPond) from @file{input/new/} into
+the tarball.
+
+You must not rename any files during this, or the next, stage.
+
+@item
+Verify that all files compile with the new version of LilyPond,
+ideally without any warnings or errors. To ease the process,
+you may use the shell script that appears after this list.
+
+Due to the workload involved, we @emph{do not} require that you
+verify that all snippets produce the expected output. If you
+happen to notice any such snippets and can fix them, great; but as
+long as all snippets compile, don't delay this step due to some
+weird output. If a snippet is broken, the hordes of willing
+web-2.0 volunteers will fix it. It's not our problem.
+
+@item
+Create a tarball and send it back to Sebastiano.
+
+@item
+When LSR has been updated, download another snippet tarball,
+verify that the relevant snippets from @file{input/new/} were
+included, then delete those snippets from @file{input/new/}.
+
+@end enumerate
+
+
+Here is a shell script to run all @code{.ly} files in a directory
+and redirect terminal output to text files, which are then
+searched for the word "failed" to see which snippets do not compile.
+
+@example
+#!/bin/bash
+
+for LILYFILE in *.ly
+do
+ STEM=$(basename "$LILYFILE" .ly)
+ echo "running $LILYFILE..."
+ lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt
+done
+
+grep failed *.txt
+@end example
projects / lilypond.git / blobdiff