@c -*- coding: us-ascii; mode: texinfo; -*-
@node LSR work
@chapter LSR work

@menu
* Introduction to LSR::
* Adding and editing snippets::
* Approving snippets::
* LSR to Git::
* Fixing snippets in LilyPond sources::
@end menu


@node Introduction to LSR
@section Introduction to LSR

The
@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.


@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.
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.

Please make sure that the lilypond code follows the guidelines in
@ref{LilyPond formatting}.


@node Approving snippets
@section Approving snippets

The main task of LSR editors is approving snippets.  To find a list of
unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
select @qq{No} from the dropdown menu to the right of the word
@qq{Approved} at the bottom of the interface, then click
@qq{Enable filter}.

Check each snippet:

@enumerate

@item
Does the snippet make sense and does what the author claims that
it does?  If you think the snippet is particularly helpful, add
the @qq{docs} tag and at least one other tag.

@item
If the snippet is tagged with @qq{docs}, check to see if it
matches our guidelines for @ref{LilyPond formatting}.

@item
If the snippet uses scheme, check that everything looks good and
there are no security risks.

@warning{Somebody could sneak a @code{#'(system "rm -rf /")}
command into our source tree if you do not do this!  Take this
step @strong{VERY SERIOUSLY}.}

@end enumerate


@node LSR to Git
@section LSR to Git

@enumerate

@item
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
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 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
step @strong{VERY SERIOUSLY}.}

@item
Do a git add / commit / push.

@end enumerate


@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