Release process for Xorg 7.1

[Josh Triplett]

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
>   formats.
> - 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...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
URL: <http://lists.x.org/archives/xorg/attachments/20060427/0809e3d9/attachment.pgp>