Now, the publication chain is ready then come the time to write a article or an book.
3.1. Creating the article's skeleton
The first action will be to create the skeleton of the document. We will take the redaction of this article as an example.
First we will ask publican to create the skeleton of an article with the commands:
mkdir ~/Documentation
cd ~/Documentation
publican create --type=article --name "Publican and Serna" --product "Publication Chain"
--type define the type of the document. It can be article or book.
--name define the name of the document.
--product define the name of the product the document is written for.
The command creates the a directory ~/Documentation/Publican_and_Serna/ directly constructed from the value of the parameter --name. This directory contains the publican configuration file ~/Documentation/Publican_and_Serna/publican.cfg and five other files into the subdirectory ~/Documentation/Publican_and_Serna/en-US/. en-US is the default language of publican.
Lets have a look into these files:
~/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>
The name of this file directly comes from the parameter --name of the command line. This is the root of the document. It includes other files generated automatically like the article information at the beginning and the revision history at the end, just before the index.
In this skeleton it is proposed to write directly the article inside this file. We will see in the next chapter how to make the document easier to edit by including sections into separate and dedicated files.
~/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>
This file contains the information of the article: the title of the document, the product associated, the versions of product and document and an abstract explaining the subject of the article. It also includes other 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>
This file gather the list of the writer of the document. The content of this file is included into the article info.
~/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>
This file is gathering the list of revision of the article. It will be rendered as an appendix and will appear at the end of the document (since it has been included at the end of the root file).
~/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 |">
This file is containing the definition of entities. This file is inserted every generated files. The values defined in this file can be used as parameter inside the XML document.
~/Documentation/Publican_and_Serna/publican.cfg
xml_lang: "en-US"
type: Article
brand: common
This is the configuration file used by publican during the rendering of the document and define the type of the document (Article) and the brand (common) which will define the look and feel of the final rendering. With Ubuntu package, only the 'common' brand is available.
Lets now render the first article with the following command:
cd ~/Documentation/Publican_and_Serna
publican build --langs en-US --formats html-single
and see what has been produced in firefox
firefox tmp/en-US/html-single/index.html
We will see in detail how to use this command to generate user-friendly documentation.
3.2. Preparing the document structure
We have now to edit the files automatically generated and replace default value by real information. This should be done directly by editing the XML file into a text editor.
Edit publican.cfg and add the following lines:
docname: Publican_and_Serna
mainfile: Publican_and_Serna
This will allow to change the title of the document without changing the name of the XML files. If these values are not defined, publican will determine the name of the main file based on the title information written into the information file (Article_Info.xml or Book_Info.xml).
Edit the file Article_Info.xml, Author_Group.xml, Revision_History.xml and Publican_and_Serna.ent. Update their content with the information related to the project and authors.
Now to simplify the edition of our article, we will create sections and we will include these section inside the document root: Publican_and_Serna.xml.
Each section is stored into a file will contain the text and formating description of a chapter.
For the redaction of this article we created the following sections:
Introduction stored into the file Section-Introduction.xml
Installation stored into the file Section-Installation.xml
Redaction stored into the file Section-Redaction.xml
Publication stored into the file Section-Publication.xml
With the following content:
<?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>
This XML code is describing a section. This section is containing one empty title and one empty paragraph.
We then updated the main document Publican_and_Serna.xml to include the section in the order we would like to see.
The root document have now the following content:
<?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>
index has been commented out the since it is not needed for this project.
The structure of our document is ready. We can start writing the article. To make this easier, we will use serna-free. This tool allow to edit the document in a WYSIWYM way. It also does the validation of the conformity of the document with the DocBook rules in real time. If you try to create a structure not supported by the DocBook definition you will see an error and the operation will be canceled..
Start serna-free an open the document Section-Introduction.xml using the menu →
serna-free is divided into 2 main area: The Content Map / TOC on the left side and the edition area in the right side.
The Content Map / TOC panel displays a view of the structure of the document. This is an interactive area that allow to reorganize the data by a simple drag and drop.
The right side is displaying the text into a formatted view. This representation is not reflecting the exact view of the final document but is giving a quick overview of how it will look.
Using these two panels will allow the edition of the document. The first thing to do is the add the title of the section then the text of the paragraph.
In a DocBook article as well as into any XML document the formating is not done during the redaction of the article. We do perform a description of the formating using XML elements. This is the subject of the next chapter.
3.3.2. Docbook XML elements
This chapter is gathering some basic of DocBook element and explaining how to use them into serna-free and how it is encoded into DocBook XML.
In serna-free, the contextual menu can be activated on both right and left panels. It will gives you the access to every possibilities given during the edition of your document. When a text is selected, it is possible to 'tag' the selected text and insert it into an XML element.
Highlighting words
A word could be highlighted using emphasis: Bold, italic, underline
To do so, select the text to highlight into the editing pane and click on the button of the tool-bar. The document will be modified as in the screen-shot below (Bold in bold, Italic in italic and underline underlined):
This is a graphical view of the underlaying XML which is in reality:
<para>A word could be highlighted using enphsis: <emphasis role="bold">Bold</emphasis>, <emphasis role="italic">italic</emphasis>, <emphasis role="underline">underline</emphasis></para>
A word could also represent a filename, an application, a command, a code, a phrase, a classname... There are a lot of possibility offered by the DocBook reference. To highlight a specific word or phrase, you should select it and from the contextual menu select
Images
Image are specific object and have to be inserted as <mediaobject> or <inlinemediaobject> composed by an <imageobject> composed by and <imagedata>.
The <imagedata> element contains attributes visible using the context menu
The image to display is defined by the attribute fileref. You can use the little yellow folder in the bottom left to browse the image to insert.
The underlying XML code looks like that:
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/MediaObject.png"/>
</imageobject>
</mediaobject>
Lists
Two kinds of lists exist: <itemizedlist> and <orderedlist>. In the first list, each item is preceded by a bullet. In the ordered list, each item is preceded by a number (incremental).
The elements <itemizedlist> and <orderedlist> represent the entry point of the list. These elements are composed by a list of <listitem> containing the data to display a <para> like in the example bellow:
The underlying XML code looks like that:
<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>
In this document we only used <itemizedlist>. Creating a sub-listing can be done by inserting an <itemizedlist> or <orderedlist> inside a <listitem>.
Program listing
The element <programlisting> allow to insert pieces of code inside a document. publican as the capability to highlight the code to make it easier to read. To perform the correct highlighting, it is mandatory to define the language of the code. This language will be defined into the attribute language of the element. The list of supported language is available into the following page:
The first column list represent the text to add into the attribute.
To go further
Video how to use serna are available at
Information about how to write a clean docbook article are available at
