+++ /dev/null
-@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::
-* Updating LSR to a new version::
-@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
-
-@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, 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
-
-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
-
-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
-
-
-
-@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