Re: Scrap Docbook in favour of Asciidoc?
On Wed, Apr 27, 2011 at 07:42:12PM +0200, Dominik Vogt wrote: Which are readable in vi *and* can be nicely converted to any other format *and* look good. Since I am in limbo with FVWM's development, and this is something I wanted to do for ages anyway, I have made a start. But it's a lot of hard work, most notably because there is no way to go from raw Docbook to Asciidoc. Which makes converting over fvwm.1 annoying. However, I think I've solved that. Converting the rawe *roff formats we have for other man pages isn't too hard. It's quite a lot of fun, actually. :) We'd need a stylesheet most likely but that's for someone else to do. -- Thomas Adam -- 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.)
Re: Scrap Docbook in favour of Asciidoc?
On Sat, Apr 23, 2011 at 09:18:05PM -0400, des...@verizon.net wrote: Thomas Adam tho...@fvwm.org writes: Hi all, 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. ... [1] http://www.methods.co.nz/asciidoc/ Wow, cool. It's yet another documentation language but it looks like they go to pains to make the markup as invisible as possible. Yup, asciidoc is my format of choice. It actually evolved from a simple tool to add markup for printing to existing ascii documents which is why the markup mostly non existent. Without knowing anything about asciidoc, you can write documents like Theory of foobar 1. Inroduction bla bla bla bla bla bla 2. Basics 2.1 Terms bla bla bla * foo * bar * baz Appendix A -- ... Appendix B -- ... Which are readable in vi *and* can be nicely converted to any other format *and* look good. I think that might even make Dominik happy. ;-) I love asciidoc. It's a tool for hard core programmers that are forced to write documentation. Ciao Dominik ^_^ ^_^ -- Dominik Vogt
Re: Scrap Docbook in favour of Asciidoc?
On Sat, Apr 23, 2011 at 09:18:05PM -0400, des...@verizon.net wrote: Thomas Adam tho...@fvwm.org writes: Hi all, 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. ... [1] http://www.methods.co.nz/asciidoc/ Wow, cool. It's yet another documentation language but it looks like they go to pains to make the markup as invisible as possible. Yes -- out of the plethora of other ones [1][2] available, it is Asciidoc which seems to have won -- or at least the more widely-used. I've used it, even at work and have found the markup to be, as you say, as invisible as possible. I think that might even make Dominik happy. Heh. -- Thomas Adam [1] http://daringfireball.net/projects/markdown/ [2] http://txt2tags.org/ -- 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.)
Scrap Docbook in favour of Asciidoc?
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.)
Re: Scrap Docbook in favour of Asciidoc?
Thomas Adam tho...@fvwm.org writes: Hi all, 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. ... [1] http://www.methods.co.nz/asciidoc/ Wow, cool. It's yet another documentation language but it looks like they go to pains to make the markup as invisible as possible. I think that might even make Dominik happy.
