Something like Structured Text or Markdown have simple enough formats that they don't interfere with the writing of normal documentation. (STX has some parsing problems, but nothing that can't be fixed)
reStructuredText crosses far, far over into markup-land, and occupies this strange space of not quite being as capable as HTML, but every bit as complex. Just look at the default link syntax, wow. Anyway, I'm sure it works well for programmers and other people that like learning new syntax and juggle a few of them in their heads, but it's an absolute disaster among "normal people", whereas Structured Text and Markdown both work pretty well for these people.
And reST's HTML output is exceptionally bad. No, really:
http://article.gmane.org/gmane.comp.web.zope.plone.documentation/1498
Ah, feels good to get that rant off my chest. Again. ;-)
PS: Of course, I'm of the opinion that basic XHTML should be a mandatory language for fourth-graders. It's the only universal markup language! :-)
inline literal text bug filed
Posted byjeffkat
2008-04-09 03:24 PM
limi, bug now filed for this specific shortcoming: http://sourceforge.net/tracker/index.php?func=detail&aid=1938891&group_id=38414&atid=422030 .
If there is a systematic way to identify others, I'd file additional bugs. I think the docutils developers would choose to fix those which they are informed of.
Perhaps some large or representative reStructuredText document run through rst2html, then comparing that output HTML to manually cleaned up compliant XHTML. Or do you suggest a specific configuration of a tidy tool to produce this XHTML for diff?
reStructuredText crosses far, far over into markup-land, and occupies this strange space of not quite being as capable as HTML, but every bit as complex. Just look at the default link syntax, wow. Anyway, I'm sure it works well for programmers and other people that like learning new syntax and juggle a few of them in their heads, but it's an absolute disaster among "normal people", whereas Structured Text and Markdown both work pretty well for these people.
And reST's HTML output is exceptionally bad. No, really:
http://article.gmane.org/gmane.comp.web.zope.plone.documentation/1498
Ah, feels good to get that rant off my chest. Again. ;-)
PS: Of course, I'm of the opinion that basic XHTML should be a mandatory language for fourth-graders. It's the only universal markup language! :-)
If there is a systematic way to identify others, I'd file additional bugs. I think the docutils developers would choose to fix those which they are informed of.
Perhaps some large or representative reStructuredText document run through rst2html, then comparing that output HTML to manually cleaned up compliant XHTML. Or do you suggest a specific configuration of a tidy tool to produce this XHTML for diff?