Towards The Manual

[Minh Ha Duong]

Hi all,

  I can't help but think at night about how I would setup a project to make 
the missing Neo FreeRunner manual. So here it is.

Overview:

1. Fetch Wiki  pages   or   Source code
2. Convert them to articles in DocBook XML source
3. Generate any output necessary (html, PDF, paper...)

Step 3. is kind of trivial, once the source code of the manual is XML files in 
the docbook format. Docbook seems a good idea because
. It is probably _the_ open standard precisely designed for this
. It is mature and well supported
. I want to go with O'Reilly to publish the book ultimately
http://www.docbook.org/tdg/en/html/docbook.html

There would be a dedicated (virtual) server to do the builds, notify failures, 
publish the result etc... See http://svnbook.red-bean.com/ for example.

The files would be hosted as a project at  git.openmoko.org  of course.
There would be three branches:
. One branch that do continuous integration, rebuild everything every 15 
minutes from scratch
. One branch that updates from the previous one automatically, provided the 
build worked (i.e. smoketest rule: update a chapter iff it is not empty)
. One branch that is updated from the previous one manually

For Step 1 and 2, there would be three workflows.

Workflow A is from wiki to docbook. The mediawiki server exposes the content 
as XML, so it is a relatively simple. Wget the page, the XLSTing it into an 
article. There are probably already plenty of tools to do this.

Workflow B is from OpenOffice to docbook. For original material not in the 
wiki. There are export filters.

Workflow C is from source code to docbook. It is necessary go discuss with 
freesmartphone.org hackers to know how they want to document the 
the "Framework" section of the book. Python source files can include 
structured documentation strings, and there are tools to generate the doc 
automatically by separating the Python from the comments. There are filters 
to convert reStructureText, Python's markup format, to docbook.

What do you think ?

Minh