Discussion

Please post your comments here, for now. If enough interest we can create a discussion page.

Thoughts:

  1. Should reSTX be implemented in ZWiki ?
  2. Does anyone know of a STX to reSTX converter ? There doesn't exist an HTML to reSTX.

Jay, Dylan, 2002/09/16 05:42 GMT (via mail):

Cleaned up RestructuredText page. Attempt at kicking off a discussion.

We've talked about this before. I'm all for it simply because the non-indent approach is a bloody good idea.

Should it be implemented? Someone with some time (i.e. not me) just needs to go ahread and do it. Just do so in a way that it becomes another rendering option so that ZWiki users have a choice to use it or not. Replacing stx is a bad idea because of backward compatibility issues.

DeanGoodmanson, 2002/09/26

I've updated this page with feedback I've received from David Goodger .

First step to development would be adding a new render type.

Replacing stx is a bad idea because of backward compatibility issues. Doesn't seem to be a peaceful co-existance...thus the need for migration tools.

Jay, Dylan, 2002/09/26 22:56 GMT (via mail):

Doesn't seem to be a peaceful co-existance...thus the need
for migration tools.

You really think u need migration tools? If someone wants to use rStx then they will setup their wiki to do so from the start. Perhaps a better use of a similar effort would be roundtrip conversion from html to rStx, then you can still build a migration tool, plus such code could be used to support wysiwyg editing of stx/rstx by using a similar "source.html" mechanism that ZPT uses.

2002/09/27 00:11 GMT (via web):

The migration tool did seem to get more visibility than it needed, that is

Is Adding a reSTX render option for every STX option OK for the first round of render options list?

HTML -> reST sounds likes the best option, and once removed from STX. I asked about an HTML->reST existing code, and none exist. Those are some interesting possibilities. Maybe they'll help gather expert coders!

I haven't proceeded to the ZPT of the Zope learning curve. :-( Could you explain or point me to info on the "source.html" ZPT mechanism?

Co-existing will best determine the need for migration tools. I recall being a lacky in a college IT shop converting 35 meg+ Word 5 documents to Word 6 on a 486/33 laptop for a too-busy administrator.. I expected that wiki (and cmf) members would at least like an automated first pass at converting their stx documents to the latest format. I don't know the history of how changes of stx in the community propogated, though.

Jay, Dylan, 2002/09/27 00:39 GMT (via mail):

Is Adding a reSTX render option for every STX option OK for
the first round of render options list?

Yes, but I'm wondering about the combinatorial explosion of rendering options. Someone awhile back was talking about a flexible filter map for rendering for a wiki. That sounded nice but the times I've looked through the code there has been a high dependency between each of the rendering steps so I don't know how that would actually work. In terms of UI perhaps check boxes or multiple selection is going to work better but that might just open up a can of worms

HTML -> reST sounds likes the best option, *and* once removed  from
STX. I asked about an HTML->reST existing code, and none exist.
Those are some interesting possibilities. Maybe they'll help gather
expert coders!

Yes, it's something I've been thinking about lately esp with regard to editing a wiki as rtf or word doc, so then I can go backwards and forwards from word <-> wiki easily which I find myself doing a lot. Then I can also use a spell checker on my wiki's easily which is a real plus for me :) Roundtripping rtf and html seems to be done so I was thinking that html <-> stx (or reSTX) is the harder part that no one has really tried yet.

I haven't proceeded to the ZPT of the Zope learning curve.  :-( Could
you explain or point me to info on the "source.html" ZPT
mechanism?

Each template has a virtual sub object called source.html. If you access it via http or webdav or ftp you get the source rather than the rendered version of the template. This is a nice way to play nice with html wysiwyg editors. In the case with a reStx, instead of getting the source, you would get a rendered html document without the header and footer and without wikilinks rendered. Then if you try to save that back via webdav or ftp, it will try to interpret the html back into reStx by matching html patterns to reSTX structure. Then you have the roundtrip.

Co-existing will best determine the need for migration tools.  I
recall being a lacky in a college IT shop converting 35 meg+ Word 5
 documents to Word 6 on a 486/33 laptop for a too-busy
administrator.. I expected that  wiki (and cmf) members would at
least like an automated first pass at  converting their stx
documents to the latest format. I don't know the history of  how
changes of stx in the community propogated, though.

Well if each rendering option can render to html in such a way that headers and footers etc can be ignored, and html->reSTX is written, then a simple loop to do that for each would be trivial.

DeanGoodmanson, 2002/10/31 18:14 GMT (via web):

Zope.org Proposal by Andreas Jung : Integration of reStructuredText into Zope 2.7 , http://dev.zope.org/Wikis/DevSite/Proposals/ReStructuredTextIntegration

DeanGoodmanson, 2002/11/04 05:44 GMT (via web):

What-dya know, someone requested this via ZwikiIssueTracker #352 Add reStructuredText document type?.

DeanGoodmanson, 2002/11/06 03:54 GMT (via web):

Zope 2.7 update:

Integration of reStructuredText into Zope 2.7

a preliminary version that supports dtml is now available in the ajung-restructured-text-integration-branch on cvs.zope.org -- Anyone have a problem with holding off until 2.7?

Also, I played around with ZReST tonight and didn't dig enough to get any more than semi acquainted with the syntax. Details <a href="http://zwiki.org/DeanGoodmanson#ZRest">here</a>

Another STX rant.. --DeanGoodmanson, 2002/12/19 22:03 GMT (via web):

StructuredText is a system that does the job of making HTML easier, and as an article or prose markup it's quite handy.

Web sites, especially Wiki's (and my personal note taking style) are quite filled with lists and tables. These are some of STX's biggest weaknesses. Lists require double spacing, and have a number other whitespace and general nuances. Tables are simply a pain.

Zwiki makes up for this by allowing HTML in pages, and conveniently offers the external editor.

rest and wikis

PieterB:

Would you mind posting your preliminary plans?

I would be content (for experimental and starting point purposes) on a version which replaced all StructuredText with RestructuredText, and/or or a page similar to HTML which was /just/ RestructuredText content.

Zope 2.7 RestructuredText Status: Complete --DeanGoodmanson, 2003/03/12 23:00 GMT

While checking on the 2.7 status today I was pleased to see that the RestructuredText integration is complete. http://dev.zope.org/Wikis/DevSite/Proposals/ReStructuredTextIntegration

implementation notes --DeanGoodmanson, 2003/04/09 17:33 GMT

"copy one of the render_stx... methods, replace the STX call with the RST
call, add the new page type to ZWIKI_PAGE_TYPES and the editform. Old
pages will keep working and people can start creating/converting to RST
at will.

Performance and usability impacts are less certain."

via SimonMichael, - http://mail.zope.org/pipermail/zope3-dev/2003-April/006264.html

Release for 2.6 --DeanGoodmanson, 2003/04/10 06:16 GMT

We may not have to wait for 2.7!!! :-)

http://www.zope.org/Members/ajung/reStructuredText/backport_new

StikiWiki? --DeanGoodmanson, 2003/04/28 12:33 GMT

StikiWiki? is a Python based Wiki with reStructuredText markup. http://mithrandr.moria.org/code/stikiwiki/

restructured text support added --SimonMichael, 2003/05/06 18:18 GMT

I've just added a new page type, 'rstprelinkdtmlfitissuehtml' that does restructured text formatting, thanks to Andreas and Richard's zope integration & backport.

There's a bit of a spelling/abbreviation consistency problem here.. I have been using reSTX but it seems as if RST may be the best to go with.

Last month I took my third hard look at RST and liked it much better than before. I think/hope it's going to work really well for Zwiki. Shall we start converting some pages and see what kind of issues turn up ?

I tried to make headings start at level 2 not 3, but don't think it's working yet.

wah! --SimonMichael, 2003/05/06 18:22 GMT

I was afraid of that. RST doesn't allow HTML ?

a test comment using only rst formatting --SimonMichael, 2003/05/06

The comment body. It's not going to be as easy as all that.

RST doesn't allow HTML??! --DeanGoodmanson, 2003/05/06 19:10 GMT:

I'm also very baffled about the embedded HTML. Here's hoping it's a flag.

Looks like STX table are going to be the first that need converted. Let's see how the rest table looks:

a beeee c
1 2 235
4 55 6

RST comment format --SimonMichael, 2003/05/06 21:25 GMT

Zwiki now formats comment headings without HTML on RST pages.

Unicode Error -- RuedigerBlach, Tue Jul 8 16:02:00 GMT 2003

Problem: edit with GermanUmlaute ae, oe, ue, ... ==> save ==> Unicode Error

Is this a problem of ZWiki or Zope or Python? Any solution?

page update --2003/07/21 06:12 GMT reply

Added a link at the top of the page to the the "Restructured Text backport for Zope 2.6" (replaces ZReST), w/a note that it needs to be installed w/0-20-0 to render RST. and I made the link in RST! =}

I considered testing whether it would find the link from here ... but, mmm, no, better on a test page.

LaT

Re: Unicode Error -- Christian Tismer, Sat Jul 26 18:43:00

This is a problem with your Python setup in the first place.
You need to convince Unicode to use a defaultencoding which is not
ASCII. see /etc/python2.1/site.py , line 252, above
    # Enable to support locale aware default string encodings.
The other problem is Zope related or, well, maybe one could say
that the [reStructuredText] integration could be a little bit tighter.
At least I didn't have such problems with StructuredText.
To get your umlauts for Zope, you need to install a proper locale
on your Linux box, and then make sure that Zope is started
with an option like this: "-L de_DE"
Edit /etc/zope/zopectlrc, locate the comment telling you how
to add options to ZOPEOPTS and add this:
ZOPEOPTS="${ZOPEOPTS} -L de_DE"

installing reST rendering engine --laura trippi, Mon, 18 Aug 2003 15:55:32 +0000 reply

This is an "I'm not a developer" question... =}

I've gotten the Backport of reStructuredText support from Zope 2.7 to Zope 2.6:

http://www.zope.org/Members/ajung/reStructuredText/

That page says:

> To install the package you need to unpack the archive in the

top-level folder of your Zope installation.

I untarred it first in the upload directory on my zope host, and see that it's a lib directory. Zope (2.6.0) already has a lib directory:

> ls -l uploads/lib
total 2
drwx------  6 laura  laura  512 Apr 25 09:25 python

> ls -l Zope/lib
total 2
drwxr-xr-x  2 laura  laura  512 Oct 17  2002 python

Do I just overwrite Zope/lib w/the new one from reST? Should I worry about the permissions being different?

thanks,

LaT

hallo --Fri, 22 Aug 2003 09:15:15 +0000 reply

hallo

... --Tue, 02 Sep 2003 13:52:17 -0700 reply

I just tar -xzvf 'd the gzipped tar file rest-102.tar.gz in the directory where lib/python/products was.. /usr/local/Zope.. After I restarted Zope, I got the ability to add a reStructuredText document in the ZMI! (which actually worked.) Ok, actually, I unzipped it in Products first, but when it made a lib directory and I hunted around in it, I understood that it had several files to add to several directories under Zope, and the instructions of unzipping in the root made sense. Still got a ZWiki error about can't import reStructuredText, but maybe I can figure that one out.

... --mgedmin, Tue, 02 Sep 2003 14:45:21 -0700 reply

rest-102.tar.gz adds a new dependency to Zope -- you also have to have Python 2.1 distutils installed. After you do that and restart Zope, you might need to actually change the text of a ReST page to force rerendering, because that "error importing reStructuredText" message is cached persistently.

... --Drew, Tue, 02 Sep 2003 17:08:24 -0700 reply

distutils? or docutils? It looks like rest-102.tar.gz from the 2.6 backport adds docutils, ZReST, reStructuredText, and DocumentTemplate?/DT_Var.py stuff all at once for you. Thanks for the hint to change the page to force re-rendering. That works nicely!

... --Tue, 02 Dec 2003 12:51:23 -0800 reply

... --Tue, 02 Dec 2003 12:52:23 -0800 reply

2.6 Backport --Mon, 08 Dec 2003 21:52:02 -0800 reply

To get the Backport going properly for ZWiki and restuctured text inside a plone site I needed to change the imports around in the PageTypes?.py to look like this:

try:
   # start headings at level 2, not 3; will affect all rst clients
   # XXX not working
   import reStructuredText
   from  reStructuredText import html4zope
   html4zope.default_level = 2

except ImportError:
   reStructuredText = None
   DLOG('could not import reStructuredText, will not be available')
   raise

Notice the extra raise in there so that we get another bubble for other logs to catch.

Linking --jks, Fri, 23 Jan 2004 05:27:48 -0800 reply

How do I create a link on a ReST formatted ZWiki page, if I want the link text to look like a WikiName but to point the link to an external resource? If I do this:

[WikiName]_
.. _[WikiName]: http://www.example.com

I get an extra question mark. If I do this:

WikiName_
.. _[WikiName]: http://www.example.com

I don't get any link at all.

2.6 Backport --simon, Fri, 23 Jan 2004 06:20:17 -0800 reply

> Notice the extra raise in there

Oh, I missed that. Can you clarify how the system will behave differently with or without it ? Should I be doing this in all similar cases ?

Linking --simon, Fri, 23 Jan 2004 06:43:44 -0800 reply

Not easily.. there may be some trick, but I couldn't find it at RSTTests.

It's awkward to make these things coexist nicely. There is some built-in knowledge of STX markup which helps to keep STX and Zwiki's processing out of each other's way, in PageTypes.ZwikiStxPageType.renderStxIn (good) and in ZWikiPage.ZWikiPage.markLinksIn (not so good as it's used by all page types). We probably could and should add similar hints to the RST page type. I haven't done much of this since I don't really use RST yet.

2.6 backport --Fri, 05 Mar 2004 15:35:08 -0800 reply

I'm using docutils in other parts of my zope site. I installed a recent docutils snapshop in python's site-packages. It's enough to copy the directory lib/python/reStructuredText to Products/ZWiki/reStructuredText from the 2.6 reSt backport. Since our own RST Article type uses std. doctuils, this is what I'd consider the "clean" way of using reSt with Zope und ZWiki.

reSTX is not simple. --Fri, 26 Mar 2004 04:14:37 -0800 reply

The author of reSTX seem not know other wiki text rule.

usemodwiki's text rule is simple and better.

Linking for jks --Fri, 07 May 2004 09:19:22 -0700 reply

Found this using Plone - a wiki name can be used as the link without the ? showing up by placing an exclamation point before the wiki name in both the reference and target lines, combined with single backquotes around the exclamation point and wiki name in the reference only.

WikiName

RST source? --Mon, 27 Dec 2004 12:04:55 -0800 reply

How can I get the rst source from a wiki page?

... --d2m, Mon, 27 Dec 2004 12:12:17 -0800 reply

  1. use the 'edit' link
  2. in this wiki append /src to the pagename

encoding problem --davo, Thu, 09 Nov 2006 13:03:14 -0800 reply

using latest zope+plone+zwiki (in hosting) if i create a zwiki page using restructured text i can't use italians letter with stress like "รจ". using structured test pages i can. how can i solve the problem?