Re: Updating the manual
Brendan Cully <brendan@xxxxxxxxxx>, 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/