-
Notifications
You must be signed in to change notification settings - Fork 0
DocBook Production Notes
The Handbook is written in DocBook which is a markup language similar to HTML but for large structured documents. The Handbook was originally produced using OxygenXML, a commercial tool for document production, but is being reworked to use more generally available tools to allow potentially wider collaboration. This page is to organize some notes about how that might work and examples of what other projects are using.
The goal of the production process shall be:
- Produce a well-formatted PDF document for offline reading and possible printing with:
-
Table of contents, List of Figures, Index, Glossary and other tools.
-
Proper citations and bibliography
-
Internal references and bookmarks
-
External cross-references (URLs) clickable in PDF and viewable in printed.
-
Internal section numbering (e.g. 3-1, 3-2, 4-1) so that sections can be printed and organized by themselves.
-
Floats
- Produce a chunked (multiple HTML files), interlinked document for easy browsing, bookmarking, and search linking.
-
Should behave well on multiple devices
-
Should provide an easy pathway to e-book production (e.g. EPUB) and automatic re-flowable, re-fontable text.
-
HTML should preserve semantics of DocBook markup as much as possible, especially to enable screen-reader and other alternative navigation. In other words, a glossary link should be distinguishable from a citation link from an internal cross-reference from an external source link. Outline processors should be able to navigate the document structure with no hiccups (making it possible to use css/javascript to build mini-tocs, breadcrumbs, and other conveniences for the reader), and again, to enable easy e-book production.
-
All necessary processing to check out source and produce a document available with free tools.
-
May use commercial tools for value-added tasks or as options to free tools.
-
As much as possible, tracking of dependencies (e.g. obtaining appropriate style-sheet and XSLT processors), should be automated. An editor should not have to fiddle with which stylesheet or which version of a single tool in the production chain is needed for a particular version of the document; it should just happen.
-
Document production should work reasonably with a text-editor (or the built-in GIT tools) and a command-line but allow use of an XML-aware IDE (e.g. NetBeans) without too much trouble. Production shall not be tied to a specific editing environment or need to track IDE project files.
-
Editing of one chapter or section of the Handbook should be able to be isolated from the rest of the document as much as possible. In other words, someone working on editing local cottage industry material should not need to worry (much) about what someone in the community organization section is doing. That will require some basic conventions for glossary, cross-reference, bibliography components that everyone will affect as well as intelligent uses of version-control and branches in Git.
-
Some notes on an old NetBeans thread on DocBook production which talks about the process other projects use, some of which I wanted to dig through: https://netbeans.org/projects/platform/lists/dev/archive/2006-10/message/113 .
-
Apache Ant will generate HTML/PDF from DocBook and I have used it before. It has many of the tools necessary already built in. It is free, cross-platform, and would probably make sense as the backbone of the system. The Ant4DocBook Project focuses on DocBook production from Ant.