[Doc-SIG] sub/superscript directive?

[Ueli Schläpfer]

Hi there,

On Fri, 05 Dec 2003 13:02:47 -0500
David Goodger <goodger at python.org> wrote:

> Frank Siebenlist wrote:
> > I'm trying to use the (somewhat undocumented) sub/superscript
> > directives 
[...]
> > in RST, but I always seem to end up with a space between the 
> > sub/superscripted character and the one in front of it in the HTML
> > output.
> 
> I added a tip to the docs: 
> <http://docutils.sf.net/spec/rst/interpreted.html#subscript>.

I just checked it out.  While it's definitely a good thing to see
working examples, they clearly (at least IMHO) violate one of the
primary goals of reST: plaintext readability.  I'd suggest to extend the
tip by at east mentioning substitutions.  As of now, the tip reads:

  .. Tip::

     Whitespace or punctuation is required around interpreted text, but
     often not desired with subscripts & superscripts.
     Backslash-escaped whitespace can be used; the whitespace will be
     removed from the processed document::

         H\ :sub:`2`\ O
         E = mc\ :sup:`2`

     See `the reStructuredText spec`__ for further information.

     __ ./reStructuredText.html#character-level-inline-markup

How about modifying it to something like

  .. Tip::

     Whitespace or punctuation is required around interpreted text, but
     often not desired with subscripts & superscripts.
     Backslash-escaped whitespace can be used; the whitespace will be
     removed from the processed document::

         H\ :sub:`2`\ O
         E = mc\ :sup:`2`

     In such cases, readability of the plain text can be greatly
     improved with substitutions::

       The chemical formula for pure water is |H20|.

       .. |H20|: H\ :sub:`2`\ O

     See `the reStructuredText spec`__ for further `information on
     character-level makeup`__ and on the `substitution mechanism`__.

     __ ./reStructuredText.html
     __ ./reStructuredText.html#character-level-inline-markup
     __ ./reStructuredText.html#substitution-references


-- 
Ueli Schläpfer