X.Org documentation formats, plans, conversions, etc.

[Keith Packard]

Excerpts from Alan Coopersmith's message of Tue Nov 10 21:40:32 -0800 2009:

> Peter has also made some arguments on IRC towards changing our official
> preferred format from DocBook to AsciiDoc, since the outputs are the same,
> but the creation is easier for developers and the raw docs in the source
> trees/git repos are easier to read.   I haven't worked with it yet, so
> can't comment on my experiences, though the arguments seem reasonable.
> Anyone else want to comment/vote?

I thought about this quite a bit when writing the Fontconfig
documentation. I ended up using sgml-based docbook for the big text
sections, but for individual functions, I really wanted the html and
pdf versions to include all of the functions in a single document
while the man pages would be per-function (as is the Unix convention).

The result was that the per-function documentation is written in a
brand new format which is used to generate individual files for the
troff -man format and chapters for the pdf and html formats. I would
have loved to have found a way to make the docbook tools do this for
me.

So, it seems to me that we should first decide if the API
documentation needs to be provided in the old per-function troff -man
format at all. Few other projects bother anymore; it's usually easier
to load one giant pdf/text/html file and search through that for me.

For application documentation and protocol specs, I'd agree that
AsciiDoc is a better choice than raw sgml; I've written my share of
sgml already and don't want to do that anymore. It's the difference
between writing raw html and editing a wiki page.

-- 
keith.packard at intel.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: not available
Url : http://lists.x.org/archives/xorg-devel/attachments/20091111/1a29f226/attachment.pgp