Towards The Manual

BrendaWang brenda_wang at
Fri Dec 19 07:50:59 CET 2008

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

I had made this :
And now I am working on it.

How about we start with this page.
Enrich it. And construct it.

> 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 for example.
> The files would be hosted as a project at  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 
> 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

More information about the documentation mailing list