[Doc-SIG] RE: reStructuredText

[Garth T Kidd]

>> Given that there's no parser yet, I suppose now is a good time to
>> consider Wiki markup requirements and how they might be added as
>> extensions or incorporated into the specification?
>
> I'm not a Wiki user, so I don't know what special Wiki
> requirements might look like. Can you elaborate?

See QuickWikiBackground_ below for a quick background on what the hell
Wiki is. Skip to WikiModificationsToReStructuredText_ if you just want
to find out what modifications might be required to the reStructuredText
specification.

Just for a play, I'm going to try writing this mail in reStructuredText.

.. _QuickWikiBackground:

QuickWikiBackground
===================

Wiki fans, my apologies if any of this is a tad confrontational or
bordering on flamebait [FlameFlame]_. I'm in a hurry. :/

A Wiki is a web-based content management system that makes buiding web
sites as easy as tunnelling with a magic shovel. Three key reasons for
this ease of use are:

 * Wiki is brower based,
 * Most of what you type in will display properly, and
 * You create links with WordsOfManyCapitalLetters [7]_.

If I'd typed that into a Wiki, what I'd get when I hit the Submit would
be some normal text, a bullet list, and a link called
WordsOfManyCapitalLetters. If I clicked on it, I'd be fed the edit form
for a newly created WordsOfManyCapitalLetters page.

.. _[7]: Properly called WikiNames.

.. _[8]: Purists might want blank lines between those, but I want this
to be as close to copy-and-paste from email as I can get it.

.. _[9]: I first noticed the need for automatic footnote numbering in
footnote [1]_. Now I've finally hit the tangle. I've also just noticed
that if I were rendering this for printing I'd want a different format
for the explicit link to the footnote -- specifically, not a subscript.

.. _[FlameFlame]: This document has so much markup and so many bloody
footnotes [cough]_ it'll be a miracle if anyone manages to read far
enough to find anything worth flaming.

If I referred to DocstringProcessingSystem, that'd become a link, and if
I clicked on it I'd be editing the DocstringProcessingSystem page.

Creating a new Wiki has so little friction the process can become a non
stop brain dump. I created 150+ pages on a ZWiki in spare time between
meetings in a week. I'm sure others have done more.

To have a play with a Python-based Wiki, check out MoinMoin_.

My biggest problem with MoinMoin is that the default markup drives me
nuts (sorry, Jurgen). I have some other issues (see BlogBlog_
[LameLame]_), but my biggest source of angst is probably the parser
issue. MoinMoin supports plug-in parsers, but none of them grab me yet.
See below.

I'm slightly more comfortable with the markup used in ZWiki_, which is
heavily based on StructuredText.

StructuredText has its own problems, though. In short, it's bloody
unpredictable. StructuredTextNG might fix it, and the
BizarStructuredText plug-in contributed to MoinMoin by RichardJones [1]_

reStructuredText_ seems a lot cleaner to me than either StructuredText
or WikiWiki markup. I have marginal concerns about how "normal" people
will cope with the underscore suffix [2]_ for links, but my reading of
the spec was pleasant enough.

What I'd like to do is develop a reStructuredText plug-in parser for
MoinMoin, also one for MoinWiki:BlogBlog [3]_ (which I've decided is
going to pre-parse pages to XML for various reasons)

.. _MoinMoin: http://moin.sourceforge.net/cgi-bin/moin/moin/

.. _BlogBlog: http://moin.sourceforge.net/cgi-bin/moin/moin/BlogBlog

.. _ZWiki: http://zwiki.org/FrontPage

.. _[LameLame]: I've been promising to finish work on a Wiki clone for
years now. I did some work on ZWiki modifications (NooZWiki), which was
fine until I got sick of a) edit conflict error handling in Zope, and b)
the incredible costs of Zope posting at the time. I'm now caught between
extending MoinMoin to suit my purposes -- it's really quite amazing --
or writing my own. I sympathise with anyone tempted to consider me a
mere meddling troublemaker until I finally cough up some code.

.. _NooZWiki: http://zwiki.org/NooZWiki

.. _reStructuredText: http://structuredtext.sf.net

.. _[1]: As you can see, automatically dropping in WikiNames is an easy
habit to fall into -- you'll find yourself doing it accidentally in
email. Whilst I'm in a reStructuredText footnote, however, surely they
should be automatically numbered? [9]_

.. _[2]: The problem is that the underscore becomes a prefix when
finally pointed. If it's confusing me, it's definitely going to confuse
my users. They're going to have enough trouble just with ..
`identifier`: URL.

Is this another paragraph in the [2]_ footnote, or is this in the main
text?

.. _[3]: This is an example of an InterWiki_ link, a streamlined way of
pointing to a particular page at another known Wiki.

.. _InterWiki: http://moin.sourceforge.net/cgi-bin/moin/moin/InterWiki

.. _WikiModificationsToReStructuredText:

Pant. Wheeze. This is hard work. Especially the footnotes.

WikiModificationsToReStructuredText [4]_ [5]_
===================================

Wiki would need the following from reStructuredText:

 * Suddenly, there's markup that doesn't look like punctuation. WikiName
might well end up being a link.

 * As written, a reStructuredText document will always parse the same
way. Once you introduce WikiNature, it'll parse differently depending on
which other WikiNames are defined. [BlogBlogXML]_
[SickOfRememberingNumbers]_ [InternalWikiNames]_

 * Square brackets are extremely useful in ZWiki markup to force a word
that doesn't look like a WikiName to be treated as a link to a page of
that name. For example, [David]. [10]_

 * I dimly remember square brackets also being useful for an inline
linking representation I don't recall from the reStructuredText markup.
It's something like [here is some text: URL]. A more reStructuredText
way of doing it would be something like `here is some text`:URL. [11]_
[12]_

 * MoinMoin further overloads square brackets for an EXTREMELY [6a]_
useful macro system.

.. _[BlogBlogXML]: ... which is why I want to preparse documents to XML
in BlogBlog. <potentialWikiName>, here we come. That brings us back to
predictable output, which I can then reparse to produce appropriate
HTML.

.. _[SickOfRememberingNumbers]: Bah! And now, I'm suddenly wondering
whether underscored link destinations in reStructuredText specifically
use square brackets to say "this is a footnote", or whether that's
handled by the presence of non-URL text after the colon without an
intervening newline.

.. _[InternalWikiNames]: Wouldn't it be nice for other pages in the Wiki
to be able to refer to this footnote as
WhateverThisDocumentIsNamed.InternalWikiNames?

.. _[4]: The `MoinMoin heading style`_ seems to have a lot to offer
reStructuredText, which seems unable to do sub-headings. At least,
having read the spec, I don't remember how to do it -- and the markup
really has to be that simple, hence my problems with the underscores
[1]_ [6]_.

.. _[5]: Another confusion: should the equals signs extend all the way,
or not? I hope not, otherwise users editing with proportional fonts are
going to have an awful time.

.. _[6]: Aha! Sometimes, you need [6a]_ to be able to explicitly target
a previous footnote. Now I'm thinking "named, automatically numbered
footnotes".

.. _[6a]: Hang on, how do I embolden again? Suddenly, the StructuredText
*embolden this* format looks lovely. `embolden this`*? *`embolden
this`*?

.. _`MoinMoin heading style`:
http://moin.sourceforge.net/cgi-bin/moin/moin/HelpOnHeadlines

.. _[10]: Some Wikis scan any word with an initial capital to see
whether or not there's a page of that name, in which case you only need
the square brackets to force a link to the uncreated page when you're
first creating it.

.. _[11]: I like the backquotes!

.. _[12]: We need to also consider `here is some text`:WikiName.

My brain hurts. This is harder than it looks. I should never [6a]_ have
started with the footnotes. :)

Regards,
Garth.

.. _[cough]: You are in a twisty maze of little passages, all alike.