[Doc-SIG] Re: reStructuredText Markup Specification

[David Goodger]

on 2001-06-03 18:48, Doug Hellmann (doughellmann@bigfoot.com) wrote:
> I'm a bit confused (after only a single reading) by the 'some text'_
> formatting that looks prevalent here.

It's actually `some text`_ (backquotes, chr(96), not straight quotes). Yes,
I know, in some fonts they're indistinguishable. I submit that it's
irrelevant that it's so, even elegant. To the reader, they look like quotes,
which is what they're doing. Now, if you're *writing* or *editing*
docstrings in code, your font had better distinguish between *all*
characters.

> Are those internal references to anchors within the document?

Yes. The trailing underscore is the hyperlink reference-indicator. The
quotes are necessary to group the space-separated words together as a
'phrase-link'; otherwise, only the last word would be considered the link
name.

> It looks a bit, um, maybe dirty is the word, I
> don't know.  What about using [] or {}?

Actually, the first draft of the spec (you've just read the second draft)
used square brackets for phrase-links. They're OK, but more prominent than
backquotes. I changed my mind because:

1. I had already decided on single-backquotes for inline literal text.

2. However, I wanted to minimize the necessity for backslash escapes, for
   example when quoting Python repr-equivalent syntax that uses backquotes.

3. The processing of identifiers (funtion/method/attribute/module/etc.
   names) into hyperlinks is a useful feature. PyDoc recognizes identifiers
   heuristically, but it doesn't take much imagination to come up with
   counter-examples where PyDoc's heuristics would result in embarassing
   failure. I wanted to do it deterministically, and that called for syntax.
   I called this construct 'interpreted text'.

4. #2, combined with the *emphasis*/**strong** syntax, lead to the idea of
   using double-backquotes as syntax.

5. I worked out some rules for inline markup recognition.

6. Double backquotes in combination with #5 minimizes backslash escapes, so
   that lends itself to inline literals. In fact, the spec says that no
   interpretation of any kind is done within double-backquote inline literal
   text; backslashes do *no* escaping within literal text.

7. Single backquo;tes are then freed up for interpreted text.

8. I already had square brackets required for footnote references.

9. Since interpreted text will typically turn into hyperlinks, it was a
   natural fit to use backquotes as the phrase-quoting syntax for
   trailing-underscore hyperlinks.

By the way, the trailing underscore syntax comes from Setext. For phrases it
used underscores_between_words_like_this_, including the trailing
underscore.

> Maybe I'm just bothered that the
> single trailing or preceding _ is unbalanced.

I see the underscores as if they were right-pointing arrows: '-->'. So
'hyperlink_' points away from the reference, and '.. _hyperlink' points
toward the target.

> I'll read through again and
> see if a second pass makes this more clear to me.

Please do; I look forward to your comments.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net