discuss: Suggestion: AsciiDoc as a new format for submissions
Subject:
Re: Suggestion: AsciiDoc as a new format for submissions
From:
"Scot W. Stevenson" ####@####.####
Date:
27 Apr 2004 08:11:17 -0000
Message-Id: <200404270908.46928.scot@possum.in-berlin.de>
Hello Emma Jane,
> No it doesn't. This is one of the BIGGEST misconceptions about the LDP
> submission process.
Submission, yes. However, let's assume that you want to maintain your text,
because nice people have given you all sorts of helpful feedback and you're
the kind of person who believes that texts get better with every rewrite.
And now let's go to
> http://tldp.org/LDP/LDP-Author-Guide/html/process.html
and take a look at entry 4.3.1:
" You do not need to submit your initial document to the LDP in anything more
than plain text! The LDP volunteers will convert your document to DocBook
for you."
So far, so good. But then if you read on:
"Once it has been converted you will need to maintain your document in
DocBook format."
In other words: If you want to be part of the LDP, sooner or later you are
going to have to learn DocBook. Later, in 5.4, we again have:
"A new document may be submitted to the LDP in any format. Documents which
are not in DocBook or LinuxDoc will be converted by a volunteer. The author
is responsible for adding markup to any revisions which are made."
Again, sooner or later, you are going to have to learn a markup language
where you can't even write a single paragraph without using the dreaded
pointy brackets. Not good.
> If you'd like an easier markup language to work in than DocBook I
> recommend taking a look at LinuxDoc.
AsciiDoc is far simpler than LinuxDoc -- in fact, LinuxDoc is one of the
markup languages AsciiDoc can be automatically converted into. I think I
forgot to mention that. Unix man page format is another.
Actually -- and I think this is true for the majority of authors -- I don't
/want/ to have work in a markup language /at all/, even though I am a LaTeX
fan at heart. I just want to write my text and concentrate on the content,
and if it was up to me, I'd be using OpenOffice.org the same way I do for
anything else that I can't use vi for. I certainly don't want to have to
learn a hideously overfeatured markup language like DocBook just to be able
to maintain a text for the LDP. One reason I haven't updated the Mock
Mainframe HOWTO yet is because I feel nauseous at the very idea of the
amount of markup required to just write a simple list. I'm sure other
authors feel the same way.
My point is that as great as DocBook might be for processing the finished
texts, it is a pain in the rear as the primary format for authors who want
to do more than submit a first version and then run. It is my feeling that
the LDP is scaring off authors by requiring them to deal with DocBook in any
form and even mentioning the name. However, I do understand that every
author who does submit things in DocBook makes life that much easier for the
volunteers who are running LDP and that there is a certain lack of people
who would like to spend their lives converting plain text to DocBook. Which
doesn't surprise me at all, I might add.
AsciiDoc seems to be a way to get around this: It is a simple ascii-based
format that takes minutes to learn and can be converted to DocBook for all
the other voodoo stuff. In other words, it looks like a way that we can have
our cake and eat it, too, and that is why I suggested that you and the other
people who do most of the heavy lifting take a look at it.
Since I am the one who brought it up, how about this: If you find that
AsciiDoc can be included in the list of formats that are acceptable to the
LDP for submission as well as for maintenance (!), I'll write a chapter for
the Guide, including examples. Then, authors have the choice of either
learning DocBook for maintenance or AsciiDoc, and everybody is happy.
Thanks again for reading,
Y, Scot
--
Scot W. Stevenson - Panketal, Germany
