[Structuredtext-checkins] CVS: restructuredtext/spec problems.txt,1.7,1.8

[David G. <go...@us...>]

Update of /cvsroot/structuredtext/restructuredtext/spec
In directory usw-pr-cvs1:/tmp/cvs-serv12674/restructuredtext/spec

Modified Files:
	problems.txt 
Log Message:
Fixed whitespace & updated

Index: problems.txt
===================================================================
RCS file: /cvsroot/structuredtext/restructuredtext/spec/problems.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** problems.txt	28 Mar 2002 04:27:44 -0000	1.7
--- problems.txt	18 Apr 2002 02:42:56 -0000	1.8
***************
*** 8,12 ****
  
  There are several problems, unresolved issues, and areas of
! controversy within StructuredText_ (Classic and Next Generation). In
  order to resolve all these issues, this analysis brings all of the
  issues out into the open, enumerates all the alternatives, and
--- 8,12 ----
  
  There are several problems, unresolved issues, and areas of
! controversy within StructuredText_ (Classic and Next Generation).  In
  order to resolve all these issues, this analysis brings all of the
  issues out into the open, enumerates all the alternatives, and
***************
*** 14,18 ****
  specification.
  
! 1. No `formal specification`_. The code *is* the standard.
  2. `Understanding and extending the code`_ is difficult.
  3. `Section structure via indentation`_.
--- 14,18 ----
  specification.
  
! 1. No `formal specification`_.  The code *is* the standard.
  2. `Understanding and extending the code`_ is difficult.
  3. `Section structure via indentation`_.
***************
*** 34,45 ****
  
  The description in the original StructuredText.py has been criticized
! for being vague. For practical purposes, "the code *is* the spec."
  Tony Ibbs has been working on deducing a `detailed description`_ from
! the documentation and code of StructuredTextNG_. Edward Loper's
  STMinus_ is another attempt to formalize a spec.
  
  For this kind of a project, the specification should always precede
! the code. Otherwise, the markup is a moving target which can never be
! adopted as a standard. Of course, a specification may be revised
  during lifetime of the code, but without a spec there is no visible
  control and thus no confidence.
--- 34,45 ----
  
  The description in the original StructuredText.py has been criticized
! for being vague.  For practical purposes, "the code *is* the spec."
  Tony Ibbs has been working on deducing a `detailed description`_ from
! the documentation and code of StructuredTextNG_.  Edward Loper's
  STMinus_ is another attempt to formalize a spec.
  
  For this kind of a project, the specification should always precede
! the code.  Otherwise, the markup is a moving target which can never be
! adopted as a standard.  Of course, a specification may be revised
  during lifetime of the code, but without a spec there is no visible
  control and thus no confidence.
***************
*** 50,55 ****
  
  The original StructuredText_ is a dense mass of sparsely commented
! code and inscrutable regular expressions. It was not designed to be
! extended and is very difficult to understand. StructuredTextNG_ has
  been designed to allow input (syntax) and output extensions, but its
  documentation (both internal [comments & docstrings], and external) is
--- 50,55 ----
  
  The original StructuredText_ is a dense mass of sparsely commented
! code and inscrutable regular expressions.  It was not designed to be
! extended and is very difficult to understand.  StructuredTextNG_ has
  been designed to allow input (syntax) and output extensions, but its
  documentation (both internal [comments & docstrings], and external) is
***************
*** 58,62 ****
  For reStructuredText to become truly useful, perhaps even part of
  Python's standard library, it must have clear, understandable
! documentation and implementation code. For the implementation of
  reStructuredText to be taken seriously, it must be a sterling example
  of the potential of docstrings; the implementation must practice what
--- 58,62 ----
  For reStructuredText to become truly useful, perhaps even part of
  Python's standard library, it must have clear, understandable
! documentation and implementation code.  For the implementation of
  reStructuredText to be taken seriously, it must be a sterling example
  of the potential of docstrings; the implementation must practice what
***************
*** 67,79 ****
  =================================
  
! Setext_ required that body text be indented by 2 spaces. The original
  StructuredText_ and StructuredTextNG_ require that section structure
! be indicated through indentation, as "inspired by Python". For certain
! structures with a very limited, local extent (such as lists, block
! quotes, and literal blocks), indentation naturally indicates structure
! or hierarchy. For sections (which may have a very large extent),
! structure via indentation is unnecessary, unnatural and ambiguous.
! Rather, the syntax of the section title *itself* should indicate that
! it is a section title.
  
  The original StructuredText states that "A single-line paragraph whose
--- 67,79 ----
  =================================
  
! Setext_ required that body text be indented by 2 spaces.  The original
  StructuredText_ and StructuredTextNG_ require that section structure
! be indicated through indentation, as "inspired by Python".  For
! certain structures with a very limited, local extent (such as lists,
! block quotes, and literal blocks), indentation naturally indicates
! structure or hierarchy.  For sections (which may have a very large
! extent), structure via indentation is unnecessary, unnatural and
! ambiguous.  Rather, the syntax of the section title *itself* should
! indicate that it is a section title.
  
  The original StructuredText states that "A single-line paragraph whose
***************
*** 81,98 ****
  header." Requiring indentation in this way is:
  
! - Unnecessary. The vast majority of docstrings and standalone
    documents will have no more than one level of section structure.
    Requiring indentation for such docstrings is unnecessary and
    irritating.
  
! - Unnatural. Most published works use title style (type size, face,
    weight, and position) and/or section/subsection numbering rather
!   than indentation to indicate hierarchy. This is a tradition with a
    very long history.
  
! - Ambiguous. A StructuredText header is indistinguishable from a
    one-line paragraph followed by a block quote (precluding the use of
!   block quotes). Enumerated section titles are ambiguous (is it a
!   header? is it a list item?). Some additional adornment must be
    required to confirm the line's role as a title, both to a parser and
    to the human reader of the source text.
--- 81,98 ----
  header." Requiring indentation in this way is:
  
! - Unnecessary.  The vast majority of docstrings and standalone
    documents will have no more than one level of section structure.
    Requiring indentation for such docstrings is unnecessary and
    irritating.
  
! - Unnatural.  Most published works use title style (type size, face,
    weight, and position) and/or section/subsection numbering rather
!   than indentation to indicate hierarchy.  This is a tradition with a
    very long history.
  
! - Ambiguous.  A StructuredText header is indistinguishable from a
    one-line paragraph followed by a block quote (precluding the use of
!   block quotes).  Enumerated section titles are ambiguous (is it a
!   header? is it a list item?).  Some additional adornment must be
    required to confirm the line's role as a title, both to a parser and
    to the human reader of the source text.
***************
*** 103,108 ****
  
  reStructuredText_ indicates section structure through title adornment
! style (as exemplified by this document). This is far more natural. In
! fact, it is already in widespread use in plain text documents,
  including in Python's standard distribution (such as the toplevel
  README_ file).
--- 103,108 ----
  
  reStructuredText_ indicates section structure through title adornment
! style (as exemplified by this document).  This is far more natural.
! In fact, it is already in widespread use in plain text documents,
  including in Python's standard distribution (such as the toplevel
  README_ file).
***************
*** 114,127 ****
  No matter what characters are chosen for markup, some day someone will
  want to write documentation *about* that markup or using markup
! characters in a non-markup context. Therefore, any complete markup
! language must have an escaping or encoding mechanism. For a
  lightweight markup system, encoding mechanisms like SGML/XML's '*'
! are out. So an escaping mechanism is in. However, with carefully
  chosen markup, it should be necessary to use the escaping mechanism
  only infrequently.
  
  reStructuredText_ needs an escaping mechanism: a way to treat
! markup-significant characters as the characters themselves. Currently
! there is no such mechanism (although ZWiki uses '!'). What are the
  candidates?
  
--- 114,127 ----
  No matter what characters are chosen for markup, some day someone will
  want to write documentation *about* that markup or using markup
! characters in a non-markup context.  Therefore, any complete markup
! language must have an escaping or encoding mechanism.  For a
  lightweight markup system, encoding mechanisms like SGML/XML's '*'
! are out.  So an escaping mechanism is in.  However, with carefully
  chosen markup, it should be necessary to use the escaping mechanism
  only infrequently.
  
  reStructuredText_ needs an escaping mechanism: a way to treat
! markup-significant characters as the characters themselves.  Currently
! there is no such mechanism (although ZWiki uses '!').  What are the
  candidates?
  
***************
*** 131,142 ****
  4. doubling of characters
  
! The best choice for this is the backslash (``\``). It's "the single
  most popular escaping character in the world!", therefore familiar and
! unsurprising. Since characters only need to be escaped under special
  circumstances, which are typically those explaining technical
  programming issues, the use of the backslash is natural and
! understandable. Python docstrings can be raw (prefixed with an 'r', as
! in 'r""'), which would obviate the need for gratuitous doubling-up of
! backslashes.
  
  (On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
--- 131,142 ----
  4. doubling of characters
  
! The best choice for this is the backslash (``\``).  It's "the single
  most popular escaping character in the world!", therefore familiar and
! unsurprising.  Since characters only need to be escaped under special
  circumstances, which are typically those explaining technical
  programming issues, the use of the backslash is natural and
! understandable.  Python docstrings can be raw (prefixed with an 'r',
! as in 'r""'), which would obviate the need for gratuitous doubling-up
! of backslashes.
  
  (On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
***************
*** 146,152 ****
  
  The rule would be: An unescaped backslash followed by any markup
! character escapes the character. The escaped character represents the
  character itself, and is prevented from playing a role in any markup
! interpretation. The backslash is removed from the output. A literal
  backslash is represented by an "escaped backslash," two backslashes in
  a row.
--- 146,152 ----
  
  The rule would be: An unescaped backslash followed by any markup
! character escapes the character.  The escaped character represents the
  character itself, and is prevented from playing a role in any markup
! interpretation.  The backslash is removed from the output.  A literal
  backslash is represented by an "escaped backslash," two backslashes in
  a row.
***************
*** 158,168 ****
  When an expression (requiring backslashes and other characters used
  for markup) becomes too complicated and therefore unreadable, a
! literal block may be used instead. Inside literal blocks, no markup is
! recognized, therefore backslashes (for the purpose of escaping markup)
! become unnecessary.
  
  We could allow backslashes preceding non-markup characters to remain
! in the output. This would make describing regular expressions and
! other uses of backslashes easier. However, this would complicate the
  markup rules and would be confusing.
  
--- 158,168 ----
  When an expression (requiring backslashes and other characters used
  for markup) becomes too complicated and therefore unreadable, a
! literal block may be used instead.  Inside literal blocks, no markup
! is recognized, therefore backslashes (for the purpose of escaping
! markup) become unnecessary.
  
  We could allow backslashes preceding non-markup characters to remain
! in the output.  This would make describing regular expressions and
! other uses of backslashes easier.  However, this would complicate the
  markup rules and would be confusing.
  
***************
*** 173,177 ****
  Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13)
  is the ability to write lists without requiring blank lines between
! items. In docstrings, space is at a premium. Authors want to convey
  their API or usage information in as compact a form as possible.
  StructuredText_ requires blank lines between all body elements,
--- 173,177 ----
  Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13)
  is the ability to write lists without requiring blank lines between
! items.  In docstrings, space is at a premium.  Authors want to convey
  their API or usage information in as compact a form as possible.
  StructuredText_ requires blank lines between all body elements,
***************
*** 181,185 ****
  In reStructuredText, blank lines are optional between list items.
  However, in order to eliminate ambiguity, a blank line is required
! before the first list item and after the last. Nested lists also
  require blank lines before the list start and after the list end.
  
--- 181,185 ----
  In reStructuredText, blank lines are optional between list items.
  However, in order to eliminate ambiguity, a blank line is required
! before the first list item and after the last.  Nested lists also
  require blank lines before the list start and after the list end.
  
***************
*** 188,194 ****
  ==================
  
! StructuredText_ includes 'o' as a bullet character. This is dangerous
! and counter to the language-independent nature of the markup. There
! are many languages in which 'o' is a word. For example, in Spanish::
  
      Llamame a la casa
--- 188,194 ----
  ==================
  
! StructuredText_ includes 'o' as a bullet character.  This is dangerous
! and counter to the language-independent nature of the markup.  There
! are many languages in which 'o' is a word.  For example, in Spanish::
  
      Llamame a la casa
***************
*** 208,213 ****
  could be misinterpreted as a bullet list.
  
! In reStructuredText_, 'o' is not used as a bullet character. '-', '*',
! and '+' are the possible bullet characters.
  
  
--- 208,213 ----
  could be misinterpreted as a bullet list.
  
! In reStructuredText_, 'o' is not used as a bullet character.  '-',
! '*', and '+' are the possible bullet characters.
  
  
***************
*** 217,226 ****
  StructuredText enumerated lists are allowed to begin with numbers and
  letters followed by a period or right-parenthesis, then whitespace.
! This has surprising consequences for writing styles. For example, this
! is recognized as an enumerated list item by StructuredText::
  
      Mr. Creosote.
  
! People will write enumerated lists in all different ways. It is folly
  to try to come up with the "perfect" format for an enumerated list,
  and limit the docstring parser's recognition to that one format only.
--- 217,226 ----
  StructuredText enumerated lists are allowed to begin with numbers and
  letters followed by a period or right-parenthesis, then whitespace.
! This has surprising consequences for writing styles.  For example,
! this is recognized as an enumerated list item by StructuredText::
  
      Mr. Creosote.
  
! People will write enumerated lists in all different ways.  It is folly
  to try to come up with the "perfect" format for an enumerated list,
  and limit the docstring parser's recognition to that one format only.
***************
*** 232,237 ****
  
  If a PELI is labeled with a "1.", and is immediately followed by a
! PELI labeled with a "2.", we've got an enumerated list. Or "(A)"
! followed by "(B)". Or "i)" followed by "ii)", etc. The chances of
  accidentally recognizing two adjacent and consistently labeled PELIs,
  are acceptably small.
--- 232,237 ----
  
  If a PELI is labeled with a "1.", and is immediately followed by a
! PELI labeled with a "2.", we've got an enumerated list.  Or "(A)"
! followed by "(B)".  Or "i)" followed by "ii)", etc.  The chances of
  accidentally recognizing two adjacent and consistently labeled PELIs,
  are acceptably small.
***************
*** 252,261 ****
  
  StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on
! the first line of a paragraph to indicate a definition list item. The
  ' -- ' serves to separate the term (on the left) from the definition
  (on the right).
  
  Many people use ' -- ' as an em-dash in their text, conflicting with
! the StructuredText usage. Although the Chicago Manual of Style says
  that spaces should not be used around an em-dash, Peter Funk pointed
  out that this is standard usage in German (according to the Duden, the
--- 252,261 ----
  
  StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on
! the first line of a paragraph to indicate a definition list item.  The
  ' -- ' serves to separate the term (on the left) from the definition
  (on the right).
  
  Many people use ' -- ' as an em-dash in their text, conflicting with
! the StructuredText usage.  Although the Chicago Manual of Style says
  that spaces should not be used around an em-dash, Peter Funk pointed
  out that this is standard usage in German (according to the Duden, the
***************
*** 277,283 ****
  
  A reStructuredText definition list item consists of a term and a
! definition. A term is a simple one-line paragraph. A definition is a
  block indented relative to the term, and may contain multiple
! paragraphs and other body elements. No blank line precedes a
  definition (this distinguishes definition lists from block quotes).
  
--- 277,283 ----
  
  A reStructuredText definition list item consists of a term and a
! definition.  A term is a simple one-line paragraph.  A definition is a
  block indented relative to the term, and may contain multiple
! paragraphs and other body elements.  No blank line precedes a
  definition (this distinguishes definition lists from block quotes).
  
***************
*** 286,300 ****
  ==============
  The StructuredText_ specification has literal blocks indicated by
! 'example', 'examples', or '::' ending the preceding paragraph. STNG
! only recognizes '::'; 'example'/'examples' are not implemented. This
! is good; it fixes an unnecessary language dependency. The problem is
  what to do with the sometimes- unwanted '::'.
  
  In reStructuredText_ '::' at the end of a paragraph indicates that
! subsequent *indented* blocks are treated as literal text. No further
  markup interpretation is done within literal blocks (not even
! backslash-escapes). If the '::' is preceded by whitespace, '::' is
  omitted from the output; if '::' was the sole content of a paragraph,
! the entire paragraph is removed (no 'empty' paragraph remains). If
  '::' is preceded by a non-whitespace character, '::' is replaced by
  ':' (i.e., the extra colon is removed).
--- 286,300 ----
  ==============
  The StructuredText_ specification has literal blocks indicated by
! 'example', 'examples', or '::' ending the preceding paragraph.  STNG
! only recognizes '::'; 'example'/'examples' are not implemented.  This
! is good; it fixes an unnecessary language dependency.  The problem is
  what to do with the sometimes- unwanted '::'.
  
  In reStructuredText_ '::' at the end of a paragraph indicates that
! subsequent *indented* blocks are treated as literal text.  No further
  markup interpretation is done within literal blocks (not even
! backslash-escapes).  If the '::' is preceded by whitespace, '::' is
  omitted from the output; if '::' was the sole content of a paragraph,
! the entire paragraph is removed (no 'empty' paragraph remains).  If
  '::' is preceded by a non-whitespace character, '::' is replaced by
  ':' (i.e., the extra colon is removed).
***************
*** 313,322 ****
  ======
  
! The table markup scheme in classic StructuredText was horrible. Its
  omission from StructuredTextNG is welcome, and its markup will not be
! repeated here. However, tables themselves are useful in documentation.
! Alternatives:
  
! 1. This format is the most natural and obvious. It was independently
     invented (no great feat of creation!), and later found to be the
     format supported by the `Emacs table mode`_::
--- 313,322 ----
  ======
  
! The table markup scheme in classic StructuredText was horrible.  Its
  omission from StructuredTextNG is welcome, and its markup will not be
! repeated here.  However, tables themselves are useful in
! documentation.  Alternatives:
  
! 1. This format is the most natural and obvious.  It was independently
     invented (no great feat of creation!), and later found to be the
     format supported by the `Emacs table mode`_::
***************
*** 345,358 ****
  
     Row and column spans are possible simply by omitting the column or
!    row separators, respectively. The header row separator must be
     complete; in other words, a header cell may not span into the table
!    body. Each cell contains body elements, and may have multiple
!    paragraphs, lists, etc. Initial spaces for a left margin are
     allowed; the first line of text in a cell determines its left
     margin.
  
! 2. Below is a minimalist possibility. It may be better suited to
     manual input than alternative #1, but there is no Emacs editing
!    mode available. One disadvantage is that it resembles section
     titles; a one-column table would look exactly like section &
     subsection titles. ::
--- 345,358 ----
  
     Row and column spans are possible simply by omitting the column or
!    row separators, respectively.  The header row separator must be
     complete; in other words, a header cell may not span into the table
!    body.  Each cell contains body elements, and may have multiple
!    paragraphs, lists, etc.  Initial spaces for a left margin are
     allowed; the first line of text in a cell determines its left
     margin.
  
! 2. Below is a minimalist possibility.  It may be better suited to
     manual input than alternative #1, but there is no Emacs editing
!    mode available.  One disadvantage is that it resembles section
     titles; a one-column table would look exactly like section &
     subsection titles. ::
***************
*** 369,379 ****
  
     The table begins with a top border of equals signs with a space at
!    each column boundary (regardless of spans). Each row is underlined.
!    Internal row separators are underlines of '-', with spaces at
!    column boundaries. The last of the optional head rows is underlined
!    with '=', again with spaces at column boundaries. Column spans have
!    no spaces in their underline. Row spans simply lack an underline at
!    the row boundary. The bottom boundary of the table consists of '='
!    underlines. A blank line is required following a table.
  
  Alternative #1 is the choice adopted by reStructuredText.
--- 369,380 ----
  
     The table begins with a top border of equals signs with a space at
!    each column boundary (regardless of spans).  Each row is
!    underlined.  Internal row separators are underlines of '-', with
!    spaces at column boundaries.  The last of the optional head rows is
!    underlined with '=', again with spaces at column boundaries.
!    Column spans have no spaces in their underline.  Row spans simply
!    lack an underline at the row boundary.  The bottom boundary of the
!    table consists of '=' underlines.  A blank line is required
!    following a table.
  
  Alternative #1 is the choice adopted by reStructuredText.
***************
*** 387,399 ****
  emphatic text::
  
!     "**What?**" she cried. (*exit stage left*)
  
  The `reStructuredText markup specification`_ allows for such
  constructs and disambiguates inline markup through a set of
! recognition rules. These recognition rules define the context of
  markup start-strings and end-strings, allowing markup characters to be
  used in most non-markup contexts without a problem (or a backslash).
  So we can say, "Use asterisks (*) around words or phrases to
! *emphasisze* them." The '(*)' will not be recognized as markup. This
  reduces the need for markup escaping to the point where an escape
  character is *almost* (but not quite!) unnecessary.
--- 388,400 ----
  emphatic text::
  
!     "**What?**" she cried.  (*exit stage left*)
  
  The `reStructuredText markup specification`_ allows for such
  constructs and disambiguates inline markup through a set of
! recognition rules.  These recognition rules define the context of
  markup start-strings and end-strings, allowing markup characters to be
  used in most non-markup contexts without a problem (or a backslash).
  So we can say, "Use asterisks (*) around words or phrases to
! *emphasisze* them." The '(*)' will not be recognized as markup.  This
  reduces the need for markup escaping to the point where an escape
  character is *almost* (but not quite!) unnecessary.
***************
*** 403,407 ****
  ===========
  
! StructuredText uses '_text_' to indicate underlining. To quote David
  Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring
  grammar: a very revised proposal":
--- 404,408 ----
  ===========
  
! StructuredText uses '_text_' to indicate underlining.  To quote David
  Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring
  grammar: a very revised proposal":
***************
*** 417,421 ****
      ('__init__'), I think of docstring markups much like I think of
      type annotations -- they should be optional and above all do no
!     harm. In this case the underline markup does harm.
  
  Underlining is not part of the reStructuredText specification.
--- 418,422 ----
      ('__init__'), I think of docstring markups much like I think of
      type annotations -- they should be optional and above all do no
!     harm.  In this case the underline markup does harm.
  
  Underlining is not part of the reStructuredText specification.
***************
*** 427,431 ****
  StructuredText's markup for inline literals (text left as-is,
  verbatim, usually in a monospaced font; as in HTML <TT>) is single
! quotes ('literals'). The problem with single quotes is that they are
  too often used for other purposes:
  
--- 428,432 ----
  StructuredText's markup for inline literals (text left as-is,
  verbatim, usually in a monospaced font; as in HTML <TT>) is single
! quotes ('literals').  The problem with single quotes is that they are
  too often used for other purposes:
  
***************
*** 448,452 ****
  
  The examples below contain inline literals, quoted text, and
! apostrophes. Each example should evaluate to the following HTML::
  
      Some <TT>code</TT>, with a 'quote', "double", ain't it grand?
--- 449,453 ----
  
  The examples below contain inline literals, quoted text, and
! apostrophes.  Each example should evaluate to the following HTML::
  
      Some <TT>code</TT>, with a 'quote', "double", ain't it grand?
***************
*** 480,497 ****
          Does ``a[b] = 'c' + "d" + `2^3\``` work?
  
! Backquotes (#9 & #12) are the best choice. They are unobtrusive and
! relatviely rarely used (more rarely than ' or ", anyhow). Backquotes
  have the connotation of 'quotes', which other options (like carets,
  #10) don't.
  
  Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12)
! could be used for inline literals. If single-backquotes are used for
  'interpreted text' (context-sensitive domain-specific descriptive
  markup) such as function name hyperlinks in Python docstrings, then
  double-backquotes could be used for absolute-literals, wherein no
! processing whatsoever takes place. An advantage of double-backquotes
  would be that backslash-escaping would no longer be necessary for
  embedded single-backquotes; however, embedded double-backquotes (in an
! end-string context) would be illegal. See `Backquotes in
  Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__.
  
--- 481,498 ----
          Does ``a[b] = 'c' + "d" + `2^3\``` work?
  
! Backquotes (#9 & #12) are the best choice.  They are unobtrusive and
! relatviely rarely used (more rarely than ' or ", anyhow).  Backquotes
  have the connotation of 'quotes', which other options (like carets,
  #10) don't.
  
  Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12)
! could be used for inline literals.  If single-backquotes are used for
  'interpreted text' (context-sensitive domain-specific descriptive
  markup) such as function name hyperlinks in Python docstrings, then
  double-backquotes could be used for absolute-literals, wherein no
! processing whatsoever takes place.  An advantage of double-backquotes
  would be that backslash-escaping would no longer be necessary for
  embedded single-backquotes; however, embedded double-backquotes (in an
! end-string context) would be illegal.  See `Backquotes in
  Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__.
  
***************
*** 499,503 ****
  __ alternatives.html
  
! Alternative choices are carets (#10) and TeX-style quotes (#11). For
  examples of TeX-style quoting, see
  http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor.
--- 500,504 ----
  __ alternatives.html
  
! Alternative choices are carets (#10) and TeX-style quotes (#11).  For
  examples of TeX-style quoting, see
  http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor.
***************
*** 516,527 ****
  
  Outside of inline literals, the above uses of backquotes would require
! backslash-escaping. However, these are all prime examples of text that
! should be marked up with inline literals.
  
  If either backquotes or straight single-quotes are used as markup,
  TeX-quotes are too troublesome to support, so no special-casing of
! TeX-quotes should be done (at least at first). If TeX-quotes have to
  be used outside of literals, a single backslash-escaped would suffice:
! \``TeX quote''. Ugly, true, but very infrequently used.
  
  Using literal blocks is a fallback option which removes the need for
--- 517,528 ----
  
  Outside of inline literals, the above uses of backquotes would require
! backslash-escaping.  However, these are all prime examples of text
! that should be marked up with inline literals.
  
  If either backquotes or straight single-quotes are used as markup,
  TeX-quotes are too troublesome to support, so no special-casing of
! TeX-quotes should be done (at least at first).  If TeX-quotes have to
  be used outside of literals, a single backslash-escaped would suffice:
! \``TeX quote''.  Ugly, true, but very infrequently used.
  
  Using literal blocks is a fallback option which removes the need for
***************
*** 533,539 ****
  
  No mechanism for inline literals is perfect, just as no escaping
! mechanism is perfect. No matter what we use, complicated inline
  expressions involving the inline literal quote and/or the backslash
! will end up looking ugly. We can only choose the least often ugly
  option.
  
--- 534,540 ----
  
  No mechanism for inline literals is perfect, just as no escaping
! mechanism is perfect.  No matter what we use, complicated inline
  expressions involving the inline literal quote and/or the backslash
! will end up looking ugly.  We can only choose the least often ugly
  option.
  
***************
*** 547,557 ****
  There are three forms of hyperlink currently in StructuredText_:
  
! 1. (Absolute & relative URIs.) Text enclosed by double quotes followed
!    by a colon, a URI, and concluded by punctuation plus white space,
!    or just white space, is treated as a hyperlink::
  
         "Python":http://www.python.org/
  
! 2. (Absolute URIs only.) Text enclosed by double quotes followed by a
     comma, one or more spaces, an absolute URI and concluded by
     punctuation plus white space, or just white space, is treated as a
--- 548,558 ----
  There are three forms of hyperlink currently in StructuredText_:
  
! 1. (Absolute & relative URIs.)  Text enclosed by double quotes
!    followed by a colon, a URI, and concluded by punctuation plus white
!    space, or just white space, is treated as a hyperlink::
  
         "Python":http://www.python.org/
  
! 2. (Absolute URIs only.)  Text enclosed by double quotes followed by a
     comma, one or more spaces, an absolute URI and concluded by
     punctuation plus white space, or just white space, is treated as a
***************
*** 560,566 ****
         "mail me", mailto:me...@ma...
  
! 3. (Endnotes.) Text enclosed by brackets link to an endnote at the end
!    of the document: at the beginning of the line, two dots, a space,
!    and the same text in brackets, followed by the end note itself::
  
         Please refer to the fine manual [GVR2001].
--- 561,568 ----
         "mail me", mailto:me...@ma...
  
! 3. (Endnotes.)  Text enclosed by brackets link to an endnote at the
!    end of the document: at the beginning of the line, two dots, a
!    space, and the same text in brackets, followed by the end note
!    itself::
  
         Please refer to the fine manual [GVR2001].
***************
*** 570,577 ****
  
  The problem with forms 1 and 2 is that they are neither intuitive nor
! unobtrusive (they break design goals 5 & 2). They overload
  double-quotes, which are too often used in ordinary text (potentially
! breaking design goal 4). The brackets in form 3 are also too common in
! ordinary text (such as [nested] asides and Python lists like [12]).
  
  Alternatives:
--- 572,579 ----
  
  The problem with forms 1 and 2 is that they are neither intuitive nor
! unobtrusive (they break design goals 5 & 2).  They overload
  double-quotes, which are too often used in ordinary text (potentially
! breaking design goal 4).  The brackets in form 3 are also too common
! in ordinary text (such as [nested] asides and Python lists like [12]).
  
  Alternatives:
***************
*** 581,585 ****
  2. A. Interpret and mark up hyperlinks as any contiguous text
        containing '://' or ':...@' (absolute URI) or '@' (email
!       address) after an alphanumeric word. To de-emphasize the URI,
        simply enclose it in parentheses:
  
--- 583,587 ----
  2. A. Interpret and mark up hyperlinks as any contiguous text
        containing '://' or ':...@' (absolute URI) or '@' (email
!       address) after an alphanumeric word.  To de-emphasize the URI,
        simply enclose it in parentheses:
  
***************
*** 589,593 ****
        Hyperlinks in ordinary reStructuredText documents would be
        required to be standalone (i.e. the URI text inline in the
!       document text). Processed hyperlinks (where the URI text is
        hidden behind the link) are important enough to warrant syntax.
  
--- 591,595 ----
        Hyperlinks in ordinary reStructuredText documents would be
        required to be standalone (i.e. the URI text inline in the
!       document text).  Processed hyperlinks (where the URI text is
        hidden behind the link) are important enough to warrant syntax.
  
***************
*** 610,614 ****
  Since each source link must match up to a target, the odd variable
  ending in an underscore can be spared being marked up (although it
! should generate a "no such link target" warning). The only
  disadvantage is that phrase-links aren't possible without some
  obtrusive syntax.
--- 612,616 ----
  Since each source link must match up to a target, the odd variable
  ending in an underscore can be spared being marked up (although it
! should generate a "no such link target" warning).  The only
  disadvantage is that phrase-links aren't possible without some
  obtrusive syntax.
***************
*** 628,638 ****
         `like this`_
  
! Each gives us somewhat obtrusive markup, but that is unavoidable. The
  bracketed syntax (#2) is reminiscent of links on many web pages
! (intuitive), although it is somewhat obtrusive. Alternative #3 is much
! less obtrusive, and is consistent with interpreted text: the trailing
! underscore indicates the interpretation of the phrase, as a hyperlink.
! #3 also disambiguates hyperlinks from footnote references. Alternative
! #3 wins.
  
  The same trailing underscore markup can also be used for footnote and
--- 630,640 ----
         `like this`_
  
! Each gives us somewhat obtrusive markup, but that is unavoidable.  The
  bracketed syntax (#2) is reminiscent of links on many web pages
! (intuitive), although it is somewhat obtrusive.  Alternative #3 is
! much less obtrusive, and is consistent with interpreted text: the
! trailing underscore indicates the interpretation of the phrase, as a
! hyperlink.  #3 also disambiguates hyperlinks from footnote references.
! Alternative #3 wins.
  
  The same trailing underscore markup can also be used for footnote and
***************
*** 648,655 ****
  comments, which are removed from the (visible) processed output.
  reStructuredText uses this syntax for comments, footnotes, and link
! target, collectively termed "explicit markup". For link targets, in
  order to eliminate ambiguity with comments and footnotes,
  reStructuredText specifies that a colon always follow the link target
! word/phrase. The colon denotes 'maps to'. There is no reason to
  restrict target links to the end of the document; they could just as
  easily be interspersed.
--- 650,657 ----
  comments, which are removed from the (visible) processed output.
  reStructuredText uses this syntax for comments, footnotes, and link
! target, collectively termed "explicit markup".  For link targets, in
  order to eliminate ambiguity with comments and footnotes,
  reStructuredText specifies that a colon always follow the link target
! word/phrase.  The colon denotes 'maps to'.  There is no reason to
  restrict target links to the end of the document; they could just as
  easily be interspersed.
***************
*** 657,661 ****
  Internal hyperlinks (links from one point to another within a single
  document) can be expressed by a source link as before, and a target
! link with a colon but no URI. In effect, these targets 'map to' the
  element immediately following.
  
--- 659,663 ----
  Internal hyperlinks (links from one point to another within a single
  document) can be expressed by a source link as before, and a target
! link with a colon but no URI.  In effect, these targets 'map to' the
  element immediately following.
  
***************
*** 689,704 ****
  
  The presence or absence of a colon after the target link
! differentiates an indirect hyperlink from a footnote, respectively. A
! footnote requires brackets. Backquotes around a target link word or
  phrase are required if the phrase contains a colon, optional
  otherwise.
  
  Below are examples using no markup, the two StructuredText hypertext
! styles, and the reStructuredText hypertext style. Each example
  contains an indirect link, a direct link, a footnote/endnote, and
! bracketed text. In HTML, each example should evaluate to::
  
      <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000">
!     [eggs2000]</A> (in Bacon [Publisher]). Also see
      <A HREF="http://eggs.org">http://eggs.org</A>.</P>
  
--- 691,706 ----
  
  The presence or absence of a colon after the target link
! differentiates an indirect hyperlink from a footnote, respectively.  A
! footnote requires brackets.  Backquotes around a target link word or
  phrase are required if the phrase contains a colon, optional
  otherwise.
  
  Below are examples using no markup, the two StructuredText hypertext
! styles, and the reStructuredText hypertext style.  Each example
  contains an indirect link, a direct link, a footnote/endnote, and
! bracketed text.  In HTML, each example should evaluate to::
  
      <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000">
!     [eggs2000]</A> (in Bacon [Publisher]).  Also see
      <A HREF="http://eggs.org">http://eggs.org</A>.</P>
  
***************
*** 729,733 ****
  
         A "URI", http://spam.org, see [eggs2000] (in Bacon
!        [Publisher]). Also see "http://eggs.org", http://eggs.org.
  
         .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
--- 731,735 ----
  
         A "URI", http://spam.org, see [eggs2000] (in Bacon
!        [Publisher]).  Also see "http://eggs.org", http://eggs.org.
  
         .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
***************
*** 744,748 ****
  StructuredText (syntax 2 & 3).
  
! reStructuredText's syntax (#4) is definitely the most readable. The
  text is separated from the link URI and the footnote, resulting in
  cleanly readable text.
--- 746,750 ----
  StructuredText (syntax 2 & 3).
  
! reStructuredText's syntax (#4) is definitely the most readable.  The
  text is separated from the link URI and the footnote, resulting in
  cleanly readable text.