Release process for Xorg 7.1
josh at freedesktop.org
Thu Apr 27 14:59:36 PDT 2006
Egbert Eich wrote:
> Kevin E Martin writes:
> > For those who might not know, the decision to put all of the old docs
> > into a single package was made for primarily one reason: There was
> > discussion last year about converting the docs from the various old
> > formats to a modern format. Then, as each doc is converted, it could be
> > moved out of the docs package and put into a more appropriate package.
> > I'm not sure if/when that will happen, so if people would like to go
> > ahead and spread the old format docs out to the appropriate packages now
> > and then convert them to a modern format later, that's okay by me. I
> > just don't want to desire to convert the docs to a modern format to be
> > lost in the shuffle here.
> The doc conversion was a project advocated by JG.
> Unfortunately he had been rather busy lately so he
> he did not follow up on this.
> It would definitely make sense to move the docs
> to the individual packets when the format conversion
> is done.
> However currently there is nothing but a vague desire
> to do so at some point in time.
> Maybe there is somebody here who'd be interested in
> taking on this task to make a plan how the conversion
> should be performed,propose this plan and execute it.
> - There needs to be a consensus on the format to use.
> - We need to have a consensus what the target formats
> should be (I assume we need to be able to generate
> traditional man pages as well as specs in book form.)
> - Tools need to exist to convert to the desired target
> - Tools should exist to make doc writing easy.
> Maybe we can collect a few opinions here?
For the documentation of the X protocol and protocol extensions, the XCB
project has an open TODO item to integrate documentation into our XML X
protocol descriptions (either within each file or as separate files with
cross-references between the two), and then generate the documentation
from the protocol descriptions. This would ensure that the
documentation always agrees with the actual layout of requests,
responses, and structures; when writing many of those extension
descriptions in the first place, I discovered many cases where the
documentation did not agree with the code.
Such a project, as well as the conversion of the various other
documents, might make a good summer of code project for someone inclined
towards documentation and/or XML.
- Josh Triplett
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 252 bytes
Desc: OpenPGP digital signature
More information about the xorg