- 1 FOSS Docs Toolchain
- 1.1 INTRODUCTION
- 1.2 DESIGN ASSUMPTIONS
- 1.3 THE DOCUMENTATION WORKFLOW CYCLE
- 1.4 STAGE A: Distributive Editing [Create/Edit Document]
- 1.5 STAGE B: Editorial Review [2-Stage Document Processing]
- 1.6 STAGE C: Persistent Storage [Check-in/Check-out]
- 1.7 STAGE D: Static Content [Display/Publish/Print]
- 1.8 A Real-world Example
FOSS Docs Toolchain
- The documents are licensed under the Open Publication License (OPL) or compatible license.
- Only FOSS tools with mutually compatible licenses are used in the tool chain.
- Existing tools are used whenever possible.
- Open standards, in file formats, data structures, communications protocols and programming interfaces, are used whenever possible.
- New tools are designed to be modular and extensible.
- The resulting process is flexible enough to be performed manually or programmatically, run from the CLI or the GUI, on the client side or on the server side, and allows for choice of favorite editor, SCM and other tools.
- Python is the preferred scripting tool.
- The initial implementation is intended for Fedora Linux, but can easily be ported to other distributions, and even other operating systems platforms.
- If packaged as a complete system, the resulting tool set is licensed under the GPL.
THE DOCUMENTATION WORKFLOW CYCLE
The four stages in the Documentation Workflow Cycle (Patent Pending - Not!) are:
(A) Distributive editing, where writer edits documentation online wiki-style or offline with tagline-capable editor. The writer gets task assignments through Bugzilla. Material edited offline is reposted to the wiki for review and/or further revision by team members.
(B) Editorial review, wiki content reviewed by editors, before it is checked into CVS. Editorial functions include document version tracking, selection of best material from multiple versions, spell checking, and conversion of text to Doc
Book for storage in CVS. Note that Doc
Book conversion may be done manually or automatically.
(C) Persistent storage, edited Doc
Book document is checked into the version control system, along with its revision history. Source Control Management (SCM) can be performed using a variety of packages. The Fedora Project currently uses CVS.
(D) Static content, posted on website, generated automatically from CVS or equivalent version control system. This function would be enhanced by Plone in our scenario.
What follows is a preliminary outline of the steps within each stage.
STAGE A: Distributive Editing [Create/Edit Document]
First of all, there are two major options in editing the document.
OPTION 1: Offline via Client-side Editor
Simple GUI ASCII Text Editors:
- gedit (GNOME)
- KEDIT (KDE)
- MousePad (xfce)
Sophisticated Macro CLI/GUI Editors:
- Emacs with PSGML and/or nXML mode addons
- Vim with xmledit script
- GUI Editors with Plugins:
- gedit with Taglist Plugin
- KATE with XML Plugin
Advanced Markup GUI Editors:
- Bluefish (GNOME)
- IMView (GNOME)
- KXML (KDE)
WYSIWYG GUI Editors:
- Conglomerate (GNOME)
- Quanta Plus (KDE)
- Vex (JAVA Eclipse Platform)
Advanced Word Processors:
- OpenOffice.org Writer (export as DocBook)
- KOffice KWord (DocBook SGML support, but no XML)
- AbiWord (limited DocBook import/export support)
OPTION 2: Online via Server-side Editor
- Built-in editor for MediaWiki
- External editor such as It's All Text! add-on for Mozilla FireFox browser
STAGE B: Editorial Review [2-Stage Document Processing]
STAGE B1 - Input
- Wiki Markup Language (WML)
- OpenOffice Document (*.odf or *.swx)
STAGE B1 - Processing
- Convert input document into valid Doc
Book XML with DTD (Document Type Definition)
STAGE B1 - Output / STAGE B2 - Input
- Valid Doc
- Input to Stage C
STAGE B2 - Processing
- Convert Doc
Book XML into final output format
STAGE B2 - Output
- Wiki Markup Language
Input to Stage D
STAGE C: Persistent Storage [Check-in/Check-out]
Book source is checked into the SCM
- Revision history is automatically updated
- DocBook XML source is now available for editing/distribution/adaptation/publishing
STAGE D: Static Content [Display/Publish/Print]
- Wiki content is updated
- PDF is made available for download from website
- HTML source is generated for website
- Other formats are generated as needed
A Real-world Example
This scenario mirrors the procedure for updating source code in a program.
An existing document is published as a series of HTML web pages on a web site. It also is available for downloading as a PDF document. The original source is stored in Doc
Book XML format in CVS. Several "bugs" are filed against the document in Bugzilla, requiring it to be updated/corrected.
|Stages are not Strictly Sequential|
|This example illustrates that stages are not strictly sequential - for example, persistent storage (Stage C) is accessed several times throughout the process.|
The following sequence of events (or workflow) occurs:
Book XML source module is checked out of the SCM by the writer. The writer edits the document using the Emacs editor with PSGML and nXML mode addons. The writer then checks the module back into the SCM, requesting an editorial review.
The editor checks out the revised document module, proofreading and validating the updated Doc
Book XML source.
The editor checks the revised Doc
Book XML source module back into the SCM and closes any relevant Bugzilla tickets.
Book XML source is converted into valid HTML and is posted on the website as a set of web pages, complete with table of contents and an index. An updated PDF file is also generated and posted to the website for downloading.