@section Introduction to LSR
The
-@uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
+@uref{http://lsr.di.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
When you create (or find!) a nice snippet, if it is supported by
the LilyPond version running on the LSR, please add it to the LSR.
-Go to @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
+Go to @uref{http://lsr.di.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.
scripts/auxiliar/makelsr.py
@end example
-@noindent
-@command{makelsr} also copies translated texidoc fields and snippet titles into
-snippets in @file{Documentation/snippets}. Note: this, in turn, could
-make the translated texidoc fields to appear as out of sync when you
-run @code{make check-translation}, if the originals changed from the
-last translation update, even if the translations are also updated;
-see @ref{Documentation translation maintenance} for details about
-updating the docs; in particular, see @ref{Updating translation
-committishes} to learn how to mark these translated fields as fully
-updated.
-
Be sure that @command{make doc} runs successfully before submitting a
patch, to prevent breaking compilation.
@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
+unapproved snippets, log into @uref{http://lsr.di.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}.
@enumerate
@item
-Make sure that @command{convert-ly} script and the
-@command{lilypond} binary are a
-bleeding edge version -- the latest release or even better, a fresh
-snapshot from Git master.
+Make sure that @command{convert-ly} script and the @command{lilypond}
+binary are a bleeding edge version -- the latest release or even
+better, a fresh snapshot from Git master, with the environment
+variable @code{LILYPOND_BUILD_DIR} correctly set up, see
+@ref{Environment variables}.
@item
Start by creating a list of updated snippets from your local
@end example
Commit the changes and make a patch. Check the patch has nothing
-other than minor changes - in particular changes to the commitish
-for translations. If all is good and you're confident in what
+other than minor changes. If all is good and you're confident in what
you've done, this can be pushed directly to staging.
@item
-Next, download the updated snippets and run makelsr against them.
-From the top source directory, run:
+Next, download the updated snippets and run @command{makelsr.py}
+against them. From the top source directory, run:
@smallexample
-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}
+wget http://lsr.di.unimi.it/download/lsr-snippets-docs-`date +%F`.tar.gz
+tar -xzf lsr-snippets-docs-`date +%F`.tar.gz
+make -C $LILYPOND_BUILD_DIR
+scripts/auxiliar/makelsr.py lsr-snippets-docs-`date +%F`
@end smallexample
@noindent
-where @var{YYYY-MM-DD} is the current date, e.g. 2011-12-25.
+where @command{date +%F} gives the current date in format
+@var{YYYY-MM-DD} (the snippets archive is usually generated around
+03:50 CET, you may want to use @command{date -d yesterday +%F}
+instead, depending on your time zone and the time you run this
+commands sequence). @command{make} is included in this sequence so
+that @command{makelsr} can run @command{lilypond} and
+@command{convert-ly} versions that match current source tree; you can
+select different binaries if desired or needed, to see options for
+this do
+
+@smallexample
+scripts/auxiliar/makelsr.py --help
+@end smallexample
@item
Follow the instructions printed on the console to manually check for
carefully to see if files have been added. If so, add them with
@code{git add}.
-As the console says, makelsr creates a list of possibly unsafe
-files in @file{lsr-unsafe.txt} by running @code{lilypond} against each
-snippet using the @code{-dsafe} switch. This list can be quite
-long. However, by using the command @code{xargs git diff HEAD < lsr-unsafe.txt}
-git will take that list and check whether any of the snippets are
-different from the snippet already in master. If any is different
-it must be checked manually VERY CAREFULLY.
+As the console says, @command{makelsr} creates a list of possibly
+unsafe files in @file{lsr-unsafe.txt} by running @code{lilypond}
+against each snippet using the @code{-dsafe} switch. This list can be
+quite long. However, by using the command @code{xargs git diff HEAD <
+lsr-unsafe.txt} git will take that list and check whether any of the
+snippets are different from the snippet already in master. If any is
+different it must be checked manually VERY CAREFULLY.
@warning{Somebody could sneak a @code{#'(system "rm -rf /")}
command into our source tree if you do not do this! Take this
advised to run a review on Rietveld.
@item
-If a Review is not needed, commit the changes and push to staging.
+If a Review is not needed, commit the changes and push to
+@code{staging}.
@end enumerate
documentation build successfully.
@item
-Determine where it comes from by looking at its first line, e.g. run
+Determine where it comes from by looking at its first two lines,
+e.g. run
@example
-head -1 Documentation/snippets/@var{foo}.ly
+head -2 Documentation/snippets/@var{foo}.ly
@end example
@item
@file{Documentation/snippets/new}, then run @command{makelsr.py}.
@item
-@strong{If the snippet comes from}
-@file{Documentation/snippets/new}, apply the same fix in
-@file{Documentation/snippets/new/@var{foo}.ly} that you did in
-@file{Documentation/snippets/@var{foo}.ly}. If the build failure
-was caused by a translation string, you may have to fix
-@file{input/texidocs/@var{foo}.texidoc} instead.
+@strong{If the snippet comes from} @file{Documentation/snippets/new},
+apply the fix in @file{Documentation/snippets/new/@var{foo}.ly}, then
+run @command{makelsr.py} without argument from top of the source tree:
+
+@example
+scripts/auxiliar/makelsr.py
+@end example
+
+Then, inspect @file{Documentation/snippets/@var{foo}.ly} to check that
+the fix has been well propagated.
+
+If the build failure was caused by a translation string, you may have
+to fix some @file{Documentation/@var{lang}/texidocs/@var{foo}.texidoc}
+instead; in case the build failure comes only from translation
+strings, it is not needed to run @command{makelsr.py}.
@item
When you've done, commit your changes to Git and ensure they're
@item
Download the latest snippet tarball from
-@uref{http://lsr.dsi.unimi.it/download/} and extract it.
+@uref{http://lsr.di.unimi.it/download/} and extract it.
The relevant files can be found in the @file{all} subdirectory.
Make sure your shell is using an English language version, for
example @code{LANG=en_US}, then run @command{convert-ly} on all
projects / lilypond.git / blobdiff