The exisiting implementation of StructuredText in Zope has several disadvantages: - its behaviour depends on the locale settings (letters and punctuation is taken from the locale settings). In some case the locale settings are imcomplete (characters ¡ and ¿ are not available through the locales as puncuation characters). - the behaviour of STX is not very well defined (what are allowed letters, what are allowed punctuation characters...) With the upcoming importance of reStructuredText (PEP 12) there is a real need for a better StructuredText implementation for Zope. reStructuredText solves these problems by using a reasonable specification and by avoiding ambiguities. RIchard Jones also implemented a first version of a reStructuredDocument product. I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run. Open points: how to migrate exisiting STX documents to reStructuredText Cheers, Andreas --------------------------------------------------------------------- - Andreas Jung http://www.andreas-jung.com - - EMail: andreas at andreas-jung.com - - "Life is too short to (re)write parsers" - ---------------------------------------------------------------------
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
+1
Open points: how to migrate exisiting STX documents to reStructuredText
Wouldn't the simplest solution be: <dtml-var content format=rest> ??? Then we could use both interchangably. regards Max M "Skeptic Effect" or the "Randi Effect" When a skeptic is near, supernatural effects seem to disappear. ><evolve> > >
[courtesy cc send to David G, so if I make any blatantly errneous statements he can come chase me with the Big Stick :)] On Wed, 4 Sep 2002 8:01 pm, Max M wrote:
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
+1
+1 but with the reservations below :)
Open points: how to migrate exisiting STX documents to reStructuredText
Wouldn't the simplest solution be:
<dtml-var content format=rest> ???
Then we could use both interchangably.
One of the big issues is that rest isn't optimised. I don't know what the scope is for optimising rest, nor have I got any real benchmark numbers. The emphasis so far has been to build it to spec. It's potentially much slower than stx because the latter has been around for longer and therefore is potentially more tweaked. The ReStructuredText Document works because I compile the source text into HTML when it's written. Nice and fast, and works well in content management environments. In the above DTML tag usage though, you'd want "content" to be quite small or the performance hit could be large. I believe migration may be possible - that is, the parser half of rest might be mutable enough to make it handle stx blocks and other syntax eccentricities. That's a question for David Goodger to answer really. As I understand it though, there's ambiguities in stx that the rest parser might not interpret in the same manner as the stx parser. The docutils/rest project has an analysis of the stx format: http://docutils.sourceforge.net/spec/rst/problems.html Richard
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
My two cents - there are some things in rST I would like to have but I think it has gone too far with it's rules. If I had to choose one or the other right now I would stick with stxNG for simplicity and because it doesn't dictate things unnecessarily. I think the number one problem with stx for most people is the indenting hassle. These markups are evolving and I don't think we've seen the best designs yet. http://repose.cx/emacs/wiki/wikimarkup.pt is another which feels good to me, check it out. -Simon
IMHO, the indenting hassle is one of the best features of "classic" STX. It's a pain to line things up but it does make for very readable source documents. I think STX-NG is a little better than ReST for constructing readable source docs; especially if they are long, like chapters of a book due to this indenting. I would agree that if the source doc is less important than its rendering to HTML (or another format), reST has STX beat in many areas. ReST also has an enormous amount of specification and documentation, which counts for a lot. Personally, I will likely stick with STX-NG as well (at least for the foreseeable future), because I am comfortable with its weaknesses and I also have a fairly large corpus of documents that are written in STX and there has not yet been written (that I know of) a classic-STX-to-reST converter. - C ----- Original Message ----- From: "Simon Michael" <simon@joyful.com> To: <zope-dev@zope.org> Cc: "David Goodger" <goodger@users.sourceforge.net> Sent: Wednesday, September 04, 2002 12:24 PM Subject: [Zope-dev] Re: Future of StructuredText
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
My two cents - there are some things in rST I would like to have but I think it has gone too far with it's rules. If I had to choose one or the other right now I would stick with stxNG for simplicity and because it doesn't dictate things unnecessarily.
I think the number one problem with stx for most people is the indenting hassle.
These markups are evolving and I don't think we've seen the best designs yet. http://repose.cx/emacs/wiki/wikimarkup.pt is another which feels good to me, check it out.
-Simon
_______________________________________________ Zope-Dev maillist - Zope-Dev@zope.org http://lists.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope )
On 9/4/02 10:59 AM, "Chris McDonough" <chrism@zope.com> wrote:
IMHO, the indenting hassle is one of the best features of "classic" STX. It's a pain to line things up but it does make for very readable source documents. I think STX-NG is a little better than ReST for constructing readable source docs; especially if they are long, like chapters of a book due to this indenting.
When writing books, however, you're most likely using an editor that makes it easy to reformat blocks at the proper indentation level. For a lot of web input where you still want to allow some simple structure, indentation is a pain in the ass. I do it because I'm used to it, but a lot of people just will type in a paragraph as a single line. Most of the time, this is fine in Structured Text, until they indent one of the paragraphs even by one space, turning the parent paragraph into a header block. The indentation in STX is especially annoying when trying to drop in example code, most likely pasted in from another source, and having to then move every line to the right level - thus, code that was formatted to fit well in eighty columns can be tricky to fit into an eighty column source STX document if it's a few sublevels in. I still have to find the right level, mix of colons and spacing, etc..., after all these years. -- Jeffrey P Shell www.cuemedia.com
On Wed, 4 Sep 2002, Jeffrey P Shell wrote:
When writing books, however, you're most likely using an editor that makes it easy to reformat blocks at the proper indentation level. For a lot of web input where you still want to allow some simple structure, indentation
It would be really sad if the quality of a format were limited by the fact that web browsers aren't smart enough to launch real editors for editing text fields. It may be necessary, but it would be really sad. So if that is a ruling criterion, I'd vote for two versions of structured text, preferably with a translator between them. NB: having looked briefly at the rest usage guide, I must say that I agree that all this anchor-plus-separate-line-with-the-real-info stuff does *not* appeal to me. --RDM
"R. David Murray" <bitz@bitdance.com> writes:
it would be really sad. So if that is a ruling criterion, I'd vote for two versions of structured text, preferably with a translator between them.
Well, it would be easy enough (or maybe not, with current stx code) for structured text to accept either indentation or rST-style underlining to indicate headers. I wonder if it's possible to design a system that doesn't require indentation at all, but allows it as an alternate mechanism - without causing more confusion.
On Thu, 5 Sep 2002 2:24 am, Simon Michael wrote:
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
My two cents - there are some things in rST I would like to have but I think it has gone too far with it's rules.
This seems to be a common argument, and I honestly can't understand it. I'm not going argue it here, I'll just point you all to the "primer" document which outlines the basics of ReST: http://docutils.sourceforge.net/docs/rst/quickstart.html Richard
Richard Jones wrote:
[courtesy cc send to David G, so if I make any blatantly errneous statements he can come chase me with the Big Stick :)]
Thanks for being a vocal proponent!
On Wed, 4 Sep 2002 8:01 pm, Max M wrote:
Andreas Jung wrote:
I would be fine to have reStructuredText inside the Zope core (for 2.7) and to deprecate the current StructuredText in the long run.
+1
+1 but with the reservations below :) ... One of the big issues is that rest isn't optimised.
This is true. Optimization isn't even on the radar at this point, although I'd be more than happy if someone were to take a look at it.
The emphasis so far has been to build it to spec.
True. That's why there *is* a spec, and why the spec preceded the implementation. Even after the implementation of the initial feature set, whenever new features were added the spec was always updated first. One of my biggest problems with ST was its spec, or lack thereof.
It's potentially much slower than stx because the latter has been around for longer and therefore is potentially more tweaked.
I'd say ST (classic, anyhow; never grokked the NG code) is faster simply because it does much less. ;-)
I believe migration may be possible - that is, the parser half of rest might be mutable enough to make it handle stx blocks and other syntax eccentricities. That's a question for David Goodger to answer really.
Compatibility with ST was never a consideration; I took the good ideas and left the rest. Except for section structure, reStructuredText is mostly a superset of ST, but there may be some gotchas. The reStructuredText parser is built generically enough that it could (with recoding) handle ST as well. I don't see the need though.
As I understand it though, there's ambiguities in stx that the rest parser might not interpret in the same manner as the stx parser.
There's ST's use of 'o' as bullet list marker, for one. Footnotes & footnote references are different, as are hyperlinks in general. There are others I'm sure. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
----- Original Message ----- From: "David Goodger" <goodger@users.sourceforge.net> To: "Richard Jones" <rjones@ekit-inc.com>; "Max M" <maxm@mxm.dk>; "Andreas Jung" <andreas@andreas-jung.com> Cc: <zope-dev@zope.org> Sent: Thursday, September 05, 2002 06:35 Subject: Re: [Zope-dev] Future of StructuredText
It's potentially much slower than stx because the latter has been around
for
longer and therefore is potentially more tweaked.
I'd say ST (classic, anyhow; never grokked the NG code) is faster simply because it does much less. ;-)
In deed - on the other side you could work with caches. Either on the restructuredText side to keep the cooked HTML, or you as RAM manager on the Zope level or Apache/Squid before the Zope instance. -aj
Richard Jones wrote:
One of the big issues is that rest isn't optimised. I don't know what the scope is for optimising rest, nor have I got any real benchmark numbers. The emphasis so far has been to build it to spec. It's potentially much slower than stx because the latter has been around for longer and therefore is potentially more tweaked. The ReStructuredText Document works because I compile the source text into HTML when it's written. Nice and fast, and works well in content management environments. In the above DTML tag usage though, you'd want "content" to be quite small or the performance hit could be large.
Well I have seen the alternative... and it isn't nice! The users happily paste in 300KB of obscure html from word. Html that is about 15 KB when run through Tidy that is! Besides, most of the stx documents I see my users paste in in real life is a few KB worth of text. Max... And the advantage is that REST has a syntax that is much closer to what ordinary users expect. In userland indentation is actually a hard problem. regards Max M "Skeptic Effect" or the "Randi Effect" When a skeptic is near, supernatural effects seem to disappear. ><evolve> > >
On Thursday 05 September 2002 03:45 am, Max M wrote: [snip]
In userland indentation is actually a hard problem.
regards Max M
http://lists.zope.org/mailman/listinfo/zope ) Indeed, most normal humans have trouble with understanding nested hierarchies. Something which we geeks often cannot understand since we surround ourselves with them. -Casey
participants (9)
-
Andreas Jung -
Casey Duncan -
Chris McDonough -
David Goodger -
Jeffrey P Shell -
Max M -
R. David Murray -
Richard Jones -
Simon Michael