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.