3.2.4 DocBook

L’inclusion de documents LilyPond ne doit nuire en rien à la conformité du document DocBook ; l’utilisation d’éditeurs spécialisés ainsi que d’outils de validation en sera ainsi préservée. C’est la raison pour laquelle nous ne définirons pas de balise spécifique ; nous respecterons plutôt les conventions des éléments standard de DocBook.

Conventions communes

Quel que soit le type d’extrait à inclure, nous utiliserons les éléments mediaobject et inlinemediaobject, de telle sorte que ces inclusions soient incorporées directement ou non dans le document final. Les options de formatage des extraits en question sont toujours fournies par la propriété role de l’élément central – voir les paragraphes suivants. Les balises sont déterminées de manière à ce que les éditeurs DocBook prennent en charge du mieux possible leur contenu. Les fichiers DocBook destinés à un traitement par lilypond-book doivent avoir une extension .lyxml.

Inclusion d’un fichier LilyPond

Il s’agit ici du cas le plus simple. Le fichier à inclure doit avoir une extension .ly et sera inséré comme n’importe quel imageobject, en respectant la structure suivante :

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

Vous pouvez utiliser, en tant que balise externe, aussi bien mediaobject que inlinemediaobject.

Inclusion de code LilyPond

L’inclusion de code LilyPond se réalise à l’aide d’un environnement programlisting auquel on associe le langage lilypond. En voici la syntaxe :

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

Comme vous le remarquez, la balise externe – qu’il s’agisse d’un mediaobject ou d’un inlinemediaobject – comporte un bloc textobject qui contiendra le programlisting.

Génération du document DocBook

lilypond-book génère, à partir d’un fichier .lyxml, un document DocBook tout à fait valide – extension .xml – que vous pourrez ensuite traiter avec votre application habituelle. Dans le cas de dblatex, vous obtiendrez alors automatiquement un fichier PDF. Les feuilles de style XSL DocBook officielles permettent de générer du HTML (HTML Help, JavaHelp, etc.) ; vous pourriez néanmoins devoir y apporter quelques adaptations.