discuss: AsciiDoc and DocBook, again
Subject:
AsciiDoc and DocBook, again
From:
Scot Stevenson ####@####.####
Date:
10 Oct 2005 12:01:50 -0000
Message-Id: <32CC00E5-CAB5-495A-AFD9-4E5869A2C024@possum.in-berlin.de>
Hello David
> I think that I took a very quick look as AsciiDoc some time ago and
> concluded that it was not much easier than LinuxDoc
I wouldn't know about LinuxDoc -- I have the impression that is it
slowly falling into general disuse, but that certainly just could be
my perception. What I would like to do, though, is give you an real-
life example of what AsciiDoc looks like:
========================================================
Introduction
------------
Copyright and License
~~~~~~~~~~~~~~~~~~~~~
This document, 'The Mock Mainframe Mini-HOWTO' is copyrighted (c)
2003-2005 by
'Scot W. Stevenson' Permission is granted to copy, distribute and/or
modify
this document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is available at
http://www.gnu.org/copyleft/fdl.html[GNU Copyleft]
========================================================
Now, exporting this as DocBook gives us:
========================================================
<section>
<title>Introduction</title>
<section>
<title>Copyright and License</title>
<simpara>
This document, <emphasis>The Mock Mainframe Mini-HOWTO</emphasis> is
copyrighted (c) 2003-2005 by
<emphasis>Scot W. Stevenson</emphasis> Permission is granted to copy,
distribute and/or modify
this document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is available at
<ulink url="http://www.gnu.org/copyleft/fdl.html">GNU Copyleft</ulink>
</simpara>
</section>
========================================================
Now, this is a simple example -- the real killer is stuff like lists
-- and you can argue that DocBook is a bit easier on the eyes if you
ident it. But still: Which is easier to read and write? Which is less
to type?
> So since the existing docs are in
> LinuxDoc/DocBook, they probably should be kept in those formats.
Oh certainly. I completely agree that the best format for finished
texts is DocBook, simply because there are so many ways to use it.
What I would suggest, however, is that the Project actively supports
AsciiDoc as a -- if not the -- primary format for authors, because it
is so much easier on humans. The humans write AsciiDoc, which is then
automatically converted to DocBook, which the wizards at the Project
then can work their magic on. The humans are happy, the computers are
happy, and the penguin gets more fish.
Y, Scot
