1 @c -*- coding: utf-8; mode: texinfo; -*-
6 * Introduction to LSR::
7 * Adding and editing snippets::
10 * Fixing snippets in LilyPond sources::
11 * Renaming a snippet::
12 * Updating LSR to a new version::
16 @node Introduction to LSR
17 @section Introduction to LSR
20 @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
21 is a collection of lilypond examples. A subset of these examples
22 are automatically imported into the documentation, making it easy
23 for users to contribute to the docs without learning Git and
27 @node Adding and editing snippets
28 @section Adding and editing snippets
30 @subheading General guidelines
32 When you create (or find!) a nice snippet, if it supported by LilyPond
33 version running on LSR, please add it to LSR. Go to
34 @uref{http://lsr.dsi.unimi.it/, LSR} and log in -- if you haven't
35 already, create an account. Follow the instructions on the website.
36 These instructions also explain how to modify existing snippets.
38 If you think the snippet is particularly informative and you think it
39 should be included in the documentation, tag it with @qq{docs} and one
40 or more other categories, or ask somebody who has editing permissions to
41 do it on the development list.
43 Please make sure that the lilypond code follows the guidelines in
44 @ref{LilyPond formatting}.
46 If a new snippet created for documentation purposes compiles with
47 LilyPond version currently on LSR, it should be added to LSR, and a
48 reference to the snippet should be added to the documentation.
50 If the new snippet uses new features that are not available in the
51 current LSR version, the snippet should be added to
52 @file{Documentation/snippets/new} and a reference should be added to the
55 Snippets created or updated in @file{Documentation/snippets/new} should
56 be copied to @file{Documentation/snippets} by invoking at top of the
60 scripts/auxiliar/makelsr.py
64 This also copies translated texidoc fields and snippet titles into
65 snippets in @file{Documentation/snippets}. Note: this, in turn, could
66 make the translated texidoc fields to appear as out of sync when you
67 run @code{make check-translation}, if the originals changed from the
68 last translation update, even if the translations are also updated;
69 see @ref{Documentation translation maintenance} for details about
70 updating the docs; in particular, see @ref{Updating translation
71 committishes} to learn how to mark these translated fields as fully
74 Be sure that @command{make doc} runs successfully before submitting a
75 patch, to prevent breaking compilation.
77 @subheading Formatting snippets in @file{Documentation/snippets/new}
79 When adding a file to this directory, please start the file with
84 % Use existing LSR tags other than 'docs'; see makelsr.py for
85 % the list of tags used to sort snippets. E.g.:
86 lsrtags = "rhythms,expressive-marks"
87 % This texidoc string will be formatted by Texinfo
89 This code demonstrates ...
91 % Please put doctitle last so that the '% begin verbatim'
92 % mark will be added correctly by makelsr.py.
93 doctitle = "Snippet title"
98 and name the file @file{snippet-title.ly}.
101 @node Approving snippets
102 @section Approving snippets
104 The main task of LSR editors is approving snippets. To find a list of
105 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
106 select @qq{No} from the dropdown menu to the right of the word
107 @qq{Approved} at the bottom of the interface, then click
115 Does the snippet make sense and does what the author claims that
116 it does? If you think the snippet is particularly helpful, add
117 the @qq{docs} tag and at least one other tag.
120 If the snippet is tagged with @qq{docs}, check to see if it
121 matches our guidelines for @ref{LilyPond formatting}.
123 Also, snippets tagged with @qq{docs} should not be explaining
124 (replicating) existing material in the docs. They should not
125 refer to the docs; the docs should refer to them.
128 If the snippet uses scheme, check that everything looks good and
129 there are no security risks.
131 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
132 command into our source tree if you do not do this! Take this
133 step @strong{VERY SERIOUSLY}.}
144 Make sure that @command{convert-ly} and @command{lilypond} are a
145 bleeding edge version -- the latest release or even better a fresh
146 snapshot from Git master.
149 Start by creating a list of updated snippets from your local
150 repository. From the top source directory, run:
153 scripts/auxiliar/makelsr.py
156 Commit the changes and make a patch. Check the patch has nothing
157 other than minor changes - in particular changes to the commitish
158 for translations. If all is good and you're confident in what
159 you've done, this can be pushed directly to staging.
162 Next, download the updated snippets and run makelsr against them.
163 From the top source directory, run:
166 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
167 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
168 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
172 where @var{YYYY-MM-DD} is the current date, e.g. 2011-12-25.
175 Follow the instructions printed on the console to manually check for
176 unsafe files. These are:
179 Unsafe files printed in lsr-unsafe.txt: CHECK MANUALLY!
180 git add Documentation/snippets/*.ly
181 xargs git diff HEAD < lsr-unsafe.txt
184 First, it's important to check for any added files and add them to
185 the files git is tracking. Run @code{git status} and look
186 carefully to see if files have been added. If so, add them with
189 As the console says, makelsr creates a list of possibly unsafe
190 files in @file{lsr-unsafe.txt} by running @code{lilypond} against each
191 snippet using the @code{-dsafe} switch. This list can be quite
192 long. However, by using the command @code{xargs git diff HEAD < lsr-unsafe.txt}
193 git will take that list and check whether any of the snippets are
194 different from the snippet already in master. If any is different
195 it must be checked manually VERY CAREFULLY.
197 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
198 command into our source tree if you do not do this! Take this
199 step @strong{VERY SERIOUSLY}.}
201 If there is any doubt about any of the files, you are strongly
202 advised to run a review on Rietveld.
205 If a Review is not needed, commit the changes and push to staging.
209 Note that whenever there is one snippet from
210 @file{Documentation/snippets/new} and the other from LSR with the same
211 file name, the one from @file{Documentation/snippets/new} will be copied
212 by @command{makelsr.py}.
215 @node Fixing snippets in LilyPond sources
216 @section Fixing snippets in LilyPond sources
218 In case some snippet from @file{Documentation/snippets} causes the
219 documentation compilation to fail, the following steps should be
220 followed to fix it reliably.
225 Look up the snippet filename @file{@var{foo}.ly} in the error output
226 or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the
227 documentation build successfully.
230 Determine where it comes from by looking at its first line, e.g. run
233 head -1 Documentation/snippets/@var{foo}.ly
237 @strong{In case the snippet comes from LSR}, apply the fix to the
238 snippet in LSR and send a notification email to a LSR editor with CC to
239 the development list -- see @ref{Adding and editing snippets}. The
240 failure may sometimes not be caused by the snippet in LSR but by the
241 syntax conversion made by @command{convert-ly}; in this case, try to fix
242 @command{convert-ly} or report the problem on the development list, then
243 run @command{makelsr.py} again, see @ref{LSR to Git}. In some cases,
244 when some features has been introduced or vastly changed so it requires
245 (or takes significant advantage of) important changes in the snippet, it
246 is simpler and recommended to write a new version of the snippet in
247 @file{Documentation/snippets/new}, then run @command{makelsr.py}.
250 @strong{In case the snippet comes from}
251 @file{Documentation/snippets/new}, apply in
252 @file{Documentation/snippets/new/@var{foo}.ly} the same fix you did in
253 @file{Documentation/snippets/@var{foo}.ly}. In case the build failure
254 was caused by a translation string, you may have to fix
255 @file{input/texidocs/@var{foo}.texidoc} instead.
258 In any case, commit all changes to Git.
263 @node Renaming a snippet
264 @section Renaming a snippet
266 Due to the potential duality of snippets (i.e. they may exist both
267 in the LSR database, and in @code{Documentation/snippets/new/}),
268 this process is a bit more involved than we might like.
272 Send an email LSR editor, requesting the renaming.
275 The LSR editor does the renaming (or debates the topic with you),
276 then warns the LSR-to-git person (wanted: better title) about the
280 LSR-to-git person does his normal job, but then also renames any
281 copies of the snippets in @code{Documentation/snippets/new/}, and
282 any instances of the snippet name in the documentation.
284 @code{git grep} is highly recommended for this task.
289 @node Updating LSR to a new version
290 @section Updating LSR to a new version
292 To update LSR, perform the following steps:
297 Download the latest snippet tarball, extract it, and run
298 @code{convert-ly} on all files using the command-line option
299 @option{--to=@var{version}} to ensure snippets are updated to the
300 correct stable version.
302 Make sure you use @code{convert-ly} from the latest available release to gain
303 all advantages from the latest converting-rules-updates.
313 intended LSR-update to 2.14.2
316 latest release 2.15.30
320 Use @code{convert-ly} from 2.15.30 and the following terminal
321 command for all files:
324 convert-ly -e -t2.14.2 *.ly
328 Copy relevant snippets (i.e., snippets whose version is equal to or less
329 than the new version of LilyPond) from
330 @file{Documentation/snippets/new/} into the tarball.
332 You must not rename any files during this, or the next, stage.
335 Verify that all files compile with the new version of LilyPond,
336 ideally without any warnings or errors. To ease the process,
337 you may use the shell script that appears after this list.
339 Due to the workload involved, we @emph{do not} require that you
340 verify that all snippets produce the expected output. If you
341 happen to notice any such snippets and can fix them, great; but as
342 long as all snippets compile, don't delay this step due to some
343 weird output. If a snippet is broken, the hordes of willing
344 web-2.0 volunteers will fix it. It's not our problem.
347 Create a tarball and send it back to Sebastiano.
350 When LSR has been updated, download another snippet tarball, verify that
351 the relevant snippets from @file{Documentation/snippets/new/} were
352 included, then delete those snippets from
353 @file{Documentation/snippets/new/}.
358 Here is a shell script to run all @file{.ly} files in a directory
359 and redirect terminal output to text files, which are then
360 searched for the word "failed" to see which snippets do not compile.
367 STEM=$(basename "$LILYFILE" .ly)
368 echo "running $LILYFILE..."
369 lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt