Brendan Cully <[EMAIL PROTECTED]>, 2007-02-28 08:49 -0800: > On Wednesday, 28 February 2007 at 09:47, Rocco Rutte wrote: > > Also, I think the current way of creating it is not very optimal since I > > (still) consider DocBook a format which is to be generated by machines, > > not written by humans (please no flamewar on that one! :)
I'm one of the maintainers of the DocBook XSL stylesheets, so I wanted to jump in and make a case for the value of continuing to use those as part of the doc build. First off, I want to say that the source for the docs does not necessarily need to be maintained in DocBook XML in order for make use of the DocBook XSL stylesheets in the doc build. You could maintain the source in asciidoc and still get the benefits of the DocBook XSL stylesheets -- the build would just need to include an intermediate step that converted from that form to DocBook XML. I think the asciidoc command can do that. And far as the benefits of using the DocBook XSLT stylesheets, the one big benefit is that it provides you with a lot of options about how you want your content rendered -- across a wide variety of output formats (HTML, PDF, groff/troff man pages). And though some other tools provide better output for specific formats (LaTeX provides higher-quality PDF output, native authoring in groff provides better man-page output), I don't think there is another tool that provides the same level of high-quality output across all those formats. > > Just a very stupid idea: why not play with asciidoc a little? It should > > do all what we want, we could finally simplify makedoc a lot and still > > get all output we want. Plus: the manual would be much easier to hack > > on, much smaller in size, etc. With some XSLT magic I think it could be > > more or less easy to create an initial asciidoc-based document. > > I'm for it. About halfway through your email I thought I was going to > have to write a 'why not asciidoc?' response :) One reason why not would be to make sure that asciidoc could actually provide the same level of semantic markup to capture the semantics of the current manual marked up in DocBook, and to do it in a way that does not end up making the source document even harder to read than it is in DocBook form. There are many elements in DocBook for which asciidoc doesn't have equivalent markup. And though asciidoc does in fact provide a some degree of sophistication for marking up your content semantically, in my experience at least, if you use very much of it, you end up with source that looks at least as arcane as, say, a groff/troff source document -- and the only way you or anybody else who looks at the file is going to remember what the markup means is by looking at it side-by-side with the asciidoc user guide to try to decipher it. But it may well be that the current mutt manual does not contain the level of inline markup that would require some of the more arcane stuff from asciidoc. --Mike -- Michael(tm) Smith http://people.w3.org/mike/
