Subject:
Re: AsciiDoc and DocBook, again
From:
David Lawyer ####@####.####
Date:
11 Oct 2005 07:32:48 -0000
Message-Id: <20051011073252.GA2314@lafn.org>
On Mon, Oct 10, 2005 at 02:01:45PM +0200, Scot Stevenson wrote:
> 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
Likely so but LDP could revive it.
> 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>
Here it is in LinuxDoc. I think that Copyright should be a subsection.
<sect>Introduction
<sect1>Copyright and License
<p>This document, <em>The Mock Mainframe Mini-HOWTO</em> is copyrighted
(c) 2003-2005 by <em>Scot W. Stevenson</em> 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 <url
url="http://www.gnu.org/copyleft/fdl.html" name="GNU Copyleft">
Note that I didn't type <sect1> but typed a vim macro I invented, ;s,
to get it. Etc.
> 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?
There's obviously less to type with Ascii-doc or LinuxDoc.
Interestingly, I discovered that LinuxDoc does have a <title> tag-pair
to put after a section tag, just like in DocBook, but if it's missing,
what comes after <sect> is just assumed to be the title. Few people
using LinuxDoc are aware of this. This feature of permitting the
omission of tag-pairs makes it a lot easier to use, but more difficult
for the software that parses it. This is as it should be. Make the
software do the work instead of humans.
> >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.
If LDP were to accept AsciiDoc, wouldn't it be overkill to convert it
to DocBook? It's simpler to automatically convert it to LinuxDoc?
Then if someone wants to take it over and use LinuxDoc, they have it
in the right format. Anyone who knows DocBook can learn LinuxDoc more
easily than learning the markup for AsciiDoc.
I think that LinuxDoc has some advantages over AsciiDoc. First, it's
more powerful if one uses more than a minimal set of tags. But by
using only a minimal set of tags, it's as simple as AsciiDoc. What is
a tag is clear in LinuxDoc; it's enclosed in <> brackets. But for
AsciiDoc, tags are sometimes underlines, sometimes enclosure in
certain types of brackets (including repeated brackets like [[), etc.
I think this is harder to learn. Also, the <> type of tags are widely
used: html, xml, and DocBook, so many people are familiar with the
concept of the <> type of tags. So the skills learned in using
LinuxDoc can be transferred to working with html, xml, and docbook;
and conversely. This is advantageous.
I just now downloaded asciidoc and converted a supplied example file
to linuxdoc. Problems. One was that end tags were retained, making
the linuxdoc more difficult to read. Another was that the preamble in
the asciidoc was parsed (in conversion to linuxdoc) as an abstract.
This resulted in two abstracts in the doc, since it already had an
abstract. Linuxdoc complains (there is only supposed to be one
abstract per document). But the html output looked good after my
makefile for linuxdoc ran the html output thru the tidy program.
So could you ask the developer to improve the conversion to linuxdoc?
I'm also not so sure about the conversion to docbook since shouldn't
the "Copyright .." been <section1>, as subsection of the introduction
section?
What about the wiki markups? Wouldn't more people know them than
asciidoc? Can wiki be converted to LinuxDoc? I suppose they convert
wiki to html, but converting from html to LinuxDoc or DocBook doesn't
seem possible since html doesn't have section headers. Yet there is
software that claims to go from html to docbook but I'm skeptical as
to the quality of the conversion. In David Merrill's status report on
Lampadas, he was working on a converter of wiki to docbook and said
that after he finished that he would do the same for linuxdoc. But
he's no longer around.
David Lawyer
