1. “M” is for Manual: Open Source Tools for Documentation
Paul W. Frields Fedora Project Leader – Red Hat, Inc.
This presentation is made available under a Creative Commons Attribution-ShareAlike (BY-SA) 3.0 license.

2. About...

3. Outline What is DocBook? Best practices Documentation toolkits
Publican

4. What is DocBook?

5. GEEKSPEAK

6. XML spec for technical docs

7. HUMANSPEAK

8. Markup language for creating books, articles, etc.

9. Sample DocBook <book>
<title>How to write a book</title>
<bookinfo>
<author>
<firstname>Johnny</firstname>
<surname>Author</surname>
</author>
</bookinfo>
<chapter>
<title>Chapter the First</title>
<para>Let's begin with a story! Once upon a time in
Portland, there was a great conference...</para>
</chapter>
</book>

10. Why DocBook?

11. Plain text for easy revision control

12. Human-readable tags

13. Separates content from presentation

14. XML transformation: LaTeX, HTML, PDF, *wiki, etc.

15. Which tags to use

16. RTFM (kidding!): http://www.docbook.org/tdg/

17. Use an XML-aware editor

18. Free XML editors Emacs (with nXML mode) XMLmind Personal edition Vim
Syntext Serna Free
XMLBuddy for Eclipse

19. Best practice: XInclude

20. Remix your book!

21. Best practice: Entities

22. OK, I learned DocBook. Now what?

23. Validate it: xmllint

24. Transform it: xsltproc

25. Included stylesheets:
HTML
XHTML
XHTML 1.1
HTML Help
Java Help
Epub
Man pages
FO (use FOP►PDF)

26. Clean it up: xmltidy

27. Toolchains: Make it simple

28. Translation: gettext and Transifex

29. Introducing Publican...

30. Publican Toolchain for creating and using DocBook
Another Red Hat contribution to the open source community
Makes it very simple to create HTML and PDF output from your DocBook text
Fedora is using Publican for official docs
Let's see a demo!

31. Revision control!

32. Paul W. Frields pfrields@fedoraproject.org pfrields@redhat.com
Questions?