Towards The Manual
Minh Ha Duong
haduong at centre-cired.fr
Thu Dec 18 13:54:09 CET 2008
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.
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
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 ?
More information about the documentation