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} commands in
145 current PATH are in a bleeding edge version -- latest release from
146 master branch, or even better a fresh snapshot from Git master branch.
149 From the top source directory, run:
152 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
153 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
154 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
158 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
161 Follow the instructions printed on the console to manually check for
164 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
165 command into our source tree if you do not do this! Take this
166 step @strong{VERY SERIOUSLY}.}
169 Do a git add / commit / push.
173 Note that whenever there is one snippet from
174 @file{Documentation/snippets/new} and the other from LSR with the same
175 file name, the one from @file{Documentation/snippets/new} will be copied
176 by @command{makelsr.py}.
179 @node Fixing snippets in LilyPond sources
180 @section Fixing snippets in LilyPond sources
182 In case some snippet from @file{Documentation/snippets} causes the
183 documentation compilation to fail, the following steps should be
184 followed to fix it reliably.
189 Look up the snippet filename @file{@var{foo}.ly} in the error output
190 or log, then fix the file @file{Documentation/snippets/@var{foo}.ly} to make the
191 documentation build successfully.
194 Determine where it comes from by looking at its first line, e.g. run
197 head -1 Documentation/snippets/@var{foo}.ly
201 @strong{In case the snippet comes from LSR}, apply the fix to the
202 snippet in LSR and send a notification email to a LSR editor with CC to
203 the development list -- see @ref{Adding and editing snippets}. The
204 failure may sometimes not be caused by the snippet in LSR but by the
205 syntax conversion made by @command{convert-ly}; in this case, try to fix
206 @command{convert-ly} or report the problem on the development list, then
207 run @command{makelsr.py} again, see @ref{LSR to Git}. In some cases,
208 when some features has been introduced or vastly changed so it requires
209 (or takes significant advantage of) important changes in the snippet, it
210 is simpler and recommended to write a new version of the snippet in
211 @file{Documentation/snippets/new}, then run @command{makelsr.py}.
214 @strong{In case the snippet comes from}
215 @file{Documentation/snippets/new}, apply in
216 @file{Documentation/snippets/new/@var{foo}.ly} the same fix you did in
217 @file{Documentation/snippets/@var{foo}.ly}. In case the build failure
218 was caused by a translation string, you may have to fix
219 @file{input/texidocs/@var{foo}.texidoc} instead.
222 In any case, commit all changes to Git.
227 @node Renaming a snippet
228 @section Renaming a snippet
230 Due to the potential duality of snippets (i.e. they may exist both
231 in the LSR database, and in @code{Documentation/snippets/new/}),
232 this process is a bit more involved than we might like.
236 Send an email LSR editor, requesting the renaming.
239 The LSR editor does the renaming (or debates the topic with you),
240 then warns the LSR-to-git person (wanted: better title) about the
244 LSR-to-git person does his normal job, but then also renames any
245 copies of the snippets in @code{Documentation/snippets/new/}, and
246 any instances of the snippet name in the documentation.
248 @code{git grep} is highly recommended for this task.
253 @node Updating LSR to a new version
254 @section Updating LSR to a new version
256 To update LSR, perform the following steps:
261 Download the latest snippet tarball, extract it, and run
262 @code{convert-ly} on all files using the command-line option
263 @code{--to=VERSION} to ensure snippets are updated to the
264 correct stable version.
267 Copy relevant snippets (i.e., snippets whose version is equal to or less
268 than the new version of LilyPond) from
269 @file{Documentation/snippets/new/} into the tarball.
271 You must not rename any files during this, or the next, stage.
274 Verify that all files compile with the new version of LilyPond,
275 ideally without any warnings or errors. To ease the process,
276 you may use the shell script that appears after this list.
278 Due to the workload involved, we @emph{do not} require that you
279 verify that all snippets produce the expected output. If you
280 happen to notice any such snippets and can fix them, great; but as
281 long as all snippets compile, don't delay this step due to some
282 weird output. If a snippet is broken, the hordes of willing
283 web-2.0 volunteers will fix it. It's not our problem.
286 Create a tarball and send it back to Sebastiano.
289 When LSR has been updated, download another snippet tarball, verify that
290 the relevant snippets from @file{Documentation/snippets/new/} were
291 included, then delete those snippets from
292 @file{Documentation/snippets/new/}.
297 Here is a shell script to run all @file{.ly} files in a directory
298 and redirect terminal output to text files, which are then
299 searched for the word "failed" to see which snippets do not compile.
306 STEM=$(basename "$LILYFILE" .ly)
307 echo "running $LILYFILE..."
308 lilypond --format=png -ddelete-intermediate-files "$LILYFILE" >& "$STEM".txt