Hi all,
I appreciate things might seem somewhat topsy-turvy at the moment, but I
still want to suggest this, anyway.
For a while now we've been using Docbook which inherently means knowing XML,
and worse yet, its flavour of it. Unfortunately, I don't think anyone but
Scott Smedley really knows how this all fits together, and that's bad,
because:
* Documentation with regards to new features is difficult/impossible to
write.
* Knowing how the documentation fits in to FVWM is a lost art on most
current developers.
* The format of the documents is raw XML which many view as cumbersome.
I'm sure there's other, more important points, but they're the more general
ones.
To cure this, and to take the burden off needing to know XML, I'd like to
suggest we switch the entire documentation set over to Asciidoc[1] which has
the advantage of low overhead in terms of markup (because it's mostly plain
text anyway), but is also powerful enough to allow many different formats to
be produced as a result -- not just HTML and man page formats which are our
primary needs.
At the moment though we have a lot man pages which still require raw *roff
format to be used (such as those in modules/Fvwm* -- and bringing these in
to line with using Asciidoc seems like a good idea as well.
How do people feel about this? FWIW, Asciidoc is used on a lot of open
source projects for this very reason (Git is one of them, actually). I'm
wondering though what the packaging requirements might be downstream of us,
and whether that might cause a problem? It should do, but I'd still like to
hear from packagers in case they know of any problems.
Again, once we're up and running with Git, and things have settled, I'd like
to see how feasible this is, assuming no one objects.
Kindly,
-- Thomas Adam
[1] http://www.methods.co.nz/asciidoc/
--
Deep in my heart I wish I was wrong. But deep in my heart I know I am
not. -- Morrissey (Girl Least Likely To -- off of Viva Hate.)
