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.25.21, 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 file name (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.