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.23.13, 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.


LilyPond — Contributor’s Guide v2.23.13 (development-branch).