3.2.4 DocBook

For inserting LilyPond snippets it is good to keep the conformity of DocBook documents, allowing the use of DocBook editors, validation, etc. For this reason no custom tags are provided, only specifying conventions based on standard DocBook elements.

Common conventions

For inserting all types of snippets we use the mediaobject and inlinemediaobject elements to format snippets inline or not inline, respectively. The snippet formatting options are always provided in the role property of the innermost element (see 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 simplest case. We must use the .ly extension for the included file and insert it as a standard imageobject, with the following structure:

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

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 environment where the language is set to lilypond, with the following structure:

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

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 a .lyxml file creates a valid DocBook document (with extension .xml) to be further processed. If you use dblatex, it creates 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.