discuss: Suggestion: AsciiDoc as a new format for submissions
Subject:
Suggestion: AsciiDoc as a new format for submissions
From:
"Scot W. Stevenson" ####@####.####
Date:
27 Apr 2004 00:26:42 -0000
Message-Id: <200404270123.11489.scot@possum.in-berlin.de>
Hello there,
I would like to respectfully suggest the LDP maintainers consider AsciiDoc as
an acceptable format for document submissions.
AsciiDoc is a GPLed formating system written in Python by Stuart Rackham. It
lives at http://sourceforge.net/projects/asciidoc/ . From the docs:
"AsciiDoc is a plain text human readable/writable document format that can be
translated directly to DocBook and HTML using the asciidoc(1) command. You
can then either use asciidoc(1) generated HTML directly or run asciidoc(1)
DocBook output through your favorite DocBook toolchain to produce PDF, HTML,
RTF and even HTML Help presentation formats. The AsciiDoc format is a useful
presentation format in it's own right: AsciiDoc files are unencumbered by
markup and is easily viewed, proofed and edited."
Submitting a text to TLDP currently involves learning DocBook, which is a
significant entry barrier: As powerful as DocBook is, to new users it is
confusing (two different versions: XML and SGML), its tool chain is a mess
and complicated to set up, the number of commands is bewildering, and the
number and length of the tokens make it -- bluntly speaking -- a pain in the
rear to write in. Reading -- and therefore maintaining -- DocBook source
texts is almost as bad.
AsciiDoc by contrast might not have all of the options that DocBook has, but
its syntax is intuitive, quickly learned and should cover anything that TLDP
rationally needs. From the example file included (best viewed in monospace):
====================================
The Article Title
=================
Author's Name ####@####.####
v1.0, Dec 2003
This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.
Abstract
--------
The optional abstract (one or more paragraphs) goes here.
This document is an AsciiDoc article skeleton containing briefly
annotated element placeholders plus a couple of example index entries
and footnotes. The preface, appendix, bibliography, glossary and index
section titles are significant ('specialsections').
====================================
Many of the formats follow existing ascii conventions: Bold texts are *bold*,
lists are
- Just as simple as this
- and another entry
or
1. Just like this
2. and another entry
There are footnotes and nested subsections and verbatim blocks, css support
and quotes and all the rest. The use of normal and intuitive ascii
structures instead of tags makes the whole thing easier to read, write and
the resulting files are smaller than DocBook.
Since it is Python, AsciiDoc is platform independent. It should be easier to
maintain and bugs should be easier to repair. Since you can directly create
HTML without having to start the whole DocBook machinery, write-view-rewrite
cycles should be shorter. Since texts can be converted to DocBook, there
should be a way to use the existing TLDP tools while lowering the entry
barrier for new writers -- in other words, migration should be simple.
I have found AsciiDoc very easy to use, especially compared to straight
DocBook. My knowledge of DocBook and the details of the TLDP preparation
process is too limited to say just how much of an effort would be involved
in adding this format; however, I do think that making it easier for people
to get writing would be worth a very high cost.
Thanks for reading,
Y, Scot
--
Scot W. Stevenson - Panketal, Germany
