Cours DocBook accelere

Chapitre 10. Description de l'interface d'une application

10.1. Exemples

Liste des balises concernées par cette section :

literallayout - Enveloppe pour l'ensemble des lignes hors du texte principal qui ne sont pas balisées comme écrans, exemples ou listings, dans lesquelles les coupures et les espaces sont significatives.
example - Exemple d'un programme d'ordinateur ou une information relative
informalexample - Exemple sans titre
programlisting - Listing de toutes les parties d'un programme
screen - Texte que l'utilisateur voit sur son écran

Il existe plusieurs situations dans lesquelles vous devez intégrer des exemples de code source, commandes ou actions en interface graphique dans votre documentation. DocBook possède plusieurs balises pour ces besoins. Chaque fois que vous voulez citer des exemples dans votre document, placez simplement une balise <example> ou <informalexample> aux environs de votre texte ou graphique d'exemple.

Exemple 10-1. Un exemple


<example>
<title>A BASIC Example</title>
<programlisting>
10 PRINT "HELLO WORLD"
20 GOTO 10
</programlisting>
</example>
 

Dans le premier exemple, nous avons présenté un programme simple en BASIC. Le code contenu dans la balise <programlisting> est présenté avec l'espacement et les coupures de lignes intacts ce qui est très utile pour des exemples de code et situations similaires dans lesquelles vous devez préserver la mise en forme exacte. Les balises LiteralLayout et Screen fonctionnent de la même façon, mais sont utilisées pour indiquer différents types de contenu. Screen contient des sorties qui apparaîtront à l'écran, tandis que LiteralLayout sert pour le texte qui doit être rendu avec les coupures et les tabulations.

L'exemple ressemblera à ça :

Exemple 10-2. Un programlisting


10 PRINT "HELLO WORLD"
20 GOTO 10

Un problème peut se produire avec les balises LiteralLayout, ProgramListing et Screen : tout le texte est rendu littéralement, mais les balises DocBook sont interprétées comme balises et non comme texte. Que devez vous faire quand vous voulez montrer du texte sans avoir les balises interprétées ? La réponse est d'utiliser <![CDATA[ ]]>, qui désigne le texte contenu dans les parenthèses comme données et ne sera pas interprété par l'analyseur SGML. Tout texte entre parenthèses sera rendu tel quel après la conversion, ainsi l'exemple ci-dessus reproduira correctement les balises.

Exemple 10-3. Utilisation de CDATA


<example>
<title>Du balisage</title>
<screen> 
<![CDATA[
<para>Ceci est un exemple DocBook.</Para>
 ]]>

</screen>
</example>
 

Une fois converti :

Exemple 10-4. Du balisage


<para>Ceci est un exemple DocBook.</para>