Maintenant, la chaine de publication est prête et il est temps d'écrire un article ou un livre (book).
3.1. Création du squelette de l'article
La première action consiste à créer le squelette du document. Nous allons prendre la rédaction de ce document comme exemple.
Tout d'abord, nous allons demander à publican de créer le squelette de l'article avec les commandes suivantes:
mkdir ~/Documentation
cd ~/Documentation
publican create --type=article --name "Publican and Serna" --product "Publication Chain"
--type définit le type de document. Le type peut être article ou book.
--name definit le nom du document.
--product definit le nom du produit pour lequel le document est écrit.
La commande crée un répertoire ~/Documentation/Publican_and_Serna/ directement construit à partir de la valeur du paramètre --name. Ce répertoire contient le fichier de configuration de publican: ~/Documentation/Publican_and_Serna/publican.cfg et cinq autres fichiers dans le sous-répertoire ~/Documentation/Publican_and_Serna/en-US/. en-US est la langue par defaut de publican.
Jetons un oeil à ces fichiers:
~/Documentation/Publican_and_Serna/en-US/Publican_and_Serna.xml
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Template.ent">
%BOOK_ENTITIES;
]>
<article>
<xi:include href="Article_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<para>
This is a test paragraph
</para>
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<index />
</article>
Le nom de ce fichier vient directement du paramètre --name de la ligne de commande. C'est le document racine. Il inclut les autres documents générés automatiquement comme le fichier contenant les informations de l'article au début du document et l'historique des révisions à la fin, juste avant l'index.
Dans ce squelette, il est proposé d'écrire directement l'article dans ce fichier. Nous verrons dans le chapitre suivant comment concevoir un document plus facile à éditer en incluant des sections écrites dans des fichiers dédiés.
~/Documentation/Publican_and_Serna/en-US/Article_Info.xml
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE articleinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Publican_and_Serna.ent">
%BOOK_ENTITIES;
]>
<articleinfo id="arti-Publication_Chain-Publican_and_Serna">
<title>Publican and Serna</title>
<subtitle>short description</subtitle>
<productname>Publication Chain</productname>
<productnumber>0.1</productnumber>
<edition>0</edition>
<pubsnumber>0</pubsnumber>
<abstract>
<para>
A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
</para>
</abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
</imageobject>
</inlinemediaobject>
</corpauthor>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</articleinfo>
Ce fichier contient les informations de l'article: le titre du document (title), le produit associé (product), la version du produit et du document ainsi qu'un résumé de l'article. Il inclut aussi d'autres documents:
~/Documentation/Publican_and_Serna/en-US/Author_Group.xml
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Publican_and_Serna.ent">
%BOOK_ENTITIES;
]>
<authorgroup>
<author>
<firstname>Dude</firstname>
<surname>McPants</surname>
<affiliation>
<orgname>Somewhere</orgname>
<orgdiv>Someone</orgdiv>
</affiliation>
<email>Dude.McPants@example.com</email>
</author>
</authorgroup>
Ce fichier rassemble la liste des auteurs du document. Le contenu de ce fichier est inclu dans les informations de l'article.
~/Documentation/Publican_and_Serna/en-US/Revision_History.xml
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Publican_and_Serna.ent">
%BOOK_ENTITIES;
]>
<appendix id="appe-Publican_and_Serna-Revision_History">
<title>Revision History</title>
<simpara>
<revhistory>
<revision>
<revnumber>0-0</revnumber>
<date>Fri Sep 21 2012</date>
<author>
<firstname>Dude</firstname>
<surname>McPants</surname>
<email>Dude.McPants@example.com</email>
</author>
<revdescription>
<simplelist>
<member>Initial creation of book by publican</member>
</simplelist>
</revdescription>
</revision>
</revhistory>
</simpara>
</appendix>
Ce fichier rassemble la liste des révisions de l'article. Il sera visible dans les annexes à la fin du document (Il est en effet inclus à la fin du fichier racine).
~/Documentation/Publican_and_Serna/en-US/Publican_and_Serna.ent
<!ENTITY PRODUCT "Publication Chain">
<!ENTITY BOOKID "Publican and Serna">
<!ENTITY YEAR "2012">
<!ENTITY HOLDER "| You need to change the HOLDER entity in the en-US/Publican_and_Serna.ent file |">
Ce fichier contient les entitées. Ce fichier est inséré dans tous les fichiers générés. Les variables définies dans ce fichier peuvent être utilisées comme paramètre dans les documents XML.
~/Documentation/Publican_and_Serna/publican.cfg
xml_lang: "en-US"
type: Article
brand: common
Ce fichier est utilisé par publican pendant la génération du document. Il définit le type du document (article) et la marque (brand) qui va définir le style du rendu final. Avec les paquets fournit par Ubuntu, seul la marque 'common' est disponible.
Effectuons maintenent le rendu de l'article avec la commande:
cd ~/Documentation/Publican_and_Serna
publican build --langs en-US --formats html-single
et voyons a quoi notre document ressemble dans firefox
firefox tmp/en-US/html-single/index.html
Nous allons voir en détail comment utiliser cette commande et générer des documents agréables à lire.
3.2. Préparation de la structure du document
Nous devons maintenant modifier les fichiers générés automatiquement et remplacer les valeurs par défaut par de vrais informations. Ceci devrait être effectué directement en éditant le fichier dans un editeur de texte classique.
Modifiez le fichier publican.cfg en y ajoutant les lignes suivantes:
docname: Publican_and_Serna
mainfile: Publican_and_Serna
Ceci permettra de changer le titre du document sans changer le nom du fichier XML. Si ces valeurs ne sont pas définies, publican déterminera le nom du fichier racine en fonction du titre inscrit dans les informations de l'article (Article_Info.xml ou Book_Info.xml).
Modifiez les fichiers Article_Info.xml, Author_Group.xml, Revision_History.xml et Publican_and_Serna.ent. Modifiez leur contenu avec les informations relatives au projet et aux auteurs.
Maintenant, pour simplifier la rédation de notre article, nous allons créer des sections que nous inclurons dans le document racine : Publican_and_Serna.xml.
Chaque section est stockée dans un fichier et contient le texte et la description du format de chaque chapitre.
Pour la rédaction de cet article, nous créerons les sections suivantes:
Introduction stockée dans le fichier Section-Introduction.xml
Installation stockée dans le fichier Section-Installation.xml
Redaction stockée dans le fichier Section-Redaction.xml
Publication stockée dans le fichier Section-Publication.xml
Avec le contenu suivant:
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Publican_and_Serna.ent">
%BOOK_ENTITIES;
]>
<section>
<title/>
<para/>
</section>
Ce code XML décrit une section. Cette section contient un titre vide et un paragraphe vide.
Nous mettons alors le document racine Publican_and_Serna.xml à jour pour y inclure les sections dans leur ordre d'apparition.
La racine du document contient maintenant ce contenu:
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Publican_and_Serna.ent">
%BOOK_ENTITIES;
]>
<article>
<xi:include href="Article_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Section-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Section-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Section-Redaction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Section-Publication.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Section-Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</article>
Nous avons commenté l'index qui n'est pas nécessaire pour ce projet.
3.3. Ecriture de l'article:
3.3.1. Utilisation de serna-free
La structure de notre document est prête. Nous pouvons commencer à écrire notre article. Pour rendre cette rédaction plus facile nous allons utiliser serna-free. Cet outil permet l'édition de document en WYSIWYM . Il effectue aussi le validation à la volée de la conformité du document avec les règles DocBook. Si vous essayez d'enfreindre une de ces règles, le logiciel vous retournera une erreur et annulera l'action fautive.
Démarrez serna-free et ouvez le document Section-Introduction.xml en utilisant le menu →
serna-free est divisé en deux zones: sur la gauche Content Map / TOC et sur la droite la zone d'édition.
La zone Content Map / TOC affiche une vue de la structure du document XML. Cette zone est interactive et permet la réorganisation du document par simple glisser/déposer.
La zone de droite affiche une vue formatée du document. Cette representetion ne reflète pas la vue exacte du document final mais un aperçu de ce à quoi le document ressemblera.
L'usage des deux zones permet l'édition du document. La première chose à faire est d'ajouter le titre de la section ainsi que le texte du paragraphe.
Dans un article DocBook tout comme dans un fichier XML, le formatage n'est pas effectué durant la rédaction de l'article. Nous effectuerons une description du format en utilisant des balises XML. Les balises XML sont le sujet du prochain paragraphe.
3.3.2. Les balises ou éléments XML
Ce chapitre rassemble quelques éléments de base de DocBook et explique comment les mettres en oeuvre dans serna-free. Nous verrons aussi comment ces éléments sont encodés en DocBook XML.
Dans serna-free, le menu contextuel peut être activé dans les deux zones d'édition. Il offre un accès à toutes les possibilités d'édition du document.Quand le texte est séléctioné, il est possible de le 'tagguer' et de l'insérer entre deux balises XML.
Mettre en évidence des mots
Un mot peut être mis en évidnce en le mettant en : Gras (bold), italique (italic) ou en le soulignant (underline)
Pour faire ceci, sélectionnez le texte à mettre en évidence dans la zone d'édition puis cliquez sur les boutons de la barre d'outils. Le document sera modifié comme représenté dans la copie d'écran ci-dessous:
Cette image représente le code XML ainsi généré:
<para>A word could be highlighted using enphsis: <emphasis role="bold">Bold</emphasis>, <emphasis role="italic">italic</emphasis>, <emphasis role="underline">underline</emphasis></para>
Un mot peut aussi représenter un fichier (filename), une application, une commande (command), un code, une phrase, un nom de classe (classname)... Il y a de nombreuse possibilités offertes par les références DocBook. Pour mettre en evidence un mot ou une phrase, vos devez le seletionner puis utiliser le menu contextuel
Images
Les images sont des objets spécifiques et doivent être insérées dans des balises <mediaobject> ou <inlinemediaobject> composées par un <imageobject> lui même contenant une <imagedata>.
L'élément <imagedata> contient des attributs accessible depuis le menu contextuel
L'image à afficher est définie par l'attribut fileref. Vous pouvez utiliser la petite icône en forme de dossier jaune pour sélectionner l'image à insérer.
Le code XML ainsi généré ressemblera à ceci:
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/MediaObject.png"/>
</imageobject>
</mediaobject>
Listes
Deux types de listes existent:<itemizedlist> et <orderedlist>. Pour la première balise, chaque élément de la liste sera précédé par un point. Dans la liste ordonée, chaque élément est précédé par un nombre.
Les élements <itemizedlist> et <orderedlist> représentent les points d'entrées des listes. Ces éléments sont composés de <listitem> qui contiennent l'information à afficher, un <para> dans l'exemple ci dessous:
Le code XML ainsi généré ressemblera à ceci:
<itemizedlist>
<listitem>
<para>Introduction stored into the file <filename>Section-Introduction.xml</filename></para>
</listitem>
<listitem>
<para>Installation stored into the file <filename>Section-Installation.xml</filename></para>
</listitem>
<listitem>
<para>Redaction stored into the file <filename>Section-Redaction.xml</filename></para>
</listitem>
<listitem>
<para>Publication stored into the file <filename>Section-Publication.xml</filename></para>
</listitem>
</itemizedlist>
Dans ce document nous n'utilisons que des <itemizedlist>. La creation de sous-liste peut se faire en insérant un <itemizedlist> ou <orderedlist> dans un <listitem>.
Listing de programme
L'élément <programlisting> permet d'insérer des morceaux de code dans le document. publican offre la possibilité d'effectuer une coloration synthaxique du texte pour rendre le code plus lisible. Pour permettre une coloration synthaxique correcte, il faut définir le langage utilisé. Ce langage sera définit dans l'attribut language. La liste des langages supportés se trouve dans la page suivante:
La première colonne représente les mots clés à ajouter dans l'attribut.
Pour aller plus loin
Des vidéos commentées en anglais expliquant l'utilisation de serna sont disponible ici:
Des recommentations pour écrire un article DocBook sont disponible en anglais ici:
