Your SlideShare is downloading. ×
0
Publishing Documentation
with Publican
Stephen Gordon (@sgordon_)
Content Author, Red Hat
10th
September 2013
2
Agenda
● Introduction to Publican
● Publican interaction with OpenStack manuals
● Publican Tutorial
Publican Introduction
4
What is Publican?
● A single source publishing tool.
● https://fedorahosted.org/publican/
● Supports DocBook XML input (...
5
What is Publican?
● Written in Perl.
● Uses FOP or wkhtmltopdf for PDF generation.
● Packaged for Fedora, Debian, and Ub...
6
Publican Features
● Packaging (RPMs)
● Customizable Branding
● DocBook “sets” (stand-alone and distributed)
● Site creat...
7
Who uses Publican (examples)?
● Red Hat
● http://access.redhat.com/site/documentation/
● ~ 2000 en-US documents, ~1000 t...
8
9
10
11
Who uses Publican (examples)?
● Kolab
● http://docs.kolab.org/
● Zarafa
● http://www.zarafa.com/doc
12
Image by “Master isolated images”, via freedigitalphotos.net (see “Acknowledgments” slide).
13
OpenStack Documentation
● Provides a great environment for single sourcing:
● Active and diverse community of authors.
...
14
Using Publican with OpenStack manuals
● Conversion script allows OpenStack manuals to be
built with Publican (Work in p...
15
Using Publican with OpenStack manuals
● Allows single sourcing while maintaining ability to use
existing publication in...
16
Improved Tooling?
● Publican and clouddocs-maven largely share a
problem space. Opportunity to share
solutions/experien...
Publican Tutorial
Image by “Ausis”, via openclipart.org (see “Acknowledgments” slide).
18
Tutorial - Prerequisites
● Publican (> 3.0 recommended).
● Installation instructions:
● https://wiki.openstack.org/wiki...
19
Tutorial - Create
● Create a book:
● $ publican create --name “My Test Book”
● See help for optional arguments:
● $ pub...
20
Tutorial - Create
● $ cd My_Test_Book/
21
Tutorial - Create
● Author_Group.xml
● Lists authors for a given guide.
● Book_Info.xml
● DocBook 4.5 <bookinfo> elemen...
22
Tutorial - Create
● <Book_Name>.xml
● The <book> element, top of the XML tree.
● Preface.xml
● Common Conventions
● Fee...
23
Tutorial - Create
● en-US/images (default)
● Equivalent to src/figures, modifiable with img_dir.
● en-US/images/icon.sv...
24
Tutorial - Create
● See User Guide for more detail:
● http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users
25
Tutorial - Build
● Build a book:
● $ cd “My_Test_Book”
● $ publican build --formats=html,html-single,pdf,epub 
--langs=...
26
Tutorial - Branding
● Using a brand:
● Set brand in publican.cfg for each book.
● brand: common
● brand: fedora
● Etc.
...
27
Tutorial - Branding
● See the user guide for more information on custom
brands!
● http://jfearn.fedorapeople.org/en-US/...
28
Tutorial - i18n
● Generate pot file(s):
● $ publican update_pot
● Generate po file(s):
● $ publican update_po --langs=f...
29
Tutorial - i18n
● Once translation is complete PO files are synced back
into the guide.
● Document(s) are built:
● $ pu...
30
Tutorial – Create – DocBook 5?
● $ publican create --name “My Test Book”
● $ cd My_Test_Book
● $ vim publican.cfg
● Add...
31
Tutorial – Create – DocBook 5?
● for FILE in `find . -name '*.xml'`; do
● xsltproc /usr/share/publican/xsl/db4-upgrade....
Questions?
Stephen Gordon (@sgordon_)
Content Author, Red Hat
10th
September 2013
Slides available at:
http://www.slidesha...
33
Acknowledgments
● “Pencil and note pad” stock image:
● By “Ausis”, via openclipart.org:
● http://openclipart.org/detail...
Upcoming SlideShare
Loading in...5
×

Publican

5,704

Published on

A brief introduction to Publican for members of the OpenStack documentation community. Originally presented at the OpenStack documentation bootcamp on the 10th of September 2013

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
5,704
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • Caffeine into Docbook XML!
  • Once upon a time in a galaxy far, far, away (2008). One source, many output formats. DocBook XML 4.5, DocBook XML 5 in &gt; 3.0. Common examples via pandoc include RST and AsciiDoc. Man Page generation also possible.
  • Many dependencies (Perl universe!) Publican itself lightweight. Wkhtmltopdf added in 3.0.
  • 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.
  • The most well known/obvious.
  • Lesser known examples. Many individual and/or internal projects.
  • What does this have to do with OpenStack manuals?
  • Conversion script a work in progress, automation gets 95% of the way. Publican and clouddocs-maven
  • Transcript of "Publican"

    1. 1. Publishing Documentation with Publican Stephen Gordon (@sgordon_) Content Author, Red Hat 10th September 2013
    2. 2. 2 Agenda ● Introduction to Publican ● Publican interaction with OpenStack manuals ● Publican Tutorial
    3. 3. Publican Introduction
    4. 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. 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. 6 Publican Features ● Packaging (RPMs) ● Customizable Branding ● DocBook “sets” (stand-alone and distributed) ● Site creation/management ● i18n (POT/PO file generation)
    7. 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. 8
    9. 9. 9
    10. 10. 10
    11. 11. 11 Who uses Publican (examples)? ● Kolab ● http://docs.kolab.org/ ● Zarafa ● http://www.zarafa.com/doc
    12. 12. 12 Image by “Master isolated images”, via freedigitalphotos.net (see “Acknowledgments” slide).
    13. 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. 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. 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. 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. 17. Publican Tutorial Image by “Ausis”, via openclipart.org (see “Acknowledgments” slide).
    18. 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. 19 Tutorial - Create ● Create a book: ● $ publican create --name “My Test Book” ● See help for optional arguments: ● $ publican create --help
    20. 20. 20 Tutorial - Create ● $ cd My_Test_Book/
    21. 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. 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. 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. 24 Tutorial - Create ● See User Guide for more detail: ● http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users
    25. 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. 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. 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. 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. 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. 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. 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. 32. Questions? Stephen Gordon (@sgordon_) Content Author, Red Hat 10th September 2013 Slides available at: http://www.slideshare.net/sgordon2/
    33. 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
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×