Publishing Documentation with Publican
Stephen Gordon (@sgordon_)Content Author, Red Hat
10th September 2013
Caffeine into Docbook XML!
Agenda
Introduction to Publican
Publican interaction with OpenStack manuals
Publican Tutorial
Publican Introduction
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.
Once upon a time in a galaxy far, far, away (2008).
One source, many output formats.
DocBook XML 4.5, DocBook XML 5 in > 3.0.
Common examples via pandoc include RST and AsciiDoc.
Man Page generation also possible.
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!).
Many dependencies (Perl universe!)
Publican itself lightweight.
Wkhtmltopdf added in 3.0.
Publican Features
Packaging (RPMs)
Customizable Branding
DocBook sets (stand-alone and distributed)
Site creation/management
i18n (POT/PO file generation)
I18n:
Generate POT file(s) and PO file(s) for each language.
Provide documentation builds based on PO files.
Typically integrated with Transifex or Zanata.
Who uses Publican (examples)?
Red Hathttp://access.redhat.com/site/documentation/
~ 2000 en-US documents, ~1000 translations (22 languages)
Fedorahttp://docs.fedoraproject.org
The Debian Administrator's
Handbookhttp://debian-handbook.info/
The most well known/obvious.
Who uses Publican (examples)?
Kolabhttp://docs.kolab.org/
Zarafa http://www.zarafa.com/doc
Lesser known examples.
Many individual and/or internal projects.
Image by Master isolated images, via freedigitalphotos.net (see
Acknowledgments slide).
What does this have to do with OpenStack manuals?
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.
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-convert/
http://files.iaccidentallyaword.com/openstack-user/
Like all great prototypes (?), written in Bash.
Uses XSL to perform transformations and rearranges directory
structure as required.
Conversion script a work in progress, automation gets 95% of the
way.
Publican and clouddocs-maven
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).
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.
Publican Tutorial
Image by Ausis, via openclipart.org (see Acknowledgments
slide).
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_Guide/
Tutorial - Create
Create a book:$ publican create --name My Test Book
See help for optional arguments:$ publican create --help
Tutorial - Create
$ cd My_Test_Book/
Tutorial - Create
Author_Group.xmlLists authors for a given guide.
Book_Info.xmlDocBook 4.5 element.
DocBook 5 element for .
Chapter.xmlExample chapter to get the writer started.
.entCommon entities for the guide.
Tutorial - Create
.xmlThe element, top of the XML tree.
Preface.xmlCommon Conventions
Feedback
Revision_History.xml element, can be maintained manually or
using `publican add_revision`
publican.cfgBuild and packaging directives, equivalent to
pom.xml.
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.
Tutorial - Create
See User Guide for more
detail:http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory
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/
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
Tutorial - Branding
See the user guide for more information on custom brands!
http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/chap-Users_Guide-Branding.html
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
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
Tutorial Create DocBook 5?
$ publican create --name My Test Book
$ cd My_Test_Book
$ vim publican.cfgAdd dtdver: 5.0
Change brand: common to brand: common-db5
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
Questions?
Stephen Gordon (@sgordon_)Content Author, Red Hat
10th September 2013
Slides available at:
http://www.slideshare.net/sgordon2/
Acknowledgments
Pencil and note pad stock image:By Ausis, via
openclipart.org:
http://openclipart.org/detail/1697/pencil-and-note-pad-by-ausis
Stressed Man among Question Marks stock image:By Master isolated
images, via freedigitalphotos.net:
http://www.freedigitalphotos.net/images/Ideas_and_Decision_M_g409-Stressed_Man_among_Question_Marks_p86141.html
Click to edit the title text format
Click to edit the outline text format
Click to edit the outline text formatSecond Outline LevelThird
Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline
LevelSeventh Outline LevelEighth Outline LevelNinth Outline
Level
