FOSS Docs Toolchain
Contents:
INTRODUCTION
 FOSS Docs the FOSS Way
|
| Although there are some fine, commercially available XML editors, the emphasis of this document is "FOSS docs the FOSS way". Just as FOSS developers have world-class FOSS interpreters/compilers and editors to write and interpret/compile code under FOSS licensing, FOSS documentation writers should have FOSS-licensed tools to create FOSS documentation. This is not an either/or (with us/against us) scenario. It's a matter of choice and freedom. Individuals and companies are free to choose a commercially-licensed package. They should also be free to choose a FOSS alternative. |
 Only Manual Procedure Described Initially
|
| This document examines how to manually produce FOSS docs using only FOSS tools. This is the first objective. Once the manual procedure is well-documented, it can then be scripted via a language like Python with a substantial portion of the procedure executed as server-side code. |
DESIGN ASSUMPTIONS
1. The documents are licensed under the Open Publication License (OPL) or compatible license.
1. Only FOSS tools with mutually compatible licenses are used in the tool chain.
1. Existing tools are used whenever possible.
1. Open standards, in file formats, data structures, communications protocols and programming interfaces, are used whenever possible.
1. New tools are designed to be modular and extensible.
1. 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.
1. Python is the preferred scripting tool.
1. The initial implementation is intended for Fedora Linux, but can easily be ported to other distributions, and even other operating systems platforms.
1. If packaged as a complete system, the resulting tool set is licensed under the GPL.
THE DOCUMENTATION WORKFLOW CYCLE
File:JohnBabich Sandbox Toolchain myworkflow-upd.png
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 DocBook 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, while Plone uses Subversion for its SCM.
- (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
1. Simple GUI ASCII Text Editors:
- gedit (GNOME)
- KEDIT (KDE)
- MousePad (xfce)
1. Sophisticated Macro CLI/GUI Editors:
- Emacs with PSGML and/or nXML mode addons
- Vim with xmledit script
1. GUI Editors with Plugins:
- gedit with Taglist Plugin
- KATE with XML Plugin
1. Advanced Markup GUI Editors:
- Bluefish (GNOME)
- IMView (GNOME)
- KXML (KDE)
1. WYSIWYG GUI Editors:
- Conglomerate (GNOME)
- Quanta Plus (KDE)
- Vex (JAVA Eclipse Platform)
1. Advanced Word Processors:
- OpenOffice.org Writer with OOo2DBK plugin
- KOffice KWord (DocBook SGML support, but no XML)
- AbiWord (limited DocBook import/export support)
OPTION 2: Online via Server-side Editor
1. Wiki-based Editors
- Built-in editor for MoinMoin Wiki
- Kupu Editor for Plone CMS Wiki
STAGE B: Editorial Review [2-Stage Document Processing]
- STAGE B1 - Input
- Wiki Markup Language (MoinMoin or equivalent)
- OpenOffice Document (*.odf or *.swx)
- STAGE B1 - Processing
- Convert input document into valid DocBook XML with DTD (Document Type Definition)
- STAGE B1 - Output / STAGE B2 - Input
- Valid DocBook XML
- Input to Stage C
- STAGE B2 - Processing
- Convert DocBook XML into final output format
- STAGE B2 - Output
- HTML
- Wiki Markup Language
- Input to Stage D
STAGE C: Persistent Storage [Check-in/Check-out]
- Doc
Book source is checked into SCM (CVS or Subversion) - Revision history is automatically updated
- Doc
Book 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 DocBook 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:
Stage A
The DocBook XML source module is checked out of CVS by a writer. The writer edits the document using the Emacs editor with PSGML and nXML mode addons. The writer thens checks the module back into CVS, requesting an editorial review.
Stage B
The editor checks out the revised document module, proofreading and validating the updated DocBook XML source.
Stage C
The editor checks the revised DocBook XML source module back into CVS and closes the Bugzilla tickets.
Stage D
The DocBook 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.