Towards The Manual

BrendaWang brenda_wang at openmoko.com
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 :

http://wiki.openmoko.org/wiki/Wiki_move_forward
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
> 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
>   




More information about the documentation mailing list