Comparing MarkDown and reST (Was: Consistent formating long descriptions as input data)
On Thu, 23 Apr 2009, Daniel Burrows wrote:
I'm happy to support whatever markup language people want to use.
Same for me. To feed some facts to be able to compare the options
I rendered the debug blends pages with reST using the very same code
for the preprocessing which does
1. s/^ //
2. s/^\.$//
3. s/^(\s*)[.o]\s+/\1* /
This enables rendering lists using 'o' and '.' as bullets
4. s/<*([fh]t?tp:\/\/[-./\w?=~;&]+)>*/[\1](\1)/
This is to mark URLs in Markdown - Syntax which definitely
confuses reST - I should drop this for a fair comparison - so
please ignore this
5. s/^#/\\#/
A '#' in the first column has some specific meaning in Markdown
and has to be escaped (which seems to work fin in reST[1])
6. Include empty line before lists and verbatim lines
7. Insert '\t' in the beginning of verbatim lines - this
seems to confuse reST definitely (I have not yet looked
into the reST docs because I'm just lacking time) which can
basically be seen in the remarks which are intended to be
verbatim but the reST pages just render lists etc as well
I used for markdown
from markdown import markdown
markdown(preprocessed_string)
and for reST
from docutils.core import publish_parts
publish_parts(preprocessed_string, writer_name='html')['body']
Conclusion:
Markdown renders a lot of descriptions correctly but has several
missinterpretations of multilevel lists which are partly "invented"
by Markdown and partly not detected and turned to single level
lists. I have not yet dived into the docs of the Python library
but at first sight there are no obvious warnings / errors about
potential problems.
reST also renders sevral lists quite fine. The comparison is partly
unfair because the preprocessing was keeping Markdown in mind but
reST probably need other tunings. I have no time to verify this -
hints are welcome. What I really like in reST is the fact that
you get allways messages like
...
<string>:10: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
<string>:11: (WARNING/2) Enumerated list ends without a blank line; unexpected unindent.
<string>:15: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
<string>:12: (ERROR/3) Unexpected indentation.
<string>:13: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
<string>:17: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.
<string>:18: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
<string>:13: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.
<string>:5: (SEVERE/4) Unexpected section title or transition.
...
and so you have an easy interface to check descriptions with
lintian or by other means.
Here you can view the results:
Markdown:
http://blends.debian.net/debug/tasks/
reST:
http://blends.debian.net/rest-test/tasks/
Hope this helps to compare the two options which were discussed here
Andreas.
[1] http://blends.debian.net/rest-test/tasks/works#geordi
--
http://fam-tille.de
Reply to: