discuss: Don't use DocBook, use AsciiDoc, it's for humans
Subject:
Re: [discuss] Don't use DocBook, use AsciiDoc, it's for humans
From:
David Lawyer ####@####.####
Date:
18 Dec 2005 01:27:43 -0000
Message-Id: <20051218012802.GA2306@lafn.org>
On Tue, Dec 13, 2005 at 09:38:38AM +0100, Scot W. Stevenson wrote:
> Hello Yves,
>
> >I'm convinced that we're shooting ourselves in the foot by
> >recommending
> >DocBook at this time.
>
> My feelings exactly. Unfortunately, the majority here seems to be of
> different opinion. Life is bad.
>
> But no! Not all is lost. Normal humans and other people who don't
> think they should be forced to type endless series of tags just
> because it is a technical text can use Stuart Rackhams's AsciiDoc
> (http://www.methods.co.nz/asciidoc/index.html) for their HOWTOs. From
> the blurb:
>
> "You write an AsciiDoc document the same way you would write a normal
> text document, there are no markup tags or weird format notations.
That's just the problem. There is markup to AsciiDoc and it consists
of assorted symbols and underlining. One sees this in the source and
doesn't realize that it's a "hidden tag". That's why I like LinuxDoc
better. It's clear what's a tag since they are enclosed in <>
brackets, just like in DocBook. Furthermore, if you have to use
DocBook later on, knowing LinuxDoc will help.
Example. Instead of <title> <sect> <sect1> <sect2> <sect3> asciidoc
uses underlines (excerpt from AsciiDoc documentation):
The default title underlines for each of the document levels are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
Examples:
Level One Section Title
-----------------------
Level 2 Subsection Title
~~~~~~~~~~~~~~~~~~~~~~~~
One line titles
One line titles consist of a line starting with one or more equals
characters (the exact number specified the section level) followed by a
space followed by the section title. Here are some examples:
= Document Title
== Section level 1 title (top level section)
=== Section level 2 title
==== Section level 3 title
===== Section level 4 title
The syntax can be changed by editing the configuration file [titles]
section sect0...sect4 entries.
--------------------------------------------------------------------------
Note there are two ways to do sections. === is ~~~~~~~ (as underline)
is <sect2> in LinuxDoc is <sect2><title> </title> </sect2> in
DocBook (end tags required). In this case I think LinuxDoc is the
simplest. AsciiDoc is more complicated, especially since there are 2
alternate ways of doing it. DocBook is the most complex.
One problem is that AsciiDoc doesn't seem to auto-generate a table of
contents. Before I suspected this omission, I was going to suggest
that LDP should accept submissions in AsciiDoc. The AsciiDoc
documentation says that what it calls callouts are not supported in
LinuxDoc, but one can achieve the same result using labels and
references.
David Lawyer
