7.2 Adding and editing snippets

General guidelines

When you create (or find!) a nice snippet, please add it to the Wiki. Go to the LilyPond Wiki and optionally log in – if you haven’t already, create an account. Follow the help instructions on the website so that you know how to proceed.

You should always tag a newly created page with a category at the end of a page. If you think a snippet is particularly informative and should be included in the documentation, suggest it in the snippet’s ‘Discussion’ page. Note that snippets intended for the LilyPond documentation must have a special layout.

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 current stable LilyPond version, it should be added to the Wiki. If a new snippet created for documentation purposes uses features that are not available in the current stable release of LilyPond, it should be put into directory Documentation/snippets/new/ instead. In both cases, 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’ manual automatically, once it has been imported into git and built. See LilyPond Wiki to Git.)

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 use the following template (omitting the explanatory comments) …

\version "2.xx.yy"

\header {
  % Use existing Wiki categories other than 'Category:Included in
  % the official documentation' and 'Category:Snippet' (see
  % 'https://wiki.lilypond.community/wiki/Special:Categories' for
  % a list) and omit the 'Category:' prefix.
  categories = "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`.  However, don't use markup commands like `@emph`
  % or `@code` so that the title can be directly converted to a
  % Wiki page title, which doesn't allow formatting.
  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 snippet is the minimum LilyPond version that the file compiles with; for example, if the snippet requires 2.25.24, use \version "2.25.24".

Particular attention is also necessary for the categories and doctitle fields: the categories must match category names used in the Wiki, 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 categories, texidoc, and doctitle fields within \header.