I think I am finally liking RestructuredText better than StructuredText for Zwiki. We have had some zwiki fixes recently which make it more pleasant (fewer warnings, header levels fixed, better stylesheet). The complicated linking syntax can be ignored if you just need zwiki links and bare urls. And I'm most interested in non-DTML, non-HTML-cluttered, standardised markup wikis at the moment.

Here's a multi-pronged proposal:

  1. support RestructuredText to the same degree as StructuredText (pretty comment headings, careful wiki linking, quick comments ?)
  2. if suitable, make it Zwiki's default page type instead of stx
  3. make it not just the default, but the only page type enabled out of the box in new wikis (others would have to be enabled explicitly), and focus on it in docs
  4. adopt it as preferred markup for zwiki docs, zwiki.org and zopewiki
  5. begin a process of converting existing docs and pages to it
  6. give in to docutils' preferred 'reStructuredText' capitalization for naming our RST-related pages, instead of the current 'RestructuredText' ?

Pro:

Con:

See also: RestructuredTextDemo, RestructuredTextCheatSheet

Created:2006/03

subtopics:

Just my 2 cents... --Phil Schumm, Thu, 23 Mar 2006 10:53:12 -0800 reply

FWIW, we have been exclusively using reST as the default (and only) page type on our Wikis. Most of our users don't know HTML, and those who do for the most part try to avoid it. You point out that it's rules are more complex than STX, however I would argue that fiddling around with STX trying to get it to do what you want is more complex than simply consulting the (excellent) reST documentation. In short, while those who are already familiar with STX may find it a bit simpler, in my experience new users who don't know either find reST much less frustrating.

Concurring --John Maxwell, Sat, 25 Mar 2006 11:32:55 -0800 reply

I've been running my Zwiki sites using RST exclusively for a couple of years, with loads of neophyte users, and have never had serious learning problems with it. The consistency and readability of the source makes it a great choice, as does its excellent support for intra-page links (footnotes, tables of contents, and whatnot). I'm really pleased to hear you thinking of better support for it.

i18n --JózsefJároli, Wed, 29 Mar 2006 02:49:21 -0800 reply

big minus: basic STX works only with latin-1 characters (WikiPedia:ISO_8859-1).

small plus: mixing html is good for folks who don't want to learn an other markup or if complex tables are to be inserted, it is better to "draw" it with an HTML editor.

please work around the "unexpected unindent" annoyance --LucianoRamalho?, Thu, 30 Mar 2006 11:39:14 -0800 reply

I like ReST but it can be very fussy. When you end a page with a list of items, you MUST have a newline after the last item, otherwise ReST complains about an "unexpected unindent". This is very confusing to users, but the fix is easy: always add a blank line at the end of your ReST documents. ZWiki could do that automatically, when needed.

please work around the "unexpected unindent" annoyance --simon, Thu, 30 Mar 2006 15:09:52 -0800 reply

That sounds worth doing, but I can't reproduce the problem at RSTTests - can you ?

please work around the "unexpected unindent" annoyance --simon, Thu, 30 Mar 2006 15:11:21 -0800 reply

The recent change in warning level probably took care of it.

update --simon, Thu, 30 Mar 2006 22:26:46 -0800 reply

As of today, RST is the default page type. Hurrah!

And three cheers for trusty old STX, which served us well. It is still the page type of choice when you want to do stuff with embedded DTML or HTML.