Re: Device tree binding documentation

[Matt Sealey <matt-sEEEE4iEDtaXzmuOJsdVMQ@public.gmane.org>]

Nate Case wrote:
> On Tue, 2008-10-28 at 14:39 -0500, Matt Sealey wrote:
>> I guess we would need to decide how those documents are published
>> without using proprietary software, then, and easily committed to
>> another git repository (or the same one just in a published form).
>> I don't suppose office xml is a good choice? It should be flexible
>> enough and similar enough that sections and layout do not change a
>> great deal, and git can easily produce diffs?
> 
> I would suggest using DocBook if publishing PDFs is a goal.  It would
> also let you output text and HTML as an added bonus.

The problem then is you can't edit the document outside of a special
DocBook editor (not that there is one, which means you're stuck
throwing XML around).

The goal isn't to abstract the documentation and bindings so we can
extract them as different types for different means, but to take what
is in a wiki or a text document in git and purposefully organize it
for later publishing. I wouldn't want to have the official ratified
binding just generated from the DocBook source of some version, DocBook
doesn't have the pizazz and features required.. or a GUI editor worth
a shit.

I've vote for anything OpenOffice can throw out. I guess if we're
talking about taking the .txt binding and making a PDF out of it,
the software used need only be usable by everyone involved, and it
(any output such as PDF or Word or ODT) may as well be treated as
a binary blob in the git tree (and would not be updated, as an
official errata would be published, and then a new version, and
let's not rely on git to make sure people can get the old version!).

-- 
Matt Sealey <matt-sEEEE4iEDtaXzmuOJsdVMQ@public.gmane.org>
Genesi, Manager, Developer Relations