[Docutils-users] docutils/rST vs direct html

[Malik Rumi]

Hello all,

This is my first post. I just joined because I was led here by the
instructions for getting admindocs working on django. I looked around,
followed some links, and think I learned a lot. But I do have a question.

My question is, why is rST any better than just putting the text in a text
editor and marking it up with html directly? Why would you chose to use rST
(or any 'lightweight markup language') instead? And I ask that in all
serious, trying to understand, as opposed to tying to cause controversy.


Thanks for enlightening this newby.

[Marc 'BlackJack' Rintsch]

Post by Malik Rumi
My question is, why is rST any better than just putting the text in a
text editor and marking it up with html directly? Why would you chose to
use rST (or any 'lightweight markup language') instead? And I ask that
in all serious, trying to understand, as opposed to tying to cause
controversy.

The term `lightweight markup language` contains a hint: It is easier to
write text with some lightweight markup syntax than marking it up with
something ”heavy” like HTML. Also easier to read, and therefore easier
to maintain.

You may try it yourself: Take each reST syntax construct and use it and
then write the same text directly in HTML. See which markup is more
disruptive to the thinking and writing process and which is more error
prone.

The ”lightweight” markup languages are more suitable for humans to read
and write, while HTML is designed to be easy readable by the computer.
HTML has the additional ”problem” that it is, or at least was in the
beginning, meant to describe the layout and looks of the document while
for a human writer (and reader) semantics are more important for most
kind of documents.

Ciao,
Marc 'BlackJack' Rintsch

[Alan G Isaac]

The ”lightweight” markup languages are more suitable for humans to read
and write

That's certainly a key reason: pretty much anyone
will be able to read it, without instruction.

My original reason was that I was submitting papers
to places some of which did not accept LaTeX, while
others did. By using reST I could produce LaTeX or
HTML as needed. (This was not quite as clean as I
hoped, since the no-LaTeX outlets generally wanted
Word (I kid you not). Word's import of HTML left
much to be desired, and at the time the Word writer
for reST had too many missing features. It was still
better than converting LaTeX however!

Alan

[Roberto Alsina]

Post by Malik Rumi
Hello all,
This is my first post. I just joined because I was led here by the
instructions for getting admindocs working on django. I looked around,
followed some links, and think I learned a lot. But I do have a question.
My question is, why is rST any better than just putting the text in a
text editor and marking it up with html directly? Why would you chose
to use rST (or any 'lightweight markup language') instead? And I ask
that in all serious, trying to understand, as opposed to tying to
cause controversy.
Thanks for enlightening this newby.

+---------------------+-------------------------------+
| This is a table. | It's not a big table. but it's|
| | mine. |
+---------------------+-------------------------------+

<table><tr><td>This is a table</td><td>It's not a big
table but it's mine</td></tr></table>

[Pete Jemian]

It also fits inline program documentation easier than direct HTML or
many other types of markup.

Another plus is that the syntax rules are so easy, it is a low barrier
for collaborators to contribute.

Another consideration is that HTML might not be the target output.

Post by Roberto Alsina

Post by Malik Rumi
Hello all,
This is my first post. I just joined because I was led here by the
instructions for getting admindocs working on django. I looked around,
followed some links, and think I learned a lot. But I do have a question.
My question is, why is rST any better than just putting the text in a
text editor and marking it up with html directly? Why would you chose
to use rST (or any 'lightweight markup language') instead? And I ask
that in all serious, trying to understand, as opposed to tying to
cause controversy.
Thanks for enlightening this newby.

+---------------------+-------------------------------+
| This is a table. | It's not a big table. but it's|
| | mine. |
+---------------------+-------------------------------+
<table><tr><td>This is a table</td><td>It's not a big
table but it's mine</td></tr></table>
------------------------------------------------------------------------------
CenturyLink Cloud: The Leader in Enterprise Cloud Services.
Learn Why More Businesses Are Choosing CenturyLink Cloud For
Critical Workloads, Development Environments & Everything In Between.
Get a Quote or Start a Free Trial Today.
http://pubads.g.doubleclick.net/gampad/clk?id=119420431&iu=/4140/ostg.clktrk
_______________________________________________
Docutils-users mailing list
https://lists.sourceforge.net/lists/listinfo/docutils-users
Please use "Reply All" to reply to the list.

--
----------------------------------------------------------
Pete R. Jemian, Ph.D. <***@anl.gov>
Beam line Controls and Data Acquisition, Group Leader
Advanced Photon Source, Argonne National Laboratory
Argonne, IL 60439 630 - 252 - 3189
-----------------------------------------------------------
Education is the one thing for which people
are willing to pay yet not receive.
-----------------------------------------------------------