discuss: Thread: Suggestion: AsciiDoc as a new format for submissions

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

On Tue, Apr 27, 2004 at 01:23:11AM +0200, Scot W. Stevenson wrote:
> Submitting a text to TLDP currently involves learning DocBook, which is a 

No it doesn't. This is one of the BIGGEST misconceptions about the LDP
submission process. Please read:
	http://tldp.org/LDP/LDP-Author-Guide/html/process.html
especially #2 and the additional note at the bottom. We will accept text
in *any* format. To be a part of the LDP's publishing process documents
which are not in either LinuxDoc or DocBook are converted by a volunteer.
An author does not need to install anything from the tool chain. They can
run their document through Saqib's on-line converter which is at:
	http://www.xml-dev.com/blog/test.php

If you'd like an easier markup language to work in than DocBook I
recommend taking a look at LinuxDoc.

Just out of curiosity, where did you read that a document must be
submitted in DocBook? I would like to correct the page that contains this
incorrect information.

thank you,
emma

-- 
Emma Jane Hogbin
Review Coordinator (Technical)
The Linux Documentation Project

 --- "Scot W. Stevenson" ####@####.####
wrote: > 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/ .

sinc asciidoc can be used to create docbook content,
you can very well use that tool and submit the docbook
equivalent if you feel thats convenient for you

regards
Rahul 

________________________________________________________________________
Yahoo! India Matrimony: Find your partner online. http://yahoo.shaadi.com/india-matrimony/

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

Hi,

"even though I am a LaTeX fan at heart."

Hmm, if you like LaTeX, have you tried using LyX? Chris's lyx-to-x scripts 
are now (I believe) a accepted way to create documents for the TLDP because 
they're submitted in docbook format (automatically generated).
However their setup while well-docmented is not easy.

http://www.karakas-online.de/mySGML/

I personally don't think its a bad idea, can you automatically convert this 
AsciiDoc to a DocBook format or LinuxDoc?

Then what is the problem with accepting this as a format? I mean their's 
nothing stopping this author from converting the AsciiDoc to LinuxDoc and 
submitting it (and you might not even know the difference if its nicely 
generated output).

Just my point of view...

Gareth

>From: "Scot W. Stevenson" ####@####.####
>Reply-To: ####@####.####
>To: ####@####.####
>Subject: Re: Suggestion: AsciiDoc as a new format for submissions
>Date: Tue, 27 Apr 2004 09:08:46 +0200
>
>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
>
>
>______________________
>http://lists.tldp.org/
>

_________________________________________________________________
SEEK: Now with over 50,000 dream jobs! Click here:  
http://ninemsn.seek.com.au?hotmail

> 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. 

Has anyone tried running an asciidoc "HOWTO"-type document thru the 
command to generate DocBook? I'd be interested in seeing the Docbook
markup, esp. wrt:

- container elements; hierarchy - article or book, sections/chapters?
- meta-data ({article,book}info - author/revhistory/abstract/pubdate) 

all the important stuff. 

If it can do a decent job (like wikitext did, which no one adopted
but we did accept!), then I think we'd be open to such submissions.
What I don't want to run into is garbage DocBook being generated which
in turn produces error-filled documents (which I would then need to 
correct as part of the publishing process).

regards



-- 
Greg Ferguson / LDP volunteer
####@####.####

Hi

Yes.You might have to learn docbook but there is a
quick workaround. keep your own copy of ascii document
and submit the linuxdoc/docbook document. document the
process in the author guide

regards
Rahul

________________________________________________________________________
Yahoo! India Matrimony: Find your partner online. http://yahoo.shaadi.com/india-matrimony/

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

At 14:44 4/27/2004, ####@####.#### wrote:
>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.
>[...]
>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?

Please delete unnecessary text from your replies, so the rest of us don't 
have to wade through pages and pages of stuff to see what you wrote. Not 
only will such courteous behavior make others happier, it will increase the 
chances that people actually read and think about your message.

Most of what you look for, if not all, is included in Stein Gjoen's 
tutorial on DocBook. Have you seen it? If so, is it missing anything? Stein 
is also on this list if you care to offer feedback.

Cheers,


-- 
Rodolfo J. Paiz
####@####.####
http://www.simpaticus.com

> ...
> 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?

Did you examine the Sample-HOWTO file?

  http://tldp.org/authors/template/Sample-HOWTO.xml

Author's Resources area has a lot of information/links:

  http://tldp.org/authors/index.html#resources

And we have some wonderful templates (thanks to Tille) in
the LDP Author Guide as well:

  http://tldp.org/LDP/LDP-Author-Guide/html/templates-book.html

No need to re-invent the wheel.

-- 
Greg Ferguson / LDP volunteer
####@####.####