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

[Garth T Kidd]

Some quick WikiNotes:

>> 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).

Wikis are pleasantly relaxed beasts, and as such I'd be entirely happy
for *my* Wiki to concatenate all words in the link text, strip
punctuation, and perform a case-insensitive search for matching page
names.

That's just me, though.

Fortunately, the choice doesn't have to be made by the reST parser. Link
resolution is up to the application. Some WikiClone developers might
choose to always be relaxed, others might decide to be WikiFascists and
insist that CamelCase always be used, and still others might leave it as
a configurable option for the WikiOwner to decide on.

In bullets for easy readability:

* reST defines any single word with a trailing underscore as a link.

* reST also defines any ```backquoted phrase``` with a trailing
  underscore as a link.

* The WikiClone application can decide whether or not a given link
  resolves to a heading in the document, another part of the document,
  a footnote, another WikiPage, another part of another WikiPage, a
  page on another Wiki via InterWiki, whatever the application wants.

In short, WikiNames are Somebody Else's Problem.

> 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.

Absolutely.

> which can cache the XML version of the parser output

Yup!

This is where the decision to *not* have reST resolve links really
shines. The parser output for a particular page doesn't change
regardless of what happens to other pages in the Wiki. When someone asks
for the page, the formatter simply runs the XML through an appropriate
transform (resolving links at run-time) and splits it out.

Schrodinger's links, anyone? :)

David, it just occurred to me that [most? all?] directives should simply
be parsed and embedded in the output for the application to handle.

> *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.

That's up to the formatter, not the parser. It doesn't make much
difference to the users of the system, but it keeps the parser a whole
lot simpler.

Pile a lot of WikiUsers and ask them about tweaking the page naming
standard, and you'll end up with MuchWailingAndGnashingOfTeeth that
could last for weeks. Let's let them thrash on their time, not ours. :)

> (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.

That happens to me, too.

Regards,
Garth.