[Xcb] Let's hash this out

[Jeremy Kolb]

Jamey Sharp wrote:
> On Tue, Oct 31, 2006 at 09:14:30PM -0500, Jeremy Kolb wrote:
>> Ian Osgood wrote:
>>> On Oct 31, 2006, at 5:22 PM, Jeremy Kolb wrote:
>>>> Okay... documentation generation.
> 
> OK!
> 
>>>> Let's just hash it out on the list... because once we go with something
>>>> it will be harder to change later on and I'm itching to hack something
>>>> up and don't want to make any bad decisions that will be a pain to undo
>>>> later.
> 
> Josh has declared (possibly not in public, but declared nonetheless)
> that the protocol description XML is not frozen and is subject to
> change. It's certainly true that the more people use it, the harder it
> is to make changes, but I'm not too worried about that right now: the
> audience for the XML is currently very small and will probably remain
> that way for a while.
> 
> So try stuff, and we'll see what happens.
> 

Sweet.

>>>> 1. Doxygen:
>>>> We've already decided on doxygen... and I think that's a good choice
>>>> since we can make ps/pfd/latex/html/man.
> 
> We decided on Doxygen for the C-language headers. We didn't decide that
> Doxygen tags should go in the XML.
> 

I was assuming that they wouldn't, but if we want them we could
certainly go that route.

>>> Someone is finally tackling docbook generation for the legacy
>>> documentation. I'm tempted to wait and see how that effort is received
>>> before introducing our own incompatible documentation. But I'm not the
>>> one with itchy fingers.  :)
>> Who's doing that?
> 
> Looks like Eamon Walsh <ewalsh at tycho.nsa.gov> and David Nusinow
> <dnusinow at speakeasy.net> both started working on it independently;
> they've been discussing the project on the xorg list, under the
> less-than-obvious subject of "[Fwd: macros: Changes to 'master']".
> 

Ahh! I didn't bother to read those because the subject line wasn't that
interesting.  Maybe we should pool our resources or at least inquire?

>> We still need a way to generate man pages and other docs though.
> 
> There exist translators from DocBook to manual pages and many other
> formats (info pages, PDF, LaTeX, HTML, and others). See xmlto, for
> instance:
> 	http://cyberelk.net/tim/xmlto/
> 
> My preference, which I've stated before, is to put DocBook fragments
> into the XML, and then generate Doxygen tags if desired from that.
> 	http://lists.freedesktop.org/archives/xcb/2005-June/000862.html
> 

Jamey, can you give an example of what this would look like? I'm not
that familiar with docbook.

> But again, if you want to hardcode some Doxygen tags for now, that
> wouldn't be the end of the world. I just think you'll find it as easy to
> use basic DocBook tags and write a little XSLT to translate to Doxygen
> though.
> 
>>>> 2. XML markup:
>>>> For the later I'm thinking we could either have a "brief" tag or
>>>> attribute.  ...
>>> I like using tags rather than attributes for bulk text like this.
> 
> I agree.
> 
>>>> For the "paragraph" description or what you find in the pdfs we'd
>>>> probably need a "description" tag of some sort.  Or we could use the
>>>> same tag for everything and use it differently depending on the context.
> 
> I like the Doxygen javadoc-style auto-brief mode, where the first
> sentence of the long description is used as the brief description. That
> lets us avoid providing both.
> 

That still wouldn't get us past the individual fields in the requests
though.

>>>>  I've also been thinking about error tags and I think we need something
>>>> like:
>>>>
>>>> request...
>>>> <error name="blah" thrown-when="param size is larger than yo momma." />
>>>> or something like that.
> 
> That would certainly be a start. As I've said before, machine readable
> conditions would be even better, if they're possible.
> 
>>>> 3. Versioning.
>>>> We talked about this a long time ago and we're going to need to figure
>>>> this one out (especially with randr++ coming out soon).  Alp... what did
>>>> you encounter in your branch? Any ideas?
>>> For versioning, are you thinking that we would tag requests, fields,
>>> enums, items, structs, etc. with the major/minor versions when they were
>>> introduced/retired?
>> Yeah... for docs and api.
> 
> It seems like a good idea, though I still haven't figured out what the
> tags/attributes should look like. How much sophistication do we need?

Well... in dga (which i never released because it's so horribly broken
and nothing really uses it) they have a version 1 and 2 where almost
everything has undergone a name or wire change.  I've seen a few others
where fields have been added in the middle of requests etc.  So we need
at least a "first appearing", "last appearing in" etc and some way to
differentiate them in the code... I'm not sure of the best way to do that...

Jeremy

> 
> --Jamey
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb