X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fdevel%2Flsr-work.itexi;fp=Documentation%2Fdevel%2Flsr-work.itexi;h=0000000000000000000000000000000000000000;hb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;hp=b3d49963440ce6b312376f31c78c2204d7cc0429;hpb=a8c9e8a7ca320ab0df5fd32e717fd62cd7635ce6;p=lilypond.git diff --git a/Documentation/devel/lsr-work.itexi b/Documentation/devel/lsr-work.itexi deleted file mode 100644 index b3d4996344..0000000000 --- a/Documentation/devel/lsr-work.itexi +++ /dev/null @@ -1,260 +0,0 @@ -@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