[Zope-CMF] Re: reStructuredText

Thu, 24 Oct 2002 13:42:11 -0600

On Thursday, October 24, 2002, at 09:11  AM, Florent Guillaume wrote:

> Regarding StructuredText / reStructuredText:
>
> Actually if this is a tool to give to users, both of those are much too
> complicated, and there is too much magic in them. A plain user doesn't
> want things 'like that' to appear in <code>, or things "like that": to
> appear like a link. Way too much magic. Also underline is rarely used,
> stars don't delimit text well enough, etc.

There's no such thing as a plain user.  That's too broad of a term, but 
I do understand what you're talking about.  I've decided to punt on the 
issue altogether, use 'newline_to_br' type formatting, and let the 
structure of headers and such come out of a compound document (the 
still-not-public FDoc framework), which has special Part editors for 
lists of links, images, and so on.

> STX/reSTX is good for power users, but that's hardly the majority of my
> clients' users. What I want (and will end up writing at some point) is 
> a
> very very simplified form of STX, that provides headers, paragraphes,
> lists, links, but with *very* explicit markup.

So in other words - basic "classic" HTML?  :)  Or something like the 
markup used in UBB (Ultimate Bulletin Board), which respects 
paragraphs, and gives a simplified set of basic HTML tags using square 
braces? [b]bold[/b]...

Once you go to very explicit markup, why not teach the client simple 
HTML?  <li> for list item, <b> for bold, <i> for italics, and use 
something like Strip-O-Gram to keep the list of allowed HTML in check?  
Links... Well, links are a little funnier.

Ultimately, you have to teach the users *something*.  The only thing 
that can really be automatic and instantly learnable is paragraph 
detection, so why not just allow/teach very simple HTML?

Unless you keep a markup feature set and scope EXTREMELY limited, you 
end up inventing another HTML or Structured Text with its own funky 
syntax.  I've seen this happen time and time again over the past six 
years as scope creep and user smarts for different products have grown 
over time.  Then ultimately, the systems became too complex and someone 
starts over with something simple that grows and grows and grows until 
it too is too complex and ... :)

> For those who read French, here's an example of the syntax another
> PHP-based system (SPIP) uses:
> http://arcoweb.free.fr/article.php3?id_article=125

Aside from lack of indentation (and I think STX's indentation is a 
terrible thing to expect over the web), it seems like 
just-another-structured-text.  Instead of *italic*, it's {italic}, 
**bold** becomes {{bold}}, etc.  And the documentation (at least, as 
translated to english by Mac OS X's Sherlock 3) is too peppered with 
the word 'simply' - In SPIP, one very simply indicates them while 
placing them between triple accodances: "{{{a title of part}}}".  Once 
you have to start learning these rules, again, why not say "very simply 
say <b>boo</b>"?

All of these structured text languages for me break down very quickly 
once you start trying to do advanced structure without trying to let on 
that you're doing advanced structure.  And they all seem to preclude 
that you'd ever want to type any of the symbols they've taken over on 
their own.  In structured text, it's very hard to type '2 * 2 = 4' 
inline in a paragraph.  If one were talking about mathematical in SPIP, 
it looks like they'd have to do <HTML>{1, 3, 5, 7, ...}</HTML> (of 
course, in HTML saying 3 < 29 has to turn into 3 &lt; 29)...

*sigh*

So, if you just allow very basic HTML (the classic structural HTML), 
your instruction time for users would probably be the same.  And, you 
leave yourself open to the possibility of using WYSIWYG-ish editors in 
the browser if you have a situation that allows it.