XML DocBook Publishing Using Publican

Submitted by damar on Tue, 08/08/2017 - 09:55

Damar Thapa


Legal Notice

Copyright © 2017 | DT's Den |
Disclaimer: I provide no warranty of any kind, express or implied, that the information provided is complete, accurate, and reliable. So, you use the information at your own risk.


This article is to document the procedure I took to setup Publican, "a single source publishing tool based on DocBook XML", to get started with DocBook documentation projects. This is not a DocBook or XML tutorial, nor is a replacement for any, official or unofficial, Publican tutorials or manuals.

1. Introduction

DocBook is an XML-based standard, widely used for technical documentation projects throughout the world. It is an open source, OASIS (Advancing Open Standards for the Information Society) standard, with a large following.
The idea of XML (eXtended Markup Language) is to allow users to store data in plain text and transform into different forms/formats as needed. Users do not need special software or tools for document preparation. A simple text editor, like notepad, emacs, pico, vim, etc., is all they need to create a DocBook file. It is, however, helpful to have a better -- preferably, DocBook or XML markup aware -- editor or IDE (Integrated Development Environment). There are plenty of freely available editors and software tools to prepare, transform and publish DocBook files.
DocBook, despite its verbosity, provides power and flexibility in document processing. Using a single plain text (XML) file, we can publish our work in multiple formats, such as PDF, HTML, PostScript, ePUB, txt, etc.
Publican, "a single source publishing tool based on DocBook XML", is a commandline tool that simplifies the process of publishing XML DocBook documents. It was originally developed and used by the RedHat Documentation Team.
This article is to provide a step-by-step tutorial in installing and using Publican with XML DocBook.

2. Installing Publican

Since I am using Ubuntu-based system, I only cover Ubuntu installtion. To install Publican, run the following commands on Bash shell terminal (Please note that ':~$' is not a part of the command, it only represents terminal prompt) :
:~$ sudo apt-get update
:~$ sudo apt-get install publican
If, by the way, uninstalling is needed:
:~$ sudo apt-get remove  publican
:~$ sudo apt-get remove --auto-remove publican
The above installation command installs Publican and all dependencies, such as DocBook libraries, and all other required tools. It install Publican at '/usr/share/publican' directory in Linux system.

3. Creating DocBook document (article, book) project using Publican

Publican is a command-line tool, and 'publican' is its command to perform all its operations. To create a DocBook article, we run the following commands on terminal:
:~$ mkdir /home/damar/docbook
:~$ cd /home/damar/docbook
:~/docbook$ publican create --name "My Doc" --type article --lang=en-GB 
In the first two lines in the above code, I created a directory, '/home/damar/docbook', and changed to it before running the publican command to create a project. This is going to be the directory where my projects will be stored. The third line of code ( 'publican create --name "My Doc" --type article --lang en-GB) creates a DocBook document project named "My Doc" of type "article" that uses 'en-GB' as its language.
The output of the 'publican create' should be similar to the following:
Processing file en-GB/Article_Info.xml -> en-GB/Article_Info.xml
Processing file en-GB/Author_Group.xml -> en-GB/Author_Group.xml
Processing file en-GB/My_Doc.xml -> en-GB/My_Doc.xml
Processing file en-GB/Revision_History.xml -> en-GB/Revision_History.xml 
In the process of creating the above said docbook project, publican does the folloiwngs:
  • Creates a project directory, named 'My_Doc', at the directory where the command was executed (/home/damar/docbook) . The directory name is the same as the document name, spaces replaced by underscore signs, '_'.
  • Inside the project directory ('My_Doc'), it creates the following files:
    • publican.cfg : The project configuration file.
    • en-GB/Article_Info.xml: This file contains Article Information.
    • en-GB/Author_Group.xml: This file contains the Author's detail.
    • en-GB/My_Doc.xml: The file containes the main article file.
    • en-GB/Revision_History.xml : This file contains the article revision history detail.
For those who are familier with XML or Docbook, the above created files should be self-explanatory to complete.

4. Getting help on publican command

A full list of operations of 'publican' is as follows (I am using publican version 4.2) :
add_revision  Add an entry to the revision history
build            Transform XML to other formats (pdf, html, html-single,
                  drupal-book, etc)
clean          Remove all temporary files and directories
clean_ids     Run clean ids for source XML
clean_set     Remove local copies of remote set books
copy_web_brand  Copy a brand's installed web content to another site
create        Create a new book, set, or article
create_brand  Create a new brand
create_site   Create a new WebSite in the supplied location.
help_config   Display help text for the configuration file
install_book  Install a book in to a WebSite.
install_brand  Install a brand to the supplied location
lang_stats    report PO statistics
migrate_site  Migrate a website DataBase from Publican < 3 to Publican 3.
package       Package a language for shipping
print_banned  Print a list of banned DocBook tags
print_known   Print a list of QA'd DocBook tags
print_tree    Print a tree of the xi:includes
print_unused  Print a list of unused XML files
print_unused_images  Print a list of unused Image files
remove_book   Remove a book from a WebSite.
rename        Rename a publican book
report        Print a readability report for the source text.
site_stats    Report on the contents of a WebSite
trans_drop    Snapshot the source language for use in translation.
update_db     Add or remove database entries. Used for processing
                    pre-build books, such as when building packages.
update_po     Update the PO files
update_pot    Update the POT files
update_site   Update an existing sites templates.
zt_pull       Pull translations from Zanata.
zt_push       Push 
To get help on 'create' operations, for example, we can use the following code:
:~$ publican create --help 
And, It should provide the output similar to the following:
    Create a new book, set, or article

        --help                    Display help message
        --config=s                Use a nonstandard config file
        --common_config=s         Override path to Common_Config directory
        --common_content=s        Override path to Common_Content directory
        --nocolours               Disable ANSI colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --allow_network           Allow the XML and XSLT processing to access the network. Defaults off.
        --name=<NAME>             The name of the book, article, set, or brand
        --version=<VERSION>       The version of the product
        --edition=<EDITION>       The edition of the book, article, or set
        --product=<PRODUCT>       The name of the product
        --brand=<BRAND>           The brand to use
        --lang=<LANG>             The language the XML will be written in
        --type=<TYPE>             The type (book, article, or set)
        --dtdver=<DTDVER>         The version of the DocBook DTD to use 
In the same manner, we can get help on any other available Publican operations.

5. Building the project documents

Once the document is ready, it can be built (transformed) into targetted formats with the following command:
:~$ publican build --formats html,pdf  --langs en-GB --config publican.cfg
The above command has to be executed at the root of the project directory ('/home/damar/docbook/My_Doc' directory in this case) where 'publican.cfg' file is located. The above command transforms the project into html and pdf formats, using en-GB as language and configurations provided on publican.cfg file.
To learn the list of formats Publican can generate and all available parameters, we can use the following command:
:~$ publican build  --help 

6. Branding our projects

As an organisation, we like to have our logo, legal statement, copy rights, etc. on all our documents, and Publican provides these details in the form of branding. In the above section, we create our project with the following command:
:~$ publican create --name "My Doc" --type article --lang=en-GB 
As we did not specify the brand name in the above command, Publican used its own default brand during the build process. We, however, can specify brand name with '--brand' parameter. Before we do that, however, let's create our own brand.
The following command creates a brand named 'dtsden' with 'en-GB' as its language:
:~$ publican create_brand --name dtsden --lang en-GB 
The above command creates a directory named 'publican-dtsden' -- where 'dtsden' is the name of the brand -- and generates all branding files inside it. In the branding process, we need to provide our branding details in the files generated inside the 'public-dtsden' directory (similar to document project creation process where we provided document project detail) . All files are well-documented, and if we search for the term 'SETUP' in the directory and replace with the relevant details, our brand should be ready to go.
In Linux distributions, the 'SETUP' term can be searched with the following command (to be executed at 'publican-dtsden' directory):
:~$ grep -r 'SETUP' * 
Once all required details are provided, the brand has to be published with the following command (to be executed at 'publican-dtsden' directory) :
:~$ publican build --formats xml --langs all --publish 
Once published, it can be installed with the following command (to be executed at 'publican-dtsden' directory) :
:~$ sudo publican install_brand --path /usr/share/publican/Common_Content 
The above command installs the dtsden brand at /usr/share/publican/Common_Content directory (this is where all brands are stored in Linux system).
To create a new document project with our new brand, we can run the following command:
:~$ publican create --name "My Doc" --type article --lang=en-GB --brand dtsden  
For an existing project, we can change its brand name on the project 'publican.cfg' file and build project once again. The content of the publican.cfg file:
# Config::Simple 4.59
# Sat Aug  5 22:30:42 2017

type: Article
dtdver: "4.5"
xml_lang: "en-GB"
brand: dtsden  
The project's 'publican.cfg' file is located at the root of the project directory.

7. Summary

Publican is a simple, but powerful, tool for XML DocBook publishing.
It may look complex, seeing a long list of operations and for those who are not comfortable using a terminal (the old school way), but 'create', and 'build' operations are, possibly, the only operations most users may need. It is well-documented, and the explanatory notes in the generated files too are self-explanatory.

A. Revision History

Revision History
Revision 0.0-0 Mon Aug 7 2017 Damar Thapa
Initial creation by publican