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.
91 and name the file @file{snippet-title.ly}.
94 @node Approving snippets
95 @section Approving snippets
97 The main task of LSR editors is approving snippets. To find a list of
98 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
99 select @qq{No} from the dropdown menu to the right of the word
100 @qq{Approved} at the bottom of the interface, then click
108 Does the snippet make sense and does what the author claims that
109 it does? If you think the snippet is particularly helpful, add
110 the @qq{docs} tag and at least one other tag.
113 If the snippet is tagged with @qq{docs}, check to see if it
114 matches our guidelines for @ref{LilyPond formatting}.
116 Also, snippets tagged with @qq{docs} should not be explaining
117 (replicating) existing material in the docs. They should not
118 refer to the docs; the docs should refer to them.
121 If the snippet uses scheme, check that everything looks good and
122 there are no security risks.
124 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
125 command into our source tree if you do not do this! Take this
126 step @strong{VERY SERIOUSLY}.}
137 Make sure that @command{convert-ly} and @command{lilypond} commands in
138 current PATH are in a bleeding edge version -- latest release from
139 master branch, or even better a fresh snapshot from Git master branch.
142 From the top source directory, run:
145 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
146 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
147 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
151 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
154 Follow the instructions printed on the console to manually check for
157 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
158 command into our source tree if you do not do this! Take this
159 step @strong{VERY SERIOUSLY}.}
162 Do a git add / commit / push.
166 Note that whenever there is one snippet from
167 @file{Documentation/snippets/new} and the other from LSR with the same
168 file name, the one from @file{Documentation/snippets/new} will be copied
169 by @command{makelsr.py}.
172 @node Fixing snippets in LilyPond sources
173 @section Fixing snippets in LilyPond sources
175 In case some snippet from @file{Documentation/snippets} causes the
176 documentation compilation to fail, the following steps should be
177 followed to fix it reliably.
182 Look up the snippet filename @file{@var{foo}.ly} in the error output
183 or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the
184 documentation build succesfully.
187 Determine where it comes from by looking at its first line, e.g. run
190 head -1 Documentation/snippets/@var{foo}.ly
194 @strong{In case the snippet comes from LSR}, apply the fix to the
195 snippet in LSR and send a notification email to a LSR editor with CC to
196 the development list -- see @ref{Adding and editing snippets}. The
197 failure may sometimes not be caused by the snippet in LSR but by the
198 syntax conversion made by @command{convert-ly}; in this case, try to fix
199 @command{convert-ly} or report the problem on the development list, then
200 run @command{makelsr.py} again, see @ref{LSR to Git}. In some cases,
201 when some features has been introduced or vastly changed so it requires
202 (or takes significant advantage of) important changes in the snippet, it
203 is simpler and recommended to write a new version of the snippet in
204 @file{Documentation/snippets/new}, then run @command{makelsr.py}.
207 @strong{In case the snippet comes from}
208 @file{Documentation/snippets/new}, apply in
209 @file{Documentation/snippets/new/@var{foo}.ly} the same fix you did in
210 @file{Documentation/snippets/@var{foo}.ly}. In case the build failure
211 was caused by a translation string, you may have to fix
212 @file{input/texidocs/@var{foo}.texidoc} instead.
215 In any case, commit all changes to Git.
221 @node Updating LSR to a new version
222 @section Updating LSR to a new version
224 To update LSR, perform the following steps:
229 Download the latest snippet tarball, extract it, and run
230 @code{convert-ly} on all files using the command-line option
231 @code{--to=VERSION} to ensure snippets are updated to the
232 correct stable version.
235 Copy relevant snippets (i.e., snippets whose version is equal to or less
236 than the new version of LilyPond) from
237 @file{Documentation/snippets/new/} into the tarball.
239 You must not rename any files during this, or the next, stage.
242 Verify that all files compile with the new version of LilyPond,
243 ideally without any warnings or errors. To ease the process,
244 you may use the shell script that appears after this list.
246 Due to the workload involved, we @emph{do not} require that you
247 verify that all snippets produce the expected output. If you
248 happen to notice any such snippets and can fix them, great; but as
249 long as all snippets compile, don't delay this step due to some
250 weird output. If a snippet is broken, the hordes of willing
251 web-2.0 volunteers will fix it. It's not our problem.
254 Create a tarball and send it back to Sebastiano.
257 When LSR has been updated, download another snippet tarball, verify that
258 the relevant snippets from @file{Documentation/snippets/new/} were
259 included, then delete those snippets from
260 @file{Documentation/snippets/new/}.
265 Here is a shell script to run all @code{.ly} files in a directory
266 and redirect terminal output to text files, which are then
267 searched for the word "failed" to see which snippets do not compile.
274 STEM=$(basename "$LILYFILE" .ly)
275 echo "running $LILYFILE..."
276 lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt