[Xcb] generating protocol documentation

[Jeremy A. Kolb]

On Tue, 25 Jul 2006, Jamey Sharp wrote:

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

Yeah I think we should add an error field, even it doesn't do anything 
currently.

Along the same line: what other "non documentation" information do we 
need to include besides errors thrown that we do not currently specify?

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

Is this a 2.0 feature? I can't imagine getting the XML right at least 
would be that hard.  Hopefully there wouldn't be serious breakage.

Jeremy