Product SiteDocumentation Site

Publican 3.0

Release Notes

New Features and Bugfixes in Publican 3.0

Rüdiger Landmann

Red Hat Engineering Content Services

Legal Notice

Copyright © 2012 Red Hat, Inc. This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at


This document describes the enhancements and fixes included in Publican 3.0.
Publican is available for download at
For PDF generation FOP has been replaced with wkhtmltopdf.
Publican website
The database has changed. Users of Publican 2.x websites must run publican migrate_site to update their database.
Publican now supports 2 web site layouts, controlled with the web_style parameter in the site configuration file. web_style 1, the original style, has been tweaked to be a more modern. web_style 2 a new layout style that is much more modern that the original style.


Publican uses javascript to check for the existance of toc.html to determine which style to use for the layout. If you switch from style 1 to style 2 you will need to manually remove toc.html.
Doing it this way allows you to switch between styles without regenrating any of the books.
Updates to change tracking.
Changes were tracked in publican.spec. The Changes file now tracks changes, and the spec file tracks rebuilds of packages.
Cleaned up README file.
Corrected document conventions text.
Fixed inconsistencies between text and examples.
Make XmlClean use File::Inplace instead of grep & sed.
Deleted STRICT mode. Added banned_tags and banned_attrs configurations.
In a brand you can add a list of banned tags or attributes using banned_tags and banned_attrs respectively to either defaults.cfg or overrides.cfg. These will be listed by the Publican action print_banned.
Fixed command example in PUG.
Use revision history for edition and release in translated languages.
update_po now adds a LANG/Revision_History.xml file; building the book adds this file to the English Revision History.


Many books have revnumbers that will not work when trying to package books due to format constraints. These books will have to have their revnmbers corrected.
Deleted edition and release config parameters.
Add add_revision action and associated options.
publican add_revision adds an entry in Revision_History.xml. Options:
the language the XML will be written in.
revision number to use for a revision. Will default to REVNUMBER + 1 if not specified.
date to use for a revision. Will default to current date if not set.
an entry to be added to the revision. Can be specified multiple times.
firstname to use for revision author. Optional if set in ~/.publican.cfg.
surname to use for revision author. Optional if set in ~/.publican.cfg.
email address to use for revision author. Optional if set in ~/.publican.cfg.
Fix wrong BuildRequires and path for desktop packages.
Correct typos. Yuri Chornoivan
Fix CreateBook texts missing from pot file.
Replace msgmerge
Implimented internal XML->PO and PO->XML routines.
Added --msgmerge to update_po to allow users to switch back to using msgmerge.
update_po --msgmerge
use gettext's msgmerge for POT/PO merging.
Added base_brand config option for brands to allow multiple base brands.
DocBook 5 tech preview.
To convert a publican book's XML to DB5, cd in to the book directory and run:
Edit the publican.cfg:
brand: common-db5
dtdver: 5.0
Test build with --novalid.
Added site config toc_type to allow selecting TOC styles.
toc_type specifies the name of a custom TOC template. By default, Publican looks for toc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
Added authortest target for author tests.
Removed Site statistics, site tech and HTML site map from Publican website.
Truncate PO Fuzzy/Un-translated message, added PO line number.
The error message used to display the full fuzzy string. The message is now truncated at 64 characters and displays the PO line number the entry starts on.
Add translation Author_Group.xml
Translators are now able to add an Author_Group.xml to their language directory. When the document is built this file will be appended to the source language version.
Split pod from publican command to allow auto-generation.
Fix bridgehead links not working in html.
Re-add API check.
Fix wkhtmltopdf format when building web packages.
Updates based on beta testing.
Fix sort order of books in website navigation.
String comparison of Product and Book Name is now case insensitive.
See the new sort_order parameter for more details on how to customize website order.
Extra bottom margin for screen.
Change stepalternative list style.
Add print_unused_images action.
Prints a list of the image files not referenced by an <imagedata> tag in a book, article, or set.
Fix print_unused not matching relative paths.
Fix empty parameters being parsed as arrays
Empty fields were corrupting the website TOC and displaying values such as ARRAY(0x388baf8).
Empty fields in publican.cfg are now ignored.
Removed border from blockquote.
No newline after email when inline.
Add Indic fonts to RPM spec requires.
Switch RPM spec requires from FOP to wkhtmltopdf
Remove old2new action & Makefile::Parser dep.
Override install & common paths on darwin.
Remove Image::Magick & Image::Size deps and max_image_width option.
Treat graphic like imagedata.
Support superscript, fix color.
Fix test warnings and errors.
Change title page layout in Publican website.
Remove trailing slash from --langs completion.
Remove white space munging from XmlClean.
Fix corpauthor killing FOP.
Remove --cvs option.
Publican no longer the supports the cvs option for building RPMs.
Update Conventions translation in pt-BR
Fix build failing when source language directory is read only.
Add src_dir parameter to allow building outside source tree.
Specifies the directory to source Publican files from.
Apply Spanish translation update from Ismael Olea.
Added web_cfg to allow non-standard paths for rpm based web sites.
This means you can have more than one Publican website on a single server.
Ensure xml:lang is set by XmlClean for DocBook 5 sources.
DocBook 5 is tech preview in Publican 3.0.
Publican now accepts a per user defaults file.
Users can set their own default values for Publican in ~/.publican.cfg. Currently, Publican supports the following values:
Use ~/.publican.cfg to simplify your build command, or with the new add_revision action.
Catch txt not being rebuilt.
Text only builds now refresh the text file. There is no need to run Publican clean before rebuilding a text document.
Catch invalid version when installing book.
Fix duplicate IDs in HTML outputs.
Fix some epub validation errors.
Add brand_dir option and publican XSL name space.
The Publican build option brand_dir allows you to specify the location of brand files. These files do not have to be part of an installed brand.
You can ship custom XSL in a folder named xsl in your brand: it sits at the same level as the various language files for your brand. Publican uses any XSL that it finds in that directory to override the XSL templates that we ship in the common brand (which in turn override the XSL templates that the DocBook project ships).


Brands wishing to support brand_dir that supply XSL files need to change the relative path to a URI.

Example 1. Updating brand XSL

<xsl:import href="../../../xsl/html.xsl"/>
<xsl:import href=""/>



Platform support for this this change requires updating the XML catalog on the system. Packagers should automate this for their platforms.

Example 2. Modifying the XML catalog on an RPM based system

%{_bindir}/xmlcatalog --noout --add "rewriteURI" \
 "" \
 "file://%{_datadir}/publican/xsl/"  $CATALOG

if [ "$1" = 0 ]; then
  %{_bindir}/xmlcatalog --noout --del \
   "file://%{_datadir}/publican/xsl/docbook4/" $CATALOG
Consolidate DataBase entries.
Add sort_order parameter.
Override the default sort weighting for books in a Publican website. Defaults to 50.
Books are displayed on the website in descending sort order. For example, a book with sort order 10 appears before a book with sort order 5. By default, this value is set to 50.
Fix para tag not getting newline in TXT output.
Rework toc style to fit long name products and books.
The TOC now wraps long product and book names.
Fix PO merge output order.
Fix new entires in merged PO being double escaped.
Fix false warning "Message missing from PO file".
Fix create_brand not copying images.
Fix rename requiring --name parameter.
Add rev_file and info_file parameters.
Publican now allows you to specify alternative revision history (rev_file) and info (info_file) files. For example, both revision history and info could be stored in the same file as the book's contents.
Both parameters use the full filename without a path.
Fix multiple actions not being caught.
Add jcarousel support.
Added support for using jcarousel to the web_style 2 welcome page.
To populate this content add a new file to your welcome page, en-US/Ads.xml, using the refentry format. For each refsection supply a title, subtitle, and literallayout. The text of title and subtitle are used in the Ad; literallayout is used to create a relative link on the site. You can customise the CSS for each Ad by specifing the role attribute on the refsection and then by adding the same class in the welocme page's site_overides.css. If you ship images in the welcome page's images directory you can then use them as backgroud images.

Example 3. Ads.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "" [
		<refpurpose>ADs for the home page</refpurpose>
	<refsection role="pub">
		<title>New in Publican&nbsp;3.0</title>
		<subtitle>Publican 3.0 has a shiny web interface!</subtitle>
	<refsection role="rpm">
		<title>Red Hat Package Manager&nbsp;4 Guide</title>
		<subtitle>Read all about RPM.</subtitle>