From Fedora Project Wiki
m (1 revision(s))
m (just SCM)
 
(8 intermediate revisions by the same user not shown)
Line 4: Line 4:


'''Contents:'''
'''Contents:'''


--------
--------
Line 26: Line 25:
== DESIGN ASSUMPTIONS ==
== DESIGN ASSUMPTIONS ==


1. The documents are licensed under the Open Publication License (OPL) or compatible license.
* 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.
* Only FOSS tools with mutually compatible licenses are used in the tool chain.


1. Existing tools are used whenever possible.
* Existing tools are used whenever possible.


1. Open standards, in file formats, data structures, communications protocols and programming interfaces, are used whenever possible.
* 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.
* 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.
* 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.
* 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.
* 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.
* If packaged as a complete system, the resulting tool set is licensed under the GPL.


== THE DOCUMENTATION WORKFLOW CYCLE ==
== THE DOCUMENTATION WORKFLOW CYCLE ==


[[Image:JohnBabich_Sandbox_Toolchain_myworkflow-upd.png]]
[[Image:JohnBabich_Sandbox_Toolchain_myworkflow-upd_med.png]]


The four stages in the Documentation Workflow Cycle (Patent Pending - Not!) are:
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.
'''(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<code></code>Book for storage in CVS. Note that Doc<code></code>Book conversion may be done manually or automatically.
'''(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<code></code>Book for storage in CVS. Note that Doc<code></code>Book conversion may be done manually or automatically.


* ''' (C) Persistent storage''', edited Doc<code></code>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.
'''(C) Persistent storage''', edited Doc<code></code>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.
'''(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.
What follows is a preliminary outline of the steps within each stage.
Line 63: Line 62:


First of all, there are two major options in editing the document.
First of all, there are two major options in editing the document.


=== OPTION 1: Offline via Client-side Editor ===
=== OPTION 1: Offline via Client-side Editor ===


1. Simple GUI ASCII Text Editors:
=== Simple GUI ASCII Text Editors: ===
 
- gedit (GNOME)
 
- KEDIT (KDE)
 
- Mouse<code></code>Pad (xfce)
 
1. Sophisticated Macro CLI/GUI Editors:


- Emacs with PSGML and/or nXML mode addons
* gedit (GNOME)


- Vim with xmledit script
* KEDIT (KDE)


* MousePad (xfce)


1. GUI Editors with Plugins:
=== Sophisticated Macro CLI/GUI Editors: ===


- gedit with Taglist Plugin
* Emacs with PSGML and/or nXML mode addons


- KATE with XML Plugin
* Vim with xmledit script


* GUI Editors with Plugins:


1. Advanced Markup GUI Editors:
* gedit with Taglist Plugin


- Bluefish (GNOME)
* KATE with XML Plugin


- IMView (GNOME)
=== Advanced Markup GUI Editors: ===


- KXML (KDE)
* Bluefish (GNOME)


* IMView (GNOME)


1. WYSIWYG GUI Editors:
* KXML (KDE)


- Conglomerate (GNOME)
=== WYSIWYG GUI Editors: ===


- Quanta Plus (KDE)
* Conglomerate (GNOME)


- Vex (JAVA Eclipse Platform)
* Quanta Plus (KDE)


* Vex (JAVA Eclipse Platform)


1. Advanced Word Processors:
=== Advanced Word Processors: ===


- Open<code></code>Office.org Writer with OOo2DBK plugin
* OpenOffice.org Writer (export as DocBook)


- KOffice KWord (Doc<code></code>Book SGML support, but no XML)
* KOffice KWord (DocBook SGML support, but no XML)


- Abi<code></code>Word (limited Doc<code></code>Book import/export support)
* AbiWord (limited DocBook import/export support)


=== OPTION 2: Online via Server-side Editor ===
=== OPTION 2: Online via Server-side Editor ===


1. Wiki-based Editors
=== Wiki-based Editors ===


- Built-in editor for Moin<code></code>Moin Wiki
* Built-in editor for MediaWiki


- Kupu Editor for Plone CMS Wiki
* External editor such as [https://addons.mozilla.org/en-US/firefox/addon/4125 It's All Text!] add-on for Mozilla FireFox browser


== STAGE B: Editorial Review [2-Stage Document Processing]  ==
== STAGE B: Editorial Review [2-Stage Document Processing]  ==


=== STAGE B1 - Input ===


* STAGE B1 - Input
* Wiki Markup Language (WML)
 
- Wiki Markup Language (Moin<code></code>Moin or equivalent)


- Open<code></code>Office Document (*.odf or *.swx)
* OpenOffice Document (*.odf or *.swx)


----
----


* STAGE B1 - Processing
=== STAGE B1 - Processing ===
 


- Convert input document into valid Doc<code></code>Book XML with DTD (Document Type Definition)
* Convert input document into valid Doc<code></code>Book XML with DTD (Document Type Definition)


----
----


* STAGE B1 - Output / STAGE B2 - Input
=== STAGE B1 - Output / STAGE B2 - Input ===


- Valid Doc<code></code>Book XML
* Valid Doc<code></code>Book XML


- Input to Stage C
* Input to Stage C


----
----


* STAGE B2 - Processing
=== STAGE B2 - Processing ===


- Convert Doc<code></code>Book XML into final output format
* Convert Doc<code></code>Book XML into final output format


----
----


* STAGE B2 - Output
=== STAGE B2 - Output ===


- HTML
* HTML


- PDF
* PDF


- Wiki Markup Language
* Wiki Markup Language


- Input to Stage D
=== Input to Stage D ===


----
----
Line 168: Line 162:
== STAGE C: Persistent Storage [Check-in/Check-out]  ==
== STAGE C: Persistent Storage [Check-in/Check-out]  ==


* Doc<code></code>Book source is checked into SCM (CVS or Subversion)
* Doc<code></code>Book source is checked into the SCM  
* Revision history is automatically updated
* Revision history is automatically updated
* Doc<code></code>Book XML source is now available for editing/distribution/adaptation/publishing
* DocBook XML source is now available for editing/distribution/adaptation/publishing


== STAGE D: Static Content [Display/Publish/Print]  ==
== STAGE D: Static Content [Display/Publish/Print]  ==
Line 196: Line 190:
=== Stage A ===
=== Stage A ===


The Doc<code></code>Book 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.
The Doc<code></code>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.


=== Stage B ===
=== Stage B ===
Line 204: Line 198:
=== Stage C ===
=== Stage C ===


The editor checks the revised Doc<code></code>Book XML source module back into CVS and closes the Bugzilla tickets.
The editor checks the revised Doc<code></code>Book XML source module back into the SCM and closes any relevant Bugzilla tickets.


=== Stage D ===
=== Stage D ===

Latest revision as of 22:54, 25 June 2009

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

  • 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 DocBook for storage in CVS. Note that DocBook conversion may be done manually or automatically.

(C) Persistent storage, edited DocBook 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

Wiki-based Editors

  • 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 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
  • PDF
  • Wiki Markup Language

Input to Stage D


STAGE C: Persistent Storage [Check-in/Check-out]

  • DocBook 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 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 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.

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 the SCM and closes any relevant 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.


Previous Page