Subject:
Re: Suggestion: AsciiDoc as a new format for submissions
From:
####@####.####
Date:
27 Apr 2004 20:43:22 -0000
Message-Id: <408EE250.2822.15E1D8@localhost>
Hello,
>
> > 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
I form myself think learning Docbook is a task everybody can achive
without wasting a lot of money. You will find lots of structured
document-types everywhere you turn on the world wide web, usenet,
etc.
I had to learn DocBook to publisch my first version of my glibc-
HOWTO. Having read some useful sites (just taken from google) it was
no great problem for me to switch from LaTeX, which I used during the
creation of the first text-parts, to DocBook. As I am also used to
writing smaller pages in plain (X)-HTML, I found that DocBook is a
great mixture from both worlds, allowing to create every possible
Doctype you would need.
Especially the "long" Tags make it as easy as possible to the author
to create his text, as you don't have to learn all those
abriviations, you might have in HTML or even in LaTeX.
The only thing I missed was a "quick and dirty" or "fast"
introduction to the format, maybe it would be usefull to have a
skeleton file with an initial structure and some comments in it, to
make it even easier getting along with Docbook.
Here are some points, that in my opinion should go into such a file
- Header of the Docbook-File (this is the thing that shocked me at
first ;-) )
- a sample structure of the hierachies possible to generate with
DocBook
- a short list of Tags that are frequently needed when writing e.g.
a HOWTO.
- nice to have: A prewritten Introduction, containing all the things
concerning the licencense, copyright/left
- someone an idea what else should be mentionend?
If I find the time, I am going to create such a file, but that may
take up to 5 weeks :-( - anybody willing to do so?
> > 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
>
>
> ______________________
> http://lists.tldp.org/
>
C.U. MC Murphy
PGP-fingerprint: 8640 43BF 0807 8349 67F4 C0CE CBA9 83BA 197B 3ED4
