[Xcb] Let's hash this out

[Jeremy Kolb]

Ian Osgood wrote:
> 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?  We still need a way to generate man pages and other
docs though.

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

Yeah... for docs and api.

> 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
>>
> 
> _______________________________________________
> Xcb mailing list
> Xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb