[Xcb] XML -> Documentation

[Ian Osgood]

On Jul 26, 2006, at 7:11 AM, Jeremy A. Kolb wrote:

> Alp, Vincent and I have been chatting on IRC lately about generating
> protocol documentation from XML.  I think everyone agrees how cool it
> would be so I want to see if we can't get the ball rolling, maybe  
> generate
> a list of requirements and ideas for implementation such as what
> information is needed, appropriate XML schema, and the method to pull
> documentation out of the XML and generate what we need.
>
> Alp says that we may want to look into what dbus is doing.  It  
> looks like
> they are trying to solve the same problems.
>
> So as a preliminary I'd say we are looking at generating: man  
> pages, pdfs,
> html output all from the same source.
>
> 1. A tag to specify errors generated by specific requests.
> 2. Some <comment> like tag that will allow us to place text for each
> request/reply etc. and may work on fields as well.
> 3. Some type of <a> like tag so that we can potentially have hyper- 
> link
> like functionality in whatever documentation we generate.
> 4. Although not as urgent on the documentation side of things we  
> need to
> be able to handle versioning.
>
> Docbook has been suggested.
>
> What are everyone's thoughts?
>
> Jeremy

Yes.  Also, I think there are already bugs in Bugzilla requesting  
conversion to Docbook.

  This would be a big project, perhaps start a wiki page to outline  
the scope of it and track progress?

We should distinguish comments to be inserted in the generated source  
from documentation included in a manual.

I would think that most hyperlinks could be inferred, so that there  
would be a consistent linking style.

The solution should also take into account eventual translation of  
the documents into other languages.

Ian