reST Wiki mode, was [Doc-SIG] Suggestions for reST "modes"
Garth T Kidd
garth@deadlybloodyserious.com
Tue, 7 Aug 2001 16:09:21 +1000
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.