1 @c -*- coding: utf-8; 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
51 @file{Documentation/@/snippets/@/new} and a reference should be added to the
54 Snippets created or updated in @file{Documentation/@/snippets/@/new} should
55 be copied to @file{Documentation/@/snippets} by invoking at top of the
59 scripts/auxiliar/makelsr.py
63 This also copies translated texidoc fields and snippet titles into
64 snippets in @file{Documentation/@/snippets}. Note: this, in turn, could
65 make the translated texidoc fields to appear as out of sync when you
66 run @code{make check-translation}, if the originals changed from the
67 last translation update, even if the translations are also updated;
68 see @ref{Documentation translation maintenance} for details about
69 updating the docs; in particular, see @ref{Updating translation
70 committishes} to learn how to mark these translated fields as fully
73 Be sure that @command{make doc} runs successfully before submitting a
74 patch, to prevent breaking compilation.
76 @subheading Formatting snippets in @file{Documentation/@/snippets/@/new}
78 When adding a file to this directory, please start the file with
83 lsrtags = "rhythms,expressive-marks" % use existing LSR tags other than
84 % 'docs'; see makelsr.py for the list of tags used to sort snippets.
85 texidoc = "This code demonstrates ..." % this will be formated by Texinfo
86 doctitle = "Snippet title" % please put this at the end so that
87 the '% begin verbatim' mark is added correctly by makelsr.py.
92 and name the file @file{snippet@/-title@/.ly}.
95 @node Approving snippets
96 @section Approving snippets
98 The main task of LSR editors is approving snippets. To find a list of
99 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
100 select @qq{No} from the dropdown menu to the right of the word
101 @qq{Approved} at the bottom of the interface, then click
109 Does the snippet make sense and does what the author claims that
110 it does? If you think the snippet is particularly helpful, add
111 the @qq{docs} tag and at least one other tag.
114 If the snippet is tagged with @qq{docs}, check to see if it
115 matches our guidelines for @ref{LilyPond formatting}.
117 Also, snippets tagged with @qq{docs} should not be explaining
118 (replicating) existing material in the docs. They should not
119 refer to the docs; the docs should refer to them.
122 If the snippet uses scheme, check that everything looks good and
123 there are no security risks.
125 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
126 command into our source tree if you do not do this! Take this
127 step @strong{VERY SERIOUSLY}.}
138 Make sure that @command{convert-ly} and @command{lilypond} commands in
139 current PATH are in a bleeding edge version -- latest release from
140 master branch, or even better a fresh snapshot from Git master branch.
143 From the top source directory, run:
146 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
147 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
148 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
152 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
155 Follow the instructions printed on the console to manually check for
158 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
159 command into our source tree if you do not do this! Take this
160 step @strong{VERY SERIOUSLY}.}
163 Do a git add / commit / push.
167 Note that whenever there is one snippet from
168 @file{Documentation/@/snippets/@/new} and the other from LSR with the same
169 file name, the one from @file{Documentation/@/snippets/@/new} will be copied
170 by @command{makelsr.py}.
173 @node Fixing snippets in LilyPond sources
174 @section Fixing snippets in LilyPond sources
176 In case some snippet from @file{Documentation/@/snippets} causes the
177 documentation compilation to fail, the following steps should be
178 followed to fix it reliably.
183 Look up the snippet filename @file{@var{foo}@/.ly} in the error output
184 or log, then fix the file @file{Documentation/@/snippets/@/@var{foo}@/.ly} to make the
185 documentation build successfully.
188 Determine where it comes from by looking at its first line, e.g. run
191 head -1 Documentation/snippets/@var{foo}.ly
195 @strong{In case the snippet comes from LSR}, apply the fix to the
196 snippet in LSR and send a notification email to a LSR editor with CC to
197 the development list -- see @ref{Adding and editing snippets}. The
198 failure may sometimes not be caused by the snippet in LSR but by the
199 syntax conversion made by @command{convert-ly}; in this case, try to fix
200 @command{convert-ly} or report the problem on the development list, then
201 run @command{makelsr.py} again, see @ref{LSR to Git}. In some cases,
202 when some features has been introduced or vastly changed so it requires
203 (or takes significant advantage of) important changes in the snippet, it
204 is simpler and recommended to write a new version of the snippet in
205 @file{Documentation/@/snippets/@/new}, then run @command{makelsr.py}.
208 @strong{In case the snippet comes from}
209 @file{Documentation/@/snippets/@/new}, apply in
210 @file{Documentation/@/snippets/@/new/@/@var{foo}@/.ly} the same fix you did in
211 @file{Documentation/@/snippets/@/@var{foo}@/.ly}. In case the build failure
212 was caused by a translation string, you may have to fix
213 @file{input/@/texidocs/@/@var{foo}@/.texidoc} instead.
216 In any case, commit all changes to Git.
222 @node Updating LSR to a new version
223 @section Updating LSR to a new version
225 To update LSR, perform the following steps:
230 Download the latest snippet tarball, extract it, and run
231 @code{convert-ly} on all files using the command-line option
232 @code{--to=VERSION} to ensure snippets are updated to the
233 correct stable version.
236 Copy relevant snippets (i.e., snippets whose version is equal to or less
237 than the new version of LilyPond) from
238 @file{Documentation/@/snippets/@/new/} into the tarball.
240 You must not rename any files during this, or the next, stage.
243 Verify that all files compile with the new version of LilyPond,
244 ideally without any warnings or errors. To ease the process,
245 you may use the shell script that appears after this list.
247 Due to the workload involved, we @emph{do not} require that you
248 verify that all snippets produce the expected output. If you
249 happen to notice any such snippets and can fix them, great; but as
250 long as all snippets compile, don't delay this step due to some
251 weird output. If a snippet is broken, the hordes of willing
252 web-2.0 volunteers will fix it. It's not our problem.
255 Create a tarball and send it back to Sebastiano.
258 When LSR has been updated, download another snippet tarball, verify that
259 the relevant snippets from @file{Documentation/@/snippets/@/new/} were
260 included, then delete those snippets from
261 @file{Documentation/@/snippets/@/new/}.
266 Here is a shell script to run all @code{.ly} files in a directory
267 and redirect terminal output to text files, which are then
268 searched for the word "failed" to see which snippets do not compile.
275 STEM=$(basename "$LILYFILE" .ly)
276 echo "running $LILYFILE..."
277 lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt