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. -- [email protected]
signature.asc
Description: PGP signature
_______________________________________________ xorg-devel mailing list [email protected] http://lists.x.org/mailman/listinfo/xorg-devel
