| [ << LSR work ] | [Top][Contents] | [ Issues >> ] |
| [ < Introduction to LSR ] | [ Up : LSR work ] | [ Approving snippets > ] |
7.2 Adding and editing snippets
General guidelines
When you create (or find!) a nice snippet, and if it is supported by the LilyPond version running on the LSR, please add it to the LSR. Go to LSR and log in – if you haven’t already, create an account. Follow the instructions on the website. These instructions also explain how to modify existing snippets.
If you think a snippet is particularly informative and should be included in the documentation, tag it with ‘docs’ and one or more other categories, or ask on the development list for somebody who has editing permissions to do it.
Please make sure that the LilyPond code follows our formatting guidelines, see LilyPond formatting.
If a new snippet created for documentation purposes compiles with the LilyPond version currently on LSR, it should be added to the LSR, and a reference to the snippet should be added to the documentation. Please ask a documentation editor to add a reference to it in an appropriate place in the docs. (Note – it should appear in the ‘snippets’ document automatically, once it has been imported into git and built. See LSR to Git.)
If a new snippet uses new features that are not available in the current LSR version of LilyPond, it should be added to directory ‘Documentation/snippets/new/’, and a reference should be added to the manual.
Snippets created or updated in
‘Documentation/snippets/new/’ must be adjusted and copied
to directory ‘Documentation/snippets/’. This should be done
by invoking the makelsr.pl script – after you
have compiled LilyPond. Assuming that your LilyPond build is in
the top-level subdirectory ‘build/’, a proper invocation is
cd /your/lilypond/git/top/dir scripts/auxiliar/makelsr.pl --new
See The makelsr.pl script, for more details.
Be sure that ‘make doc’ runs successfully before submitting a patch, to prevent breaking compilation (see Generating documentation).
Formatting snippets in ‘Documentation/snippets/new/’
When adding a file to this directory, please start the file with the following template …
\version "2.xx.yy"
\header {
% Use existing LSR tags other than 'docs'; the names of the
% `*.snippet-list` files in `Documentation/snippets/` give the
% tags currently used.
lsrtags = "rhythms, expressive-marks"
% The documentation string must use Texinfo syntax. In
% addition, `\` and `"` must be written as `\\` and `\"`,
% respectively.
texidoc = "
This snippet demonstrates @code{\\foo} ...
"
% The snippet title string must be formatted similar to
% `texidoc`.
doctitle = "Snippet title"
}
<LilyPond code starts here>
… and name the file ‘snippet-title.ly’.
It is important that the version number you use at the top of the
example is the minimum LilyPond version that the file compiles
with: for example, if the LSR is currently at 2.22.2, your example
requires 2.23.4, and the current development version of LilyPond
is 2.24.4, use \version "2.23.4".
Particular attention is also necessary for the lsrtags and
doctitle fields: the tags must match tags used in the
documentation, and the doctitle must match the filename
(makelsr.pl shows a helpful error message if it
doesn’t).
The order of \version, \header, and the LilyPond
code must be as shown above, otherwise makelsr.pl aborts
with an error. The same holds for the order of the
lsrtags, texidoc, and doctitle fields within
\header.
| [ << LSR work ] | [Top][Contents] | [ Issues >> ] |
| [ < Introduction to LSR ] | [ Up : LSR work ] | [ Approving snippets > ] |