[Xcb] generating protocol documentation
Jeremy A. Kolb
jkolb at brandeis.edu
Tue Jul 25 08:15:13 PDT 2006
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
More information about the Xcb
mailing list