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

[Garth T Kidd]

Go to sleep! :)

> > I think we should make footnote identifiers (excepting the square
> > brackets) implicit hyperlink targets in their own right. Amongst
> > other things, annotations and sidebars would then be able to
> > refer to footnotes.
>
> They already are::
>
>     This is how you refer to a footnote: [label]_.
>
> You can do this any number of times, from anywhere.

Let's say that I'm trying to use reST in a system designed to facilitate
development of a document that will eventually be printed as a book, and
the author has made a footnote::

  Compatriots described him as "tired and emotional" [1]_.

  .. _[1] or, as they say in showbiz, drunk.

To be as transparent as possible to the reST-using authors, the HTML
might be something along these lines::

  Compatriots described him as "tired and emotional"
  <a href="#1">[1]_</a>

  [... later ...]
  <hr align="left" width="20%">
  <table witdh="100%">
    <tr>
      <td width="5%">1</td>
      <td width="95%"><a name="1">or, as they say in showbiz,
        drunk.></a></td>
    </tr>
  </table>

We might need a later footnote to refer to the footnote. With the
existing syntax, that's easy, as you point out::

  He merrily [5]_ wandered outside to the garden and continued

  .. _[5] or, as they say in showbiz, tired and emotional. See
     also footnote [1]_.

Unfortunately, in the printed representation that'll come out as::

  5  or, as they say in showbiz, tired and emotional. See also
             1
     footnote .

Oops.

If we unify the namespace and treat the square brackets as delimiters
only, not part of the identifier, a printable representation is easy:

  .. _[5] or, as they say in showbiz, tired and emotional. See
     also footnote 1_.

That syntax is slightly less ghastly than the workaround:

  .. _footnote 1:

  .. _[1] or, as they say in showbiz, drunk.

  .. _[5] or, as they say in showbiz, tired and emotional. See also
     `footnote 1`_.

Hmmm. I might be guilty of making the common case more difficult, here,
by trying to combine the namespace. The workaround frankly isn't that
difficult now that I look at it.

Regards,
Garth.