1 @c -*- coding: us-ascii; mode: texinfo; -*-
6 * Introduction to LSR::
7 * Adding and editing snippets::
10 * Fixing snippets in LilyPond sources::
14 @node Introduction to LSR
15 @section Introduction to LSR
18 @uref{http://lsr.dsi.unimi.it/, LilyPond Snippet Repository (LSR)}
19 is a collection of lilypond examples. A subset of these examples
20 are automatically imported into the documentation, making it easy
21 for users to contribute to the docs without learning git and
25 @node Adding and editing snippets
26 @section Adding and editing snippets
28 When you create (or find!) a nice snippet, please add it to LSR. Go
29 to @uref{http://lsr.dsi.unimi.it/, LSR} and log in (if you haven't
30 already, create an account). Follow the instructions on the website.
31 These instructions also explain how to modify existing snippets.
33 If you think the snippet is particularly informative and you think
34 it should be included in the documentation, tag it with @qq{docs}
35 and one or more other categories.
37 Please make sure that the lilypond code follows the guidelines in
38 @ref{LilyPond formatting}.
41 @node Approving snippets
42 @section Approving snippets
44 The main task of LSR editors is approving snippets. To find a list of
45 unapproved snippets, log into @uref{http://lsr.dsi.unimi.it/, LSR} and
46 select @qq{No} from the dropdown menu to the right of the word
47 @qq{Approved} at the bottom of the interface, then click
55 Does the snippet make sense and does what the author claims that
56 it does? If you think the snippet is particularly helpful, add
57 the @qq{docs} tag and at least one other tag.
60 If the snippet is tagged with @qq{docs}, check to see if it
61 matches our guidelines for @ref{LilyPond formatting}.
64 If the snippet uses scheme, check that everything looks good and
65 there are no security risks.
67 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
68 command into our source tree if you do not do this! Take this
69 step @strong{VERY SERIOUSLY}.}
80 Make sure that @command{convert-ly} and @command{lilypond} commands in
81 current PATH are in a bleeding edge version -- latest release from
82 master branch, or even better a fresh snapshot from Git master branch.
85 From the top source directory, run:
88 wget http://lsr.dsi.unimi.it/download/lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
89 tar -xzf lsr-snippets-docs-@var{YYYY-MM-DD}.tar.gz
90 scripts/auxiliar/makelsr.py lsr-snippets-docs-@var{YYYY-MM-DD}
94 where @var{YYYY-MM-DD} is the current date, e.g. 2009-02-28.
97 Follow the instructions printed on the console to manually check for
100 @warning{Somebody could sneak a @code{#'(system "rm -rf /")}
101 command into our source tree if you do not do this! Take this
102 step @strong{VERY SERIOUSLY}.}
105 Do a git add / commit / push.
110 @node Fixing snippets in LilyPond sources
111 @section Fixing snippets in LilyPond sources
113 In case some snippet from @file{input/lsr} cause the documentation
114 compilation to fail, the following steps should be followed to fix it
120 Look up the snippet filename @file{@var{foo}.ly} in the error output
121 or log, then fix the file @file{input/lsr/@var{foo}.ly} to make the
122 documentation build succesfully.
125 Determine where it comes from by looking at its first line, e.g. run
128 head -1 input/lsr/@var{foo}.ly
132 @strong{In case the snippet comes from LSR}, apply the fix to the
133 snippet in LSR and send a notification email to a LSR editor with CC
134 to the development list -- see @ref{Adding and editing snippets}. The
135 failure may sometimes not be caused by the snippet in LSR but by the
136 syntax conversion made by @command{convert-ly}; in this case, try to
137 fix @command{convert-ly} or report the problem on the development
138 list, then run @command{makelsr.py} again, see @ref{LSR to Git}. In
139 some cases, when some features has been introduced or vastly changed
140 so it requires (or takes significant advantage of) important changes
141 in the snippet, it is simpler and recommended to write a new version
142 of the snippet in @file{input/new}, then run @command{makelsr.py}.
145 @strong{In case the snippet comes from} @file{input/new}, apply in
146 @file{input/new/@var{foo}.ly} the same fix you did in
147 @file{input/lsr/@var{foo}.ly}. In case the build failure was caused
148 by a translation string, you may have to fix
149 @file{input/texidocs/@var{foo}.texidoc} instead.
152 In any case, commit all changes to Git.