[Xcb] Let's hash this out

[Jamey Sharp]

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.

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

> > 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']".

> 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

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.

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

--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/20061031/daf045b8/attachment.pgp