On 03/16/2011 06:50 PM, Peter Hutterer wrote:
On Wed, Mar 16, 2011 at 03:29:09AM -0600, Matt Dew wrote:
On 03/15/2011 07:01 PM, Gaetan Nadon wrote:
On Wed, 2011-03-16 at 09:12 +1000, Peter Hutterer wrote:
asciidoc also converts to docbook. so while there would be some
inconsistency, it wouldn't be that bad.
I thought about that. The strategy would that before it matures,
asciidoc provides
a "rapid development process". At one point a more formal docbook
version is produced
with all the bells and whistles and integration with the rest of the
documentation.
No arguing writing in docbook can be a bit 'challenging' for some things.
I'm all for keeping it easy for the devs to edit and review patches.
I have a nervous twitch in my stomach about format proliferation
though. I do not want to end up back where we were a year ago.
I think the best protection against format proliferation is active
maintainership and guidelines. write down what format doc has to be in
and people will use it. we have freedom of choice, give us freedom from
choice ;)
I think that first one is the tough part. Active maintainership. But
the second is easily doable.
best proof this works: people are still writing roff
The doc will never be considered 'done' though, docs never are.
Someone will have to make the call at some point and say 'close
enough, convert to docbook.'
given a reasonable asciidoc source, what is the benefit of converting to
docbook? just more highlighting or are there other features that we could
really need?
I went and dug a little more into asciidoc soas to not completely talk
out of my rear. I think the big benefit is that docbook handles
'collection' which are just that, collections of docs that fit together,
a set. The olink tag, for instance, lets us link between the docs
without having to know the exact install path. For example in the proto
docs, you can reference error results that are written specifically
about in the current doc, and when the docs get built, docbook figures
out where the link should point to. it also goes the other way, any
other doc can reference, for example ADDMASTER, and the link will be
guaranteed to resolve within the collection.
This makes it possible for distros to install the docs locally without
any extra massaging. It also makes it easier Alan when creating the
release docs that go on the website.
While X is ~240 separate modules, of which only a couple dozen have
substantial documents, the docbook lets us create a nice collection.
asciidoc seems to be geared towards individual, standalong documents, no
concept of crosslinks. Please correct me if I'm wrong.
Matt
_______________________________________________
xorg-devel@lists.x.org: X.Org development
Archives: http://lists.x.org/archives/xorg-devel
Info: http://lists.x.org/mailman/listinfo/xorg-devel
