3.2.4 DocBook

For inserting LilyPond snippets it is good to keep the conformity of our DocBook document, thus allowing us to use DocBook editors, validation etc. So we don’t use custom tags, only specify a convention based on the standard DocBook elements.

Common conventions

For inserting all type of snippets we use the mediaobject and inlinemediaobject element, so our snippets can be formatted inline or not inline. The snippet formatting options are always provided in the role property of the innermost element (see in next sections). Tags are chosen to allow DocBook editors format the content gracefully. The DocBook files to be processed with lilypond-book should have the extension ‘.lyxml’.

Including a LilyPond file

This is the most simple case. We must use the ‘.ly’ extension for the included file, and insert it as a standard imageobject, with the following structure:

    <imagedata fileref="music1.ly" role="printfilename" />

Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.

Including LilyPond code

Including LilyPond code is possible by using a programlisting, where the language is set to lilypond with the following structure:

    <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
\context Staff \with {
  \remove "Time_signature_engraver"
  \remove "Clef_engraver"}
  { c4( fis) }

As you can see, the outermost element is a mediaobject or inlinemediaobject, and there is a textobject containing the programlisting inside.

Processing the DocBook document

Running lilypond-book on our ‘.lyxml’ file will create a valid DocBook document to be further processed with ‘.xml’ extension. If you use dblatex, it will create a PDF file from this document automatically. For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it.

LilyPond — Usage v2.21.7 (development-branch).