Device tree binding documentation

Device tree binding documentation

[Grant Likely]

I've been thinking a lot more about how to handle documenting new
bindings for the device tree and getting them up onto a web site of
some sort.  When this idea originally came up, my first impression was
to just throw up a wiki somewhere and make it available for everyone
to use.

But thinking about it more, it seems like a typical wiki wouldn't
really encourage a workflow suitable for hammering out new bindings.
For instance, before a new bindings is published as complete it needs
to be reviewed and agreed to by the development community, but a
typical wiki tends toward ad-hoc editing and continual
update/refinement of the text on-line.  If not careful, a wiki could
easily lead to unreviewed bindings being added or established bindings
getting modified in poorly designed or incompatible ways.  It could
also end up forcing everyone to do their bindings work from within a
web browser which isn't always the most efficient tool.  We would need
to come up with new processes for how to manage, review and approve
content on the wiki so that users can be confident that the
information on the web site is reliable.

It seems to me though that we *already* have a process for reviewing
and accepting changes to a large collective work.  We work together
every day on the Linux kernel and have established policies about how
to make changes.  What if we follow the Linux lead and depend on the
devicetree-discuss-mnsaURCQ41sdnm+yROfE0A@public.gmane.org and distributed revision control to
develop and maintain documentation of new bindings?

Here is my thought:
1. Set up a wiki site to publish the documentation.  Use something
like ikiwiki which uses git as the back end
2. Allow anyone to clone the backend repo
3. Binding authors would post patches to the devicetree-discuss
mailing list for all changes
4. Review/discussion/arguments would proceed in the normal way
5. Assign a few people to be binding maintainers
6. Binding maintainers pick up, commit, (and probably sign) changes
when there appears to be concensus
7. Picked up changes get pushed out to the wiki server which updates the pages

Also it would allow people to edit bindings on-line:
2b. Setup a 'working' site that uses a side branch in the repo.
2c. Allow edits in the side branch directly from the web page, but
still require the binding diff to be posted to the mailing list for
discussion before being merged into mainline.  The wiki software could
be modified to automate patch posting without having to resort to the
command line.

I'm going to experiment with ikiwiki a bit tomorrow to see if it is
workable.  I'd also appreciate any feedback on this.

Cheers,
g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

RE: Device tree binding documentation

[Yoder Stuart]

 

> -----Original Message-----
> From: 
> devicetree-discuss-bounces+stuart.yoder=freescale.com@ozlabs.o
> rg 
> [mailto:devicetree-discuss-bounces+stuart.yoder=freescale.com@
ozlabs.org] On Behalf Of Grant Likely
> Sent: Tuesday, October 28, 2008 1:23 AM
> To: devicetree-discuss list; Mitch Bradley; Matt Sealey; 
> Benjamin Herrenschmidt; Anton Vorontsov; Loeliger 
> Jon-LOELIGER; Kumar Gala; David Gibson; Hugh Blemings
> Subject: Device tree binding documentation
> 
> I've been thinking a lot more about how to handle documenting new
> bindings for the device tree and getting them up onto a web site of
> some sort.  When this idea originally came up, my first impression was
> to just throw up a wiki somewhere and make it available for everyone
> to use.
> 
> But thinking about it more, it seems like a typical wiki wouldn't
> really encourage a workflow suitable for hammering out new bindings.
> For instance, before a new bindings is published as complete it needs
> to be reviewed and agreed to by the development community, but a
> typical wiki tends toward ad-hoc editing and continual
> update/refinement of the text on-line.  If not careful, a wiki could
> easily lead to unreviewed bindings being added or established bindings
> getting modified in poorly designed or incompatible ways.  It could
> also end up forcing everyone to do their bindings work from within a
> web browser which isn't always the most efficient tool.  We would need
> to come up with new processes for how to manage, review and approve
> content on the wiki so that users can be confident that the
> information on the web site is reliable.
> 
> It seems to me though that we *already* have a process for reviewing
> and accepting changes to a large collective work.  We work together
> every day on the Linux kernel and have established policies about how
> to make changes.  What if we follow the Linux lead and depend on the
> devicetree-discuss-mnsaURCQ41sdnm+yROfE0A@public.gmane.org and distributed revision control to
> develop and maintain documentation of new bindings?
> 
> Here is my thought:
> 1. Set up a wiki site to publish the documentation.  Use something
> like ikiwiki which uses git as the back end
> 2. Allow anyone to clone the backend repo
> 3. Binding authors would post patches to the devicetree-discuss
> mailing list for all changes
> 4. Review/discussion/arguments would proceed in the normal way
> 5. Assign a few people to be binding maintainers
> 6. Binding maintainers pick up, commit, (and probably sign) changes
> when there appears to be concensus
> 7. Picked up changes get pushed out to the wiki server which 
> updates the pages
> 
> Also it would allow people to edit bindings on-line:
> 2b. Setup a 'working' site that uses a side branch in the repo.
> 2c. Allow edits in the side branch directly from the web page, but
> still require the binding diff to be posted to the mailing list for
> discussion before being merged into mainline.  The wiki software could
> be modified to automate patch posting without having to resort to the
> command line.
> 
> I'm going to experiment with ikiwiki a bit tomorrow to see if it is
> workable.  I'd also appreciate any feedback on this.

I like the general idea and have been thinking along the
same lines.  Here at Freescale I've set up an internal site
for some of our bindings in development.  The bindings themselves
are text files in a git repo.  Then we have a wiki that links
to them via git web.

The nice thing about the above approach is that you can clone
the git repo, grep through the text bindings, and use your
normal user space tools to look for things like how a
particular property is used and what bindings use it.  But
you also have the convenience of a web interface to get at
the bindings too.

So my vote is to maintain bindings as plain text files.

Some other thoughts:

   -you're going to have generic bindings (e.g. i2c, flash)
    and very specific company specific/proprietary bindings
    (e.g. Freescale security device) and so the structure 
    should accomodate this.   As far as maintainers go, it
    probably makes sense for a Freescale person to maintain
    the Freescale bindings.

   -I'd also like to see the wiki site be broader than just
    bindings and include other device tree related stuff-- e.g.
    documentation on DTC and libfdt.  It could include howtos
    on topics, and links to the ePAPR or any relevant 1275
    documents.

   -one question:  where would this be hosted?   I have been
    working with power.org on getting a wiki for essentially
    the same purpose you've been describing, but it's still
    not a done deal.   Other options would be IBM or 
    Freescale.  I'd like to see the bindings hosted somewhere
    where they have a fairly permanent home.

    If we put the bindings as text docs in a git repo we could
    separate the hosting of the git repo with that of the
    wiki.

Stuart

Re: Device tree binding documentation

[Matt Sealey]

Yoder Stuart wrote:
>  
> So my vote is to maintain bindings as plain text files.

Just like the real elections I don't actually have a vote here,
but can I put my oar in that after a certain review process and
time has passed and the binding stabilizes, these get published
as PDF documents similar to an AppNote or the ePAPR specification
so that you get the advantages of bookmarks, pagination,
formatting (notes, examples and warnings) and printing it in a
reasonable fashion on a dead tree as if it were a book?

Maintaining them as text for the development process is good but
they need to be *published* as the ePAPR binding is *published*,
so that you can say.. "hey, this is a canonical reference on a
dead tree, my platform confirms to the ePAPR MPC5200B device
tree binding V1.0 that I ordered from the Freescale website",
instead of "my platform conforms to git commit fab927fe363ac2a872bb872"

?

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

Re: Device tree binding documentation

[Scott Wood]

Matt Sealey wrote:
> Maintaining them as text for the development process is good but
> they need to be *published* as the ePAPR binding is *published*,
> so that you can say.. "hey, this is a canonical reference on a
> dead tree, my platform confirms to the ePAPR MPC5200B device
> tree binding V1.0 that I ordered from the Freescale website",
> instead of "my platform conforms to git commit fab927fe363ac2a872bb872"

The latter is actually much less subject to change... :-)

-Scott

Re: Device tree binding documentation

[Matt Sealey]

Scott Wood wrote:
> Matt Sealey wrote:
>> Maintaining them as text for the development process is good but
>> they need to be *published* as the ePAPR binding is *published*,
>> so that you can say.. "hey, this is a canonical reference on a
>> dead tree, my platform confirms to the ePAPR MPC5200B device
>> tree binding V1.0 that I ordered from the Freescale website",
>> instead of "my platform conforms to git commit fab927fe363ac2a872bb872"
> 
> The latter is actually much less subject to change... :-)

Right until the git repo is down and you don't have a copy as
reference :D

Basically it would solve all the nitpicking about how a device tree
wasn't right on a certain board (as long as it fit a certain spec,
drivers would be required to maintain compatibility with that spec)
and wouldn't get these weird effects when they change USB and decide
that they need to pare down the matchlists and break a working
board.

At least if you can refer to ePAPR right now, it's there for download
as a book-type spec for the basic elements, the same way you could with
OF, and the OF bindings were traditionally published in Postscript (and
written in tex? lord knows.. that's complicating documentation writing
but the symbol support and math support is far, far better than ASCII
art)

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

Re: Device tree binding documentation

[Grant Likely]

On Tue, Oct 28, 2008 at 10:58 AM, Matt Sealey <matt-sEEEE4iEDtaXzmuOJsdVMQ@public.gmane.org> wrote:
>
>
> Yoder Stuart wrote:
>>
>>  So my vote is to maintain bindings as plain text files.
>
> Just like the real elections I don't actually have a vote here,

If that were true you wouldn't have been in the 'to:' list.

> but can I put my oar in that after a certain review process and
> time has passed and the binding stabilizes, these get published
> as PDF documents similar to an AppNote or the ePAPR specification
> so that you get the advantages of bookmarks, pagination,
> formatting (notes, examples and warnings) and printing it in a
> reasonable fashion on a dead tree as if it were a book?

I think that is reasonable if it is something people find useful or
more accessible.

g.


-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: Device tree binding documentation

[Mitch Bradley]

> At least if you can refer to ePAPR right now, it's there for download
> as a book-type spec for the basic elements, the same way you could with
> OF, and the OF bindings were traditionally published in Postscript (and
> written in tex? lord knows..

Many, or perhaps even all, of them were written in Frame Maker, which 
had relatively good support for handling large documents compared to its 
then competitors.  The ANS Forth standard, which was being developed at 
the same time, was written in MS Word.

PDF hadn't really taken off at the time.

Re: Device tree binding documentation

[Matt Sealey]

Grant Likely wrote:
> On Tue, Oct 28, 2008 at 10:58 AM, Matt Sealey <matt-sEEEE4iEDtaXzmuOJsdVMQ@public.gmane.org> wrote:
>>
>> Yoder Stuart wrote:
>>>  So my vote is to maintain bindings as plain text files.
>> Just like the real elections I don't actually have a vote here,
> 
> If that were true you wouldn't have been in the 'to:' list.

I got an Obama campaign leaflet through the door the other day, too :)

>> but can I put my oar in that after a certain review process and
>> time has passed and the binding stabilizes, these get published
>> as PDF
> 
> I think that is reasonable if it is something people find useful or
> more accessible.

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?

For another time maybe. Continue on the discussion. I really like
the git repo/wiki idea. But I do not agree that a web browser is
inefficient; a wiki for editing changes (for registered users
assigned to a "project") in a collaborative way is probably far
better in some respects than using Kate and xdiff (certainly
less difficult in some other respects), if you want to quickly
look at changes or so, or make an update to a section.

If we didn't like web browsers that much then we wouldn't have
patchwork, for example, which is an insanely useful tool..
although the same care must be taken not to do what patchwork
just did and go through a lovely rewrite or software update
and suddenly lose years of patch reference URLs :D

I understand not wanting to have to keep a browser open to read
a forum instead of a mailing list, but this is something a
little different. Wouldn't collaboratively editing a wiki allow
multiple users to submit changes to a page (in "private"), yet
ultimately have a Responsible Person collect those changes into
a bundle and submit that as a patch to devicetree-discuss when
development is complete? Branching and checkouts in git would
work the same way but you wouldn't have to be sitting at your
desk (with git) to make a tiny update or collaborate with your
colleagues while out in the field or at a customer site.

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

Re: Device tree binding documentation

[Nate Case]

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.

-- 
Nate Case <ncase-AQeFf1F/bRxBDgjK7y7TUQ@public.gmane.org>

Re: Device tree binding documentation

[Matt Sealey]

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

Re: Device tree binding documentation

[Jon Loeliger]

On Wed, 2008-10-29 at 09:53 -0500, Matt Sealey wrote:
> 

> > 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

That's just flat not true.

I too recommend DocBook.

jdl

Re: Device tree binding documentation

[Jimi Xenidis]

On Nov 17, 2008, at 11:37 AM, Jon Loeliger wrote:

> On Wed, 2008-10-29 at 09:53 -0500, Matt Sealey wrote:
>>
>
>>> 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
>
> That's just flat not true.
>
> I too recommend DocBook.
>

second
-JX

> jdl
>
>
> _______________________________________________
> devicetree-discuss mailing list
> devicetree-discuss-mnsaURCQ41sdnm+yROfE0A@public.gmane.org
> https://ozlabs.org/mailman/listinfo/devicetree-discuss
>

Re: Device tree binding documentation

[Matt Sealey]

Jon Loeliger wrote:
> On Wed, 2008-10-29 at 09:53 -0500, Matt Sealey wrote:
> 
>>> 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
> 
> That's just flat not true.

Oh so documentation is now hand-editing XML files?

Joyous. It may as well be in LaTeX.

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

Re: Device tree binding documentation

[David Gibson]

On Mon, Nov 17, 2008 at 11:37:34AM -0600, Jon Loeliger wrote:
> On Wed, 2008-10-29 at 09:53 -0500, Matt Sealey wrote:
> > 
> 
> > > 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
> 
> That's just flat not true.
> 
> I too recommend DocBook.

Frankly, I think worrying about a "presentation" type format like
DocBook / TeX / whatever is premature.  Our immediate concern is just
getting the bindings down somewhere consistent, for which a wiki /
website is appropriate.  Bundling them up into a nice PDF publishable
book is a problem for another day.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson