### 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.