[Doc-SIG] RE: reStructuredText

[Garth T Kidd]

More time-wasting goodness. Thankfully, a short "yup" will straighten
most of it out.

 - `subjects with momentum`_
   - `multiply indirect links`_
   - `general coding attitude`_
   - `embedding directives mid-paragraph`_
   - `alternative heading format`_
   - `block quotes and literal blocks in list items`_
   - `miscellaneous`_

 - `tying up loose ends`_

I'm leading with the items that have a bit of momentum. I've bumped to
the tail end of the message all of the knotted loose ends: the yeps,
the uh-huhs, and the oopses. Paragraph indentation, I put in a
completely different message; it looks like it could take a while.

If reading my email in reStructuredText 0.2.2 is driving anyone nuts,
please let me know.

.. _subjects with momentum:

Kicking off with the momentum:

.. is that English? :)

.. _multiply indirect links:

    Multiply-indirect hyperlinks? Interesting idea. I don't know
    if it's worth the trouble though.

Collapsing multiply indirect links seems clean and trivial. Why not? :)

That said, it's not necessarily *important*, so feel free to leave it
in the pile of features labelled "Garth can code these if he wants
them so bloody badly."

.. _my general coding attitude:

In general, if it's easier to make the parser accomodate a user
behaviour than to persuade the users to select another behaviour, I'll
consistently be in favour of changing the parser.

That doesn't override my insistence on clean code, especially if it's
hanging out there in public. If I can't do it without tangling the
parser, I'll hold off until I can figure out a way to refactor it
cleanly.

Finally, I don't mind putting my code where my mouth is.

.. That almost ended up "... don't mind putting my keyboard where my
   mouse is." I clearly need more sleep than I'm getting.

Summary:

* If it's easier to change the code's behaviour than change the
  users' behaviour, change the code.

* Writing dirty, ugly code is harder than changing user behaviour.

* If it's not obvious whether the code is going to be clean or not,
  I'll find out by trying to write it.

.. _embedding directives mid-paragraph:

        Embedding directives mid-paragraph...

    Could be done with interpreted text. But is it really necessary?
    Could you provide some examples?

If I had an example in mind, I've since forgotten it.

Howabout we nail down how to hand a block of text to a directive, and
then leave messy stuff like doing something unusual mid-paragraph to
application-specific directives. If it turns out to be mind-blowingly
popular, it can be factored in later.

.. _alternative heading format:

        I *really* like MoinMoin's use of a number of equals signs
        on each side of a paragraph [to indicate a heading]: if the
        number of equals signs is the same, the paragraph is a
        heading of ident level equal to the number of equals signs.

    It's a workable alternate syntax.

Yep.

.. _block quotes and literal blocks in list items:

On block quotes and literal blocks in list items, which I still find
mildly confusing (at least, when I'm typing -- my fingers aren't used
to it yet, if you know what I mean):

        I would hope that the reStructuredText parser is smart enough
        to figure out that the example text above is part of the <li>
        above?

    Once you indent the list item's paragraph, and further indent the
    example text, yes. :-)

I keep forgetting the extra indents. Just to confirm::

    - list item

      new paragraph in list item::

        literal block in list item

      .. outdented comment to force the end of the literal block

        block quote in list item

     block quote outside of list item (oops!)

    - another list item

.. _miscellaneous:

A few quick questions:

* If I accidentally indent a bullet list, does that become a bullet
  list inside a block quote? ::

    I'm not sure whether the following is a bullet list at the same
    level as this paragraph, or a bullet list inside a block quote:

     * Anyone? Anyone? Bueller?

  I suspect the answer is: yes.

* Does the specification implicitly or explicitly support the use of
  an outdented comment to force the end of an indented block, as
  above?

  I suspect the behaviour isn't yet defined.

.. tying up loose ends:

tying up loose ends
-------------------

We turn out to completely agree on the following:

* Treating unresolved links as opportunitities to create a new
  page is up to Wiki, not the parser.

* Suppressing page creation for unresolved link destinations that
  would make wierd page names is also up to Wiki.

I've discovered the following blunders:

* Inline URL specification for links is too ugly to bear::

    `download Python 2.1`:http://www.python.org/2.1/

  I must have missed the word "rejected" at the time. My blunder.

* Interpreted literals and literal interpretation::

    Find the `` `interpreted text` `` in this paragraph!

  What was I on?

Regards,
Garth.