[Xcb] Let's hash this out

[Ian Osgood]

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

I like using tags rather than attributes for bulk text like this.

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?

Ian

On Oct 31, 2006, at 5:22 PM, Jeremy Kolb wrote:

> Okay... documentation generation.
>
> 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.  Since XCB is sort of a clean slate as far as documenting  
> the X11
> protocol we need to do this as best we can.
>
> 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.  Can we have different  
> formats
> for various output options?  So one for man pages and let's say  
> another
> format for pdf files?
>
> 2. XML markup:
> At the very minimum we need to figure out the best way to describe a
> request/reply in paragraph form and comment individual fields for
> clarity and man pages.  For the later I'm thinking we could either  
> have
> a "brief" tag or attribute.  I'm leaning towards attribute but would a
> tag be better? I don't really know how it would make a difference for
> generation.  So we would have either:
>
> <request name="MakeCurrent" opcode="5" brief="Makes a GLX context  
> current.">
> 	<field type="glx:DRAWABLE" name="drawable" brief="The drawable
> associated with the context." />
> 	<field type="glx:CONTEXT" name="context" brief="The context to make
> current." />
> 	<field type="CONTEXT_TAG" name="old_context_tag" brief="the old  
> context
> tag" />
> 	<reply>
> 		<pad bytes="1" />
> 		<field type="CONTEXT_TAG" name="context_tag" brief="the context tag.
> I don't remrember what this does."/>
> 		<pad bytes="20" />
> 	</reply>
> </request>
>
> Or
>
> <request name="MakeCurrent" opcode="5" />
> 	<brief>Makes a GLX context current</brief>
> 	<field type="glx:DRAWABLE" name="drawable">
> 	  <brief>The drawable associated with the context."</brief>
> 	</field>
> 	<field type="glx:CONTEXT" name="context">
> 	  <brief>The context to make current.</brief>
> 	</field>
> 	<field type="CONTEXT_TAG" name="old_context_tag">
> 	  <brief>The old context tag"</brief>
> 	</field>
> 	<reply>
> 		<pad bytes="1" />
> 		<field type="CONTEXT_TAG" name="context_tag">
> 		  <brief>the context tag.  I don't remrember what this does</brief>
> 		</field>
> 		<pad bytes="20" />
> 	</reply>
> </request>
>
> The brief tag/attribute would also apply to everything else (errors,
> fields, enums etc.)
>
> 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'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.
>
> 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?
>
> Okay, I'm done.  Discuss.
>
> Jeremy
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>