[Xcb] generating protocol documentation

[Jamey Sharp]

On Tue, Jul 25, 2006 at 07:11:39AM -0400, Jeremy Kolb wrote:
> Is there currently any work being done on this?

No. Andy Howe did a prototype years ago when we were still using M4, but
as far as I know he never showed it to anybody. However, there's nothing
blocking a mostly-complete implementation of the concept: somebody just
has to do it.

> What are the requirements?  Are we looking for something that could
> generate HTML/man/pdf with links running throughout?  Or something
> less complicated?

I'd be inclined to generate DocBook, which has existing tools to convert
to HTML/man/pdf, and gives us a well-defined XML-based markup language
to embed in XCB's protocol descriptions for the human-readable parts.

I've always expected that whenever we get around to implementing this,
we'll discover that we need to change the descriptions of the protocol a
bit to cover the information that's currently in the documentation. For
example, we may add tags that declare which errors each request is
capable of returning. An initial prototype shouldn't need any changes
but the longer-term project involves identifying what changes would be
helpful.

I also always hoped we could generate documentation close enough to the
current handwritten troff source, or whatever it is, that we could diff
them reasonably; but that may be asking too much.

> Are we basically going to copy and paste from the existing proto docs
> and then essentially regenerate them?

I think so. Other suggestions would be welcome but I have no idea what
else we might do.

--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20060725/6271a344/attachment.pgp