1 @c -*- coding: us-ascii; mode: texinfo; -*-
6 * Introduction to LSR::
7 * Adding and editing snippets::
10 * Fixing snippets in LilyPond sources::
11 * Updating LSR to a new version::
15 @node Introduction to LSR
16 @section Introduction to LSR
19 @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
20 is a collection of lilypond examples. A subset of these examples
21 are automatically imported into the documentation, making it easy
22 for users to contribute to the docs without learning Git and
26 @node Adding and editing snippets
27 @section Adding and editing snippets
29 @subheading General guidelines
31 When you create (or find!) a nice snippet, if it supported by LilyPond
32 version running on LSR, please add it to LSR. Go to
33 @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
34 already, create an account. Follow the instructions on the website.
35 These instructions also explain how to modify existing snippets.
37 If you think the snippet is particularly informative and you think it
38 should be included in the documentation, tag it with @qq{docs} and one
39 or more other categories, or ask somebody who has editing permissions to
40 do it on the development list.
42 Please make sure that the lilypond code follows the guidelines in
43 @ref{LilyPond formatting}.
45 If a new snippet created for documentation purposes compiles with
46 LilyPond version currently on LSR, it should be added to LSR, and a
47 reference to the snippet should be added to the documentation.
49 If the new snippet uses new features that are not available in the
50 current LSR version, the snippet should be added to @file{input/new} and
51 a reference should be added to the manual.
53 Snippets created or updated in @file{input/new} should be copied to
54 @file{input/lsr} by invoking at top of the source tree
57 scripts/auxiliar/makelsr.py
60 Be sure that @command{make doc} runs successfully before submitting a
61 patch, to prevent breaking compilation.
63 @subheading Formatting snippets in @file{input/new}
65 When adding a file to this directory, please start the file with
70 lsrtags = "rhythms,expressive-marks" % use existing LSR tags other than
71 % 'docs'; see makelsr.py for the list of tags used to sort snippets.
72 texidoc = "This code demonstrates ..." % this will be formated by Texinfo
73 doctitle = "Snippet title" % please put this at the end so that
74 the '% begin verbatim' mark is added correctly by makelsr.py.
78 and name the file @file{snippet-title.ly}.
81 @node Approving snippets
82 @section Approving snippets
84 The main task of LSR editors is approving snippets. To find a list of
85 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
86 select @qq{No} from the dropdown menu to the right of the word
87 @qq{Approved} at the bottom of the interface, then click
95 Does the snippet make sense and does what the author claims that
96 it does? If you think the snippet is particularly helpful, add
97 the @qq{docs} tag and at least one other tag.
100 If the snippet is tagged with @qq{docs}, check to see if it
101 matches our guidelines for @ref{LilyPond formatting}.
104 If the snippet uses scheme, check that everything looks good and
105 there are no security risks.
107 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
108 command into our source tree if you do not do this! Take this
109 step @strong{VERY SERIOUSLY}.}
120 Make sure that @command{convert-ly} and @command{lilypond} commands in
121 current PATH are in a bleeding edge version -- latest release from
122 master branch, or even better a fresh snapshot from Git master branch.
125 From the top source directory, run:
128 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
129 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
130 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
134 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
137 Follow the instructions printed on the console to manually check for
140 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
141 command into our source tree if you do not do this! Take this
142 step @strong{VERY SERIOUSLY}.}
145 Do a git add / commit / push.
149 Note that whenever there is one snippet from @file{input/new} and the
150 other from LSR with the same file name, the one from @file{input/new}
151 will be copied by @command{makelsr.py}.
154 @node Fixing snippets in LilyPond sources
155 @section Fixing snippets in LilyPond sources
157 In case some snippet from @file{input/lsr} cause the documentation
158 compilation to fail, the following steps should be followed to fix it
164 Look up the snippet filename @file{@var{foo}.ly} in the error output
165 or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
166 documentation build succesfully.
169 Determine where it comes from by looking at its first line, e.g. run
172 head -1 input/lsr/@var{foo}.ly
176 @strong{In case the snippet comes from LSR}, apply the fix to the
177 snippet in LSR and send a notification email to a LSR editor with CC
178 to the development list -- see @ref{Adding and editing snippets}. The
179 failure may sometimes not be caused by the snippet in LSR but by the
180 syntax conversion made by @command{convert-ly}; in this case, try to
181 fix @command{convert-ly} or report the problem on the development
182 list, then run @command{makelsr.py} again, see @ref{LSR to Git}. In
183 some cases, when some features has been introduced or vastly changed
184 so it requires (or takes significant advantage of) important changes
185 in the snippet, it is simpler and recommended to write a new version
186 of the snippet in @file{input/new}, then run @command{makelsr.py}.
189 @strong{In case the snippet comes from} @file{input/new}, apply in
190 @file{input/new/@var{foo}.ly} the same fix you did in
191 @file{input/lsr/@var{foo}.ly}. In case the build failure was caused
192 by a translation string, you may have to fix
193 @file{input/texidocs/@var{foo}.texidoc} instead.
196 In any case, commit all changes to Git.
202 @node Updating LSR to a new version
203 @section Updating LSR to a new version
205 To update LSR, perform the following steps:
210 Download the latest snippet tarball, extract it, and run
211 @code{convert-ly} on all files using the command-line option
212 @code{--to=VERSION} to ensure snippets are updated to the
213 correct stable version.
216 Copy relevant snippets (i.e., snippets whose version is equal to or
217 less than the new version of LilyPond) from @file{input/new/} into
220 You must not rename any files during this, or the next, stage.
223 Verify that all files compile with the new version of LilyPond,
224 ideally without any warnings or errors. To ease the process,
225 you may use the shell script that appears after this list.
227 Due to the workload involved, we @emph{do not} require that you
228 verify that all snippets produce the expected output. If you
229 happen to notice any such snippets and can fix them, great; but as
230 long as all snippets compile, don't delay this step due to some
231 weird output. If a snippet is broken, the hordes of willing
232 web-2.0 volunteers will fix it. It's not our problem.
235 Create a tarball and send it back to Sebastiano.
238 When LSR has been updated, download another snippet tarball,
239 verify that the relevant snippets from @file{input/new/} were
240 included, then delete those snippets from @file{input/new/}.
245 Here is a shell script to run all @code{.ly} files in a directory
246 and redirect terminal output to text files, which are then
247 searched for the word "failed" to see which snippets do not compile.
254 STEM=$(basename "$LILYFILE" .ly)
255 echo "running $LILYFILE..."
256 lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt