reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes"

[Tony J Ibbs (Tibs)]

OK - I'm in *no* way the official Wiki person here (erm - Garth started
this I think?) but that sort of consideration has never stopped me
jumping in with two left feet before...

Ken Manheimer [mailto:klm@zope.com] wrote:
> Wiki name misfires are probably among the biggest sources of user
> irritation i see - making their cues more explicit, as tony suggests,
> is a real good idea.

Oh, I don't know - the few times I've used a Wiki, I find the "?" links
rather cute (but, of course, I *am* one of those people who like filling
them in, and if someone has left potentially facetious "uncured" links,
then they deserve what they get...).

> Even with this explcit cue i would not want to then relax the
> wiki name form, however.

It is rather cute.

> Further, in systems like Zope where the page names are useful
> in URLs for getting directly to the pages, "%20" for spaces
> and other punctuation presents big, ugly obstacles.

Agreed (although that's a problem with URIs, not the user).

> The short story:
>
>   - WikiName unadorned is just regular text, not specially recognized.

Makes sense.

>   - [WikiName] is a wiki name - it must be camel case, no
> whitespace, etc.
>
>   - [Any Old Phrase] or [word] or [Word], etc, are plain text, not
>     specially recognized.
>
>   - If you must, you can use doubled '[[...]]' braces to force
>     arbitrary phrases to WikiName-hood.
>
> I haven't gotten to learning reST, and am not sure whether square
> braces already have some special significance.

They mean footnotes - so [1]_ is a footnote reference (a la PEPs, sort
of).

> I'd love to reserve
> them for the purpose of wiki names ("common names"), since that's
> sorta congruent to the way they're used in wikis (at least, ZWiki).

OK - here's my take on this (warning: I'm not a longterm Wiki user!).

The canonical "this is a link" meme in reST is word_ or `two words`_
(i.e., using backquoted strings before the underline if there is a space
within the link term).

Thus it would be natural to say that links that are not satisfied in the
document (as those two above are - see below) should be *potential* Wiki
links - i.e., that the Wiki engine should be free to consider them.

As I understand it, the "traditional" Wiki scheme is that:

- ``CamelWord`` is a link - we'd thus do that as "CamelWord_"
- ``!CamelWord`` is not a link - we'd do that as "CamelWord"
- ``[notcamelword]`` is a link - we'd naturally do *that*
  as "notcamelword_"

What you seem to be saying is that you'd like to try to stop the user
from doing the last one. Since it's easy for them to do it in a
traditional Wiki anyway, I'm not sure that's a good way to go in reST,
but...

Another reST/DPS concept is that of "warning levels" (I think of them as
equivalent to the old VMS info/warn/error/fatal levels, but David labels
them 0/1/2/3). It should, I hope, be "normal" for levels 1 and up to
insert appropriate information in the output so that the user can tell
that the error has occurred (certainly for 2 and up).

*So* - if one says that non-CamelWords are not the preferred option, it
would be "reST-compatible" to flag them with a (visible) warning in the
output.

Alternatively, one might require that the user click a checkbox on the
Wiki interface page (for instance) to enable such links in their page -
after all, the Wiki software is in charge of processing the intermediate
DOM tree to produce the final HTML, so it can decide what to do with the
links on a "supported/not supported" manner for each page.

This last might be the way to go within ZWiki, if the default state for
the button is unchecked.

.. _[1] this is the footnote from above.
.. _word: an in document target for our word.
.. _`two words`: ditto for out two words.
.. comment:: Note there is *no* in document target
   for the link ``CamelWord_``, nor for ``notcamelword_``.

> (I'm not sure if and how reST will be fit into Zope, but i'd certainly
> like to keep that option open.)

Although not the same structure as STNG, and not using the same DTDs,
reST/DPS will be producing a DOM tree as its "intermediate output
phase", just like STNG does. So one can leverage off that (hah - anyone
suggesting going DTD -> XMLSchema -> XSLT -> STNG-SMLSchema -> STNG-DTD
peobably has too much time on their hands!). I assume it would be fairly
easy to adapt to using reST instead of ST/STNG.

(Hmm - potentially two Pythonesque Wikis going to reST [2]_ - this could
be Nice).

.. [2] Erm, I didn't mean that to sound the way it can be read!

Tibs

(David - maybe we *should* be having a colon after a footnote target - I
find it very confusing not to - I keep typing them and then removing
them. Since one can (sort of) consider them as being like "`" and "`"
around a multi-word link name, does that make sense?)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)