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.
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.
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.
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.
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 Create a new book, set, or article Options: --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.
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
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.
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 0.0-0||Mon Aug 7 2017|