@chapter LSR work
@menu
-* Introduction to LSR::
-* Adding snippets::
-* Approving snippets::
-* LSR to git::
+* Introduction to LSR::
+* Adding and editing snippets::
+* Approving snippets::
+* LSR to Git::
+* Fixing snippets in LilyPond sources::
@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 snippets
-@section Adding snippets
+@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
-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.
+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, 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 web} 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
-@node LSR to git
-@section LSR to git
-
-FIXME: Neil, please check that this is up-to-date.
+@node LSR to Git
+@section LSR to Git
@enumerate
@item
-Download the latest tarball from
-@uref{http://lsr.dsi.unimi.it/download/}. You want a file called
-@file{lsr-snippets-docs-DATE.tar.gz}.
+Make sure that @command{convert-ly} and @command{lilypond} commands in
+current PATH are in a bleeding edge version -- latest release from
+master branch, or even better a fresh snapshot from Git master branch.
@item
From the top source directory, run:
@example
-scripts/auxiliar/makelsr.py
+wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
+tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
+scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
@end example
+@noindent
+where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
+
@item
-Follow the instructions on the console to manually check for
-unsafe files.
+Follow the instructions printed on the console to manually check for
+unsafe files.
@warning{Somebody could sneak a @code{#'(system "rm -rf /")}
command into our source tree if you do not do this! Take this
@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 case some snippet from @file{input/lsr} cause the documentation
+compilation to fail, the following steps should be followed to fix it
+reliably.
+
+@enumerate
+
+@item
+Look up the snippet filename @file{@var{foo}.ly} in the error output
+or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
+documentation build succesfully.
+
+@item
+Determine where it comes from by looking at its first line, e.g. run
+
+@example
+head -1 input/lsr/@var{foo}.ly
+@end example
+
+@item
+@strong{In case the snippet comes from LSR}, apply the fix to the
+snippet in LSR and send a notification email to a LSR editor with CC
+to the development list -- see @ref{Adding and editing snippets}. The
+failure may sometimes not be caused by the snippet in LSR but by the
+syntax conversion made by @command{convert-ly}; in this case, try to
+fix @command{convert-ly} or report the problem on the development
+list, then run @command{makelsr.py} again, see @ref{LSR to Git}. In
+some cases, when some features has been introduced or vastly changed
+so it requires (or takes significant advantage of) important changes
+in the snippet, it is simpler and recommended to write a new version
+of the snippet in @file{input/new}, then run @command{makelsr.py}.
+
+@item
+@strong{In case the snippet comes from} @file{input/new}, apply in
+@file{input/new/@var{foo}.ly} the same fix you did in
+@file{input/lsr/@var{foo}.ly}. In case the build failure was caused
+by a translation string, you may have to fix
+@file{input/texidocs/@var{foo}.texidoc} instead.
+
+@item
+In any case, commit all changes to Git.
+
+@end enumerate