Towards The Manual
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.
> 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 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