[Doc-SIG] RE: reStructuredText

[Garth T Kidd]

It just occurred to me:

The lowest friction implementation for a Wiki using reStructuredText is
to implicitly assume that if a _ target doesn't exist in the current
document, the link must be intended to refer to another document in the
system.

This would still require people to add the _ suffix for anything they
want linked, but would eliminate the concerns about non-punctuation
markup and ways of forcing links to pages whose names aren't that
WikiLike. I'm concerned, however, that people could end up with some
truly wierd names::

  See `the rest of my documentation on the fnarzle system`_ for more
  details.

... would imply a page named "the rest of my... system". I think it's a
tad ugly, and that it might encourage slackness that
WikiNamesOfTooManyWordsLookVerySilly tends to implicitly suppress. :) On
the other hand, the system can always refuse to create pages of such
names.

This brings me back to the potential need for a "short form" of the link
syntax. Consider an attempt to have the above example link to a more
reasonably named FnarzleDocs::

  See `the rest of my documentation on the fnarzle system`_ for more
  details.

  .. _`the rest of my documentation on the fnarzle system`: FnarzleDocs_

... with FnarzleDocs_ being unresolved within the current document,
resolving to an in-system URL, and collapsed by the parser into a single
link with the appropriate text.

I think my users would prefer::

  See `the rest of my documentation on the fnarzle system`:FnarzleDocs
  for more details.

BTW, I just found the section in the spec that permits::

  I think you should `download Python 2.1`:http://www.python.org/2.1/
  before you touch that ugly Perl code.

... which makes my suggestion look fairly reasonable.

Miscellaneous concerns:

 - embedding directives like includes or macro calls mid-paragraph.

 - being able to recognise indented paragraphs solely by their first
line, so that people can lazily just keep typing (like I'm doing now)
without having to manually terminate lines and indent the next one. The
behaviour is arguably implied by the specification ("This is a paragraph
continuation, not a sublist"), but I'd love explicit confirmation
because it might be argued that an outdent implicitly terminates the
previous paragraph but an indent doesn't. Needless to say, I'd argue
against that.

 - underlined style headings; I *really* like MoinMoin's use of a number
of equals signs on each side of a paragraph: if the number of equals
signs is the same, the paragraph is a heading of ident level equal to
the number of equals signs. For example::

  = this is a level 1 heading =

  == this is a level 2 heading ==

  == this is also a level 2 heading
  despite the fact that it has been
  wrapped for some reason ==

  === this is not a heading because the number of equals signs isn't
  equal <ahem>. ==

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

 - What's wrong with an automatically wrapped comment block like the
following? ::

  .. This would be a comment block except
  this line hasn't been indented
     because some client re-wrapped the
  lines. Damn!

 - I'm trying to figure out how to refer to a target within another
document:

    - \`hyperlink targets`_ in the spec refers to the appropriate
heading;
    - \`the specification`_ could refer to the spec if there was an
appropriate target specification later in the document::

        .. `the specification`: reStructuredText

       (implicitly targeting the reStructuredText peer of the referrer);

    - \`the specification`:reStructuredText could do the same given the
[mild] extension I suggested earlier;

    - Using a dot as a delimiter could be treaded by the link resolver
as an implied sub-target::

       See `hyperlinks`:reStructuredText.`hyperlink targets`.

       ... but that starts to get ugly.

   You can see why it's worrying me. :)

 - I hope the parser is able to deal with paragraphs inconveniently
wrapped in the middle of some emphasis::

     This is *emphasised
     text* with an
     inconvenient wrap
     point.

   ... otherwise I'd need an option to require delimiting the text::

     This is *`emphasised
     text`* with an...

   ... a shortcut for which could be::

     This is `emphasized text`* with an...

   ... which matches nicely with the link syntax, at least if you don't
need to embold the link, which sometimes I do::

     This is an `emphasized link`*_ with an...

   That's not as ugly as I thought it would be.

 - Leading and trailing whitespace should be trimmed from inline
literals so that someone can do this::

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

If I should just make up my own mind on each and submit a diff per to be
discussed|debated|mangled, someone let me know, okay? :)

Regards,
Garth.