The document introduces Publican, a single-source publishing tool primarily used for document creation by organizations like Red Hat and Fedora, supporting a variety of output formats including HTML and PDF. It emphasizes Publican's interaction with OpenStack manuals and outlines its features, including customizable branding and internationalization support. The document also provides a tutorial for creating and building documents using Publican, along with guidelines for using it with Docbook 5.

1. Publishing Documentation
with Publican
Stephen Gordon (@sgordon_)
Content Author, Red Hat
10th
September 2013

2. 2
Agenda
● Introduction to Publican
● Publican interaction with OpenStack manuals
● Publican Tutorial

3. Publican Introduction

4. 4
What is Publican?
● A single source publishing tool.
● https://fedorahosted.org/publican/
● Supports DocBook XML input (others via pandoc).
● DocBook 5 support a work in progress, experimentally
provided in Publican > 3.0.
● Generates HTML, HTML-SINGLE, PDF, EPUB, TXT,
Man, and WebHelp output.

5. 5
What is Publican?
● Written in Perl.
● Uses FOP or wkhtmltopdf for PDF generation.
● Packaged for Fedora, Debian, and Ubuntu.
● Known to work on OS/X, Windows and OpenSuSE
12.1+ (see User Guide for details!).

6. 6
Publican Features
● Packaging (RPMs)
● Customizable Branding
● DocBook “sets” (stand-alone and distributed)
● Site creation/management
● i18n (POT/PO file generation)

7. 7
Who uses Publican (examples)?
● Red Hat
● http://access.redhat.com/site/documentation/
● ~ 2000 en-US documents, ~1000 translations (22
languages)
● Fedora
● http://docs.fedoraproject.org
● The Debian Administrator's Handbook
● http://debian-handbook.info/

8. 8

9. 9

10. 10

11. 11
Who uses Publican (examples)?
● Kolab
● http://docs.kolab.org/
● Zarafa
● http://www.zarafa.com/doc

12. 12
Image by “Master isolated images”, via freedigitalphotos.net (see “Acknowledgments” slide).

13. 13
OpenStack Documentation
● Provides a great environment for single sourcing:
● Active and diverse community of authors.
● Supported format (DocBook).
● Many distribution neutral topics for collaboration.
● Provides a “living” test case for DocBook 5 support in
Publican.

14. 14
Using Publican with OpenStack manuals
● Conversion script allows OpenStack manuals to be
built with Publican (Work in progress!):
● https://github.com/redhat-openstack/openstack-manuals-con
● http://files.iaccidentallyaword.com/openstack-user/
● Like all great prototypes (?), written in Bash.
● Uses XSL to perform transformations and rearranges
directory structure as required.

15. 15
Using Publican with OpenStack manuals
● Allows single sourcing while maintaining ability to use
existing publication infrastructure.
● Drives improvement of tooling (both Publican and
clouddocs-maven).

16. 16
Improved Tooling?
● Publican and clouddocs-maven largely share a
problem space. Opportunity to share
solutions/experiences.
● Many changes in Publican 3.2 as a direct result of this
work.
● Better DocBook 5 support.
● Better support for custom directory structures.

17. Publican Tutorial
Image by “Ausis”, via openclipart.org (see “Acknowledgments” slide).

18. 18
Tutorial - Prerequisites
● Publican (> 3.0 recommended).
● Installation instructions:
● https://wiki.openstack.org/wiki/Docs_Bootcamp_2013
● http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users

19. 19
Tutorial - Create
● Create a book:
● $ publican create --name “My Test Book”
● See help for optional arguments:
● $ publican create --help

20. 20
Tutorial - Create
● $ cd My_Test_Book/

21. 21
Tutorial - Create
● Author_Group.xml
● Lists authors for a given guide.
● Book_Info.xml
● DocBook 4.5 <bookinfo> element.
● DocBook 5 <info> element for <book>.
● Chapter.xml
● Example chapter to get the writer started.
● <Book_Name>.ent
● Common entities for the guide.

22. 22
Tutorial - Create
● <Book_Name>.xml
● The <book> element, top of the XML tree.
● Preface.xml
● Common Conventions
● Feedback
● Revision_History.xml
● <revhistory> element, can be maintained manually or
using `publican add_revision`
● publican.cfg
● Build and packaging directives, equivalent to pom.xml.

23. 23
Tutorial - Create
● en-US/images (default)
● Equivalent to src/figures, modifiable with img_dir.
● en-US/images/icon.svg taken from brand by default.
● en-US/extras (optional)
● Equivalent to src/samples, modifiable with extras_dir.
● en-US/files (optional)
● Equivalent to ...?
● Used for multimedia or other additional material that the
author wants included in the resultant RPM.

24. 24
Tutorial - Create
● See User Guide for more detail:
● http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users

25. 25
Tutorial - Build
● Build a book:
● $ cd “My_Test_Book”
● $ publican build --formats=html,html-single,pdf,epub
--langs=en-US
● Commonly used parameters/values can be stored in
~/.publican.cfg.
● langs: en-US
● formats: “html,html-single,pdf,epub”
● Output in ./tmp/en-US/<format>

26. 26
Tutorial - Branding
● Using a brand:
● Set brand in publican.cfg for each book.
● brand: common
● brand: fedora
● Etc.
● Creating a brand:
● $ publican create_brand --name “My Test Brand”
--lang en-US

27. 27
Tutorial - Branding
● See the user guide for more information on custom
brands!
● http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Use

28. 28
Tutorial - i18n
● Generate pot file(s):
● $ publican update_pot
● Generate po file(s):
● $ publican update_po --langs=fr-FR,de-DE
● Translation typically performed in Transifex or Zanata

29. 29
Tutorial - i18n
● Once translation is complete PO files are synced back
into the guide.
● Document(s) are built:
● $ publican build --langs=fr-FR,de-DE
--formats=html,html-single,pdf,epub

30. 30
Tutorial – Create – DocBook 5?
● $ publican create --name “My Test Book”
● $ cd My_Test_Book
● $ vim publican.cfg
● Add “dtdver: 5.0”
● Change “brand: common” to “brand: common-db5”

31. 31
Tutorial – Create – DocBook 5?
● for FILE in `find . -name '*.xml'`; do
● xsltproc /usr/share/publican/xsl/db4-upgrade.xsl ${FILE}
> ${FILE}.new && mv ${FILE}.new ${FILE};
● done

32. Questions?
Stephen Gordon (@sgordon_)
Content Author, Red Hat
10th
September 2013
Slides available at:
http://www.slideshare.net/sgordon2/

33. 33
Acknowledgments
● “Pencil and note pad” stock image:
● By “Ausis”, via openclipart.org:
● http://openclipart.org/detail/1697/pencil-and-note-pad-by-aus
● “Stressed Man among Question Marks” stock image:
● By “Master isolated images”, via freedigitalphotos.net:
● http://www.freedigitalphotos.net/images/Ideas_and_Decision