Formal Specification

The description in the original StructuredText.py has been criticizedfor being vague. For practical purposes, "the codeis the spec."Tony Ibbs has been working on deducing adetailed description fromthe documentation and code ofStructuredTextNG. Edward Loper'sSTMinus is another attempt to formalize a spec.

For this kind of a project, the specification should always precedethe code. Otherwise, the markup is a moving target which can never beadopted as a standard. Of course, a specification may be revisedduring lifetime of the code, but without a spec there is no visiblecontrol and thus no confidence.

Understanding and Extending the Code

The originalStructuredText is a dense mass of sparsely commentedcode and inscrutable regular expressions. It was not designed to beextended and is very difficult to understand.StructuredTextNG hasbeen designed to allow input (syntax) and output extensions, but itsdocumentation (both internal [comments & docstrings], and external) isinadequate for the complexity of the code itself.

For reStructuredText to become truly useful, perhaps even part ofPython's standard library, it must have clear, understandabledocumentation and implementation code. For the implementation ofreStructuredText to be taken seriously, it must be a sterling exampleof the potential of docstrings; the implementation must practice whatthe specification preaches.

Section Structure via Indentation

Setext required that body text be indented by 2 spaces. The originalStructuredText andStructuredTextNG require that section structurebe indicated through indentation, as "inspired by Python". Forcertain structures with a very limited, local extent (such as lists,block quotes, and literal blocks), indentation naturally indicatesstructure or hierarchy. For sections (which may have a very largeextent), structure via indentation is unnecessary, unnatural andambiguous. Rather, the syntax of the section titleitself shouldindicate that it is a section title.

The original StructuredText states that "A single-line paragraph whoseimmediately succeeding paragraphs are lower level is treated as aheader." Requiring indentation in this way is:

• Unnecessary. The vast majority of docstrings and standalonedocuments will have no more than one level of section structure.Requiring indentation for such docstrings is unnecessary andirritating.

• Unnatural. Most published works use title style (type size, face,weight, and position) and/or section/subsection numbering ratherthan indentation to indicate hierarchy. This is a tradition with avery long history.

• Ambiguous. A StructuredText header is indistinguishable from aone-line paragraph followed by a block quote (precluding the use ofblock quotes). Enumerated section titles are ambiguous (is it aheader? is it a list item?). Some additional adornment must berequired to confirm the line's role as a title, both to a parser andto the human reader of the source text.

Python's use of significant whitespace is a wonderful (if notoriginal) innovation, however requiring indentation in ordinarywritten text is hypergeneralization.

reStructuredText indicates section structure through title adornmentstyle (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 toplevelREADME file).

Character Escaping Mechanism

No matter what characters are chosen for markup, some day someone willwant to write documentationabout that markup or using markupcharacters in a non-markup context. Therefore, any complete markuplanguage must have an escaping or encoding mechanism. For alightweight markup system, encoding mechanisms like SGML/XML's '*'are out. So an escaping mechanism is in. However, with carefullychosen markup, it should be necessary to use the escaping mechanismonly infrequently.

reStructuredText needs an escaping mechanism: a way to treatmarkup-significant characters as the characters themselves. Currentlythere is no such mechanism (although ZWiki uses '!'). What are thecandidates?

1. !(http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping)

2. \

3. ~

4. doubling of characters

The best choice for this is the backslash (\). It's "the singlemost popular escaping character in the world!", therefore familiar andunsurprising. Since characters only need to be escaped under specialcircumstances, which are typically those explaining technicalprogramming issues, the use of the backslash is natural andunderstandable. Python docstrings can be raw (prefixed with an 'r',as in 'r""'), which would obviate the need for gratuitous doubling-upof backslashes.

(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslashescapes, saying, "'nuff said. Backslash it is." Although neitherlegally binding nor irrevocable nor any kind of guarantee of anything,it is a good sign.)

The rule would be: An unescaped backslash followed by any markupcharacter escapes the character. The escaped character represents thecharacter itself, and is prevented from playing a role in any markupinterpretation. The backslash is removed from the output. A literalbackslash is represented by an "escaped backslash," two backslashes ina row.

A carefully constructed set of recognition rules for inline markupwill obviate the need for backslash-escapes in almost all cases; seeDelimitation of Inline Markup below.

When an expression (requiring backslashes and other characters usedfor markup) becomes too complicated and therefore unreadable, aliteral block may be used instead. Inside literal blocks, no markupis recognized, therefore backslashes (for the purpose of escapingmarkup) become unnecessary.

We could allow backslashes preceding non-markup characters to remainin the output. This would make describing regular expressions andother uses of backslashes easier. However, this would complicate themarkup rules and would be confusing.

Blank Lines in Lists

Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13)is the ability to write lists without requiring blank lines betweenitems. In docstrings, space is at a premium. Authors want to conveytheir API or usage information in as compact a form as possible.StructuredText requires blank lines between all body elements,including list items, even when boundaries are obvious from the markupitself.

In reStructuredText, blank lines are optional between list items.However, in order to eliminate ambiguity, a blank line is requiredbefore the first list item and after the last. Nested lists alsorequire blank lines before the list start and after the list end.

Bullet List Markup

StructuredText includes 'o' as a bullet character. This is dangerousand counter to the language-independent nature of the markup. Thereare many languages in which 'o' is a word. For example, in Spanish:

Llamame a la casao al trabajo.(Call me at home or at work.)

And in Japanese (when romanized):

Senshuu no doyoubi ni tegamio kakimashita.([I] wrote a letter on Saturday last week.)

If a paragraph containing an 'o' word wraps such that the 'o' is thefirst text on a line, or if a paragraph begins with such a word, itcould be misinterpreted as a bullet list.

InreStructuredText, 'o' is not used as a bullet character. '-','*', and '+' are the possible bullet characters.

Enumerated List Markup

StructuredText enumerated lists are allowed to begin with numbers andletters 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 follyto try to come up with the "perfect" format for an enumerated list,and limit the docstring parser's recognition to that one format only.

Rather, the parser should recognize a variety of enumerator styles.It is also recommended that the enumerator of the first list item beordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not beable to begin a list at an arbitrary enumeration.

An initial idea was to require two or more consistent enumerated listitems in a row. This idea proved impractical and was dropped. Inpractice, the presence of a proper enumerator is enough to reliablyrecognize an enumerated list item; any ambiguities are reported by theparser. Here's the original idea for posterity:

The parser should recognize a variety of enumerator styles, markeach block as a potential enumerated list item (PELI), andinterpret the enumerators of adjacent PELIs to decide whether theymake up a consistent enumerated list.

If a PELI is labeled with a "1.", and is immediately followed by aPELI labeled with a "2.", we've got an enumerated list. Or "(A)"followed by "(B)". Or "i)" followed by "ii)", etc. The chancesof accidentally recognizing two adjacent and consistently labeledPELIs, are acceptably small.

For an enumerated list to be recognized, the following must betrue:

• the list must consist of multiple adjacent list items (2 ormore)

• the enumerators must all have the same format

• the enumerators must be sequential

Definition List Markup

StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) onthe 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 withthe StructuredText usage. Although the Chicago Manual of Style saysthat spaces should not be used around an em-dash, Peter Funk pointedout that this is standard usage in German (according to the Duden, theofficial German reference), and possibly in other languages as well.The widespread use of ' -- ' precludes its use for definition lists;it would violate the "unsurprising" criterion.

A simpler, and at least equally visually distinctive construct(proposed by Guido van Rossum, who incidentally is a frequent user of' -- ') would do just as well:

term 1    Definition.term 2    Definition 2, paragraph 1.    Definition 2, paragraph 2.

A reStructuredText definition list item consists of a term and adefinition. A term is a simple one-line paragraph. A definition is ablock indented relative to the term, and may contain multipleparagraphs and other body elements. No blank line precedes adefinition (this distinguishes definition lists from block quotes).

Literal Blocks

TheStructuredText specification has literal blocks indicated by'example', 'examples', or '::' ending the preceding paragraph. STNGonly recognizes '::'; 'example'/'examples' are not implemented. Thisis good; it fixes an unnecessary language dependency. The problem iswhat to do with the sometimes- unwanted '::'.

InreStructuredText '::' at the end of a paragraph indicates thatsubsequentindented blocks are treated as literal text. No furthermarkup interpretation is done within literal blocks (not evenbackslash-escapes). If the '::' is preceded by whitespace, '::' isomitted 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).

Thus, a section could begin with a literal block as follows:

Section Title-------------::    print "this is example literal"

Tables

The table markup scheme in classic StructuredText was horrible. Itsomission from StructuredTextNG is welcome, and its markup will not berepeated here. However, tables themselves are useful indocumentation. Alternatives:

1. This format is the most natural and obvious. It was independentlyinvented (no great feat of creation!), and later found to be theformat supported by theEmacs table mode:

   +------------+------------+------------+--------------+|  Header 1  |  Header 2  |  Header 3  |  Header 4    |+============+============+============+==============+|  Column 1  |  Column 2  | Column 3 & 4 span (Row 1) |+------------+------------+------------+--------------+|    Column 1 & 2 span    |  Column 3  | - Column 4   |+------------+------------+------------+ - Row 2 & 3  ||      1     |      2     |      3     | - span       |+------------+------------+------------+--------------+

   Tables are described with a visual outline made up of thecharacters '-', '=', '|', and '+':

   • The hyphen ('-') is used for horizontal lines (row separators).

   • The equals sign ('=') is optionally used as a header separator(as of version 1.5.24, this is not supported by the Emacs tablemode).

   • The vertical bar ('|') is used for for vertical lines (columnseparators).

   • The plus sign ('+') is used for intersections of horizontal andvertical lines.

   Row and column spans are possible simply by omitting the column orrow separators, respectively. The header row separator must becomplete; in other words, a header cell may not span into the tablebody. Each cell contains body elements, and may have multipleparagraphs, lists, etc. Initial spaces for a left margin areallowed; the first line of text in a cell determines its leftmargin.

2. Below is a simpler table structure. It may be better suited tomanual input than alternative #1, but there is no Emacs editingmode available. One disadvantage is that it resembles sectiontitles; a one-column table would look exactly like section &subsection titles.

   ============ ============ ============ ==============  Header 1     Header 2     Header 3     Header 4============ ============ ============ ==============  Column 1     Column 2    Column 3 & 4 span (Row 1)------------ ------------ ---------------------------    Column 1 & 2 span       Column 3    - Column 4------------------------- ------------  - Row 2 & 3      1            2            3       - span============ ============ ============ ==============

   The table begins with a top border of equals signs with a space ateach column boundary (regardless of spans). Each row isunderlined. Internal row separators are underlines of '-', withspaces at column boundaries. The last of the optional head rows isunderlined with '=', again with spaces at column boundaries.Column spans have no spaces in their underline. Row spans simplylack an underline at the row boundary. The bottom boundary of thetable consists of '=' underlines. A blank line is requiredfollowing a table.

3. A minimalist alternative is as follows:

   ====  =====  ========  ========  =======  ====  =====  =====Old State    Input     Action             New State    Notes-----------  --------  -----------------  -----------ids   types  new type  sys.msg.  dupname  ids   types====  =====  ========  ========  =======  ====  =====  =====--    --     explicit  --        --       new   True--    --     implicit  --        --       new   FalseNone  False  explicit  --        --       new   Trueold   False  explicit  implicit  old      new   TrueNone  True   explicit  explicit  new      None  Trueold   True   explicit  explicit  new,old  None  True   [1]None  False  implicit  implicit  new      None  Falseold   False  implicit  implicit  new,old  None  FalseNone  True   implicit  implicit  new      None  Trueold   True   implicit  implicit  new      old   True====  =====  ========  ========  =======  ====  =====  =====

   The table begins with a top border of equals signs with one or morespaces at each column boundary (regardless of spans). There mustbe at least two columns in the table (to differentiate it fromsection headers). Each line starts a new row. The rightmostcolumn is unbounded; text may continue past the edge of the table.Each row/line must contain spaces at column boundaries, except forexplicit column spans. Underlines of '-' can be used to indicatecolumn spans, but should be used sparingly if at all. Linescontaining column span underlines may not contain any other text.The last of the optional head rows is underlined with '=', againwith spaces at column boundaries. The bottom boundary of the tableconsists of '=' underlines. A blank line is required following atable.

   This table sums up the features. Using all the features in such asmall space is not pretty though:

   ========  ========  ========          Header 2 & 3 Span          ------------------Header 1  Header 2  Header 3========  ========  ========Each      line is   a new row.Each row  consists  of one line only.Row       spans     are not possible.The last  column    may spill over to the right.Column spans are possible with an underline joining columns.----------------------------The span  is        limited to the row above the underline.========  ========  ========

4. As a variation of alternative 3, bullet list syntax in the firstcolumn could be used to indicate row starts. Multi-line rows arepossible, but row spans are not. For example:

   ===== =====col 1 col 2===== =====- 1   Second column of row 1.- 2   Second column of row 2.      Second line of paragraph.- 3   Second column of row 3.      Second paragraph of row 3,      column 2===== =====

   Column spans would be indicated on the line after the last line ofthe row. To indicate a real bullet list within a first-columncell, simply nest the bullets.

5. In a further variation, we could simply assume that whitespace inthe first column implies a multi-line row; the text in othercolumns is continuation text. For example:

   ===== =====col 1 col 2===== =====1     Second column of row 1.2     Second column of row 2.      Second line of paragraph.3     Second column of row 3.      Second paragraph of row 3,      column 2===== =====

   Limitations of this approach:

   • Cells in the first column are limited to one line of text.

   • Cells in the first columnmust contain some text; blank cellswould lead to a misinterpretation. An empty comment ("..") issufficient.

6. Combining alternative 3 and 4, a bullet list in the first columncould mean multi-line rows, and no bullet list means single-linerows only.

Alternatives 1 and 5 has been adopted by reStructuredText.

Delimitation of Inline Markup

StructuredText specifies that inline markup must begin withwhitespace, precluding such constructs as parenthesized or quotedemphatic text:

"**What?**" she cried.  (*exit stage left*)

ThereStructuredText markup specification allows for suchconstructs and disambiguates inline markup through a set ofrecognition rules. These recognition rules define the context ofmarkup start-strings and end-strings, allowing markup characters to beused in most non-markup contexts without a problem (or a backslash).So we can say, "Use asterisks (*) around words or phrases toemphasisze them." The '(*)' will not be recognized as markup. Thisreduces the need for markup escaping to the point where an escapecharacter isalmost (but not quite!) unnecessary.

Underlining

StructuredText uses '_text_' to indicate underlining. To quote DavidAscher in his 2000-01-21 Doc-SIG mailing list post, "Docstringgrammar: a very revised proposal":

The tagging of underlined text with _'s is suboptimal. Underlinesshouldn't be used from a typographic perspective (underlines weredesigned to be used in manuscripts to communicate to thetypesetter that the text should be italicized -- no well-typesetbook ever uses underlines), and conflict with double-underscoredPython variable names (__init__ and the like), which would gettruncated and underlined when that effect is not desired. Notethat whilecomplete markup would prevent that truncation('__init__'), I think of docstring markups much like I think oftype annotations -- they should be optional and above all do noharm. In this case the underline markup does harm.

Underlining is not part of the reStructuredText specification.

Inline Literals

StructuredText's markup for inline literals (text left as-is,verbatim, usually in a monospaced font; as in HTML <TT>) is singlequotes ('literals'). The problem with single quotes is that they aretoo often used for other purposes:

• Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'.";

• Quoting text:

  First Bruce: "Well Bruce, I heard the prime minister use it.'S'hot enough to boil a monkey's bum in 'ere your Majesty,' hesaid, and she smiled quietly to herself."

  In the UK, single quotes are used for dialogue in published works.

• String literals: s = ''

Alternatives:

'text'    \'text\'    ''text''    "text"    \"text\"    ""text""#text#     @text@      `text`     ^text^    ``text''    ``text``

The examples below contain inline literals, quoted text, andapostrophes. Each example should evaluate to the following HTML:

Some <TT>code</TT>, with a 'quote', "double", ain't it grand?Does <TT>a[b] = 'c' + "d" + `2^3`</TT> work?0. Some code, with a quote, double, ain't it grand?   Does a[b] = 'c' + "d" + `2^3` work?1. Some 'code', with a \'quote\', "double", ain\'t it grand?   Does 'a[b] = \'c\' + "d" + `2^3`' work?2. Some \'code\', with a 'quote', "double", ain't it grand?   Does \'a[b] = 'c' + "d" + `2^3`\' work?3. Some ''code'', with a 'quote', "double", ain't it grand?   Does ''a[b] = 'c' + "d" + `2^3`'' work?4. Some "code", with a 'quote', \"double\", ain't it grand?   Does "a[b] = 'c' + "d" + `2^3`" work?5. Some \"code\", with a 'quote', "double", ain't it grand?   Does \"a[b] = 'c' + "d" + `2^3`\" work?6. Some ""code"", with a 'quote', "double", ain't it grand?   Does ""a[b] = 'c' + "d" + `2^3`"" work?7. Some #code#, with a 'quote', "double", ain't it grand?   Does #a[b] = 'c' + "d" + `2^3`# work?8. Some @code@, with a 'quote', "double", ain't it grand?   Does @a[b] = 'c' + "d" + `2^3`@ work?9. Some `code`, with a 'quote', "double", ain't it grand?   Does `a[b] = 'c' + "d" + \`2^3\`` work?10. Some ^code^, with a 'quote', "double", ain't it grand?    Does ^a[b] = 'c' + "d" + `2\^3`^ work?11. Some ``code'', with a 'quote', "double", ain't it grand?    Does ``a[b] = 'c' + "d" + `2^3`'' work?12. Some ``code``, with a 'quote', "double", ain't it grand?    Does ``a[b] = 'c' + "d" + `2^3\``` work?

Backquotes (#9 & #12) are the best choice. They are unobtrusive andrelatviely rarely used (more rarely than ' or ", anyhow). Backquoteshave 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 descriptivemarkup) such as function name hyperlinks in Python docstrings, thendouble-backquotes could be used for absolute-literals, wherein noprocessing whatsoever takes place. An advantage of double-backquoteswould be that backslash-escaping would no longer be necessary forembedded single-backquotes; however, embedded double-backquotes (in anend-string context) would be illegal. SeeBackquotes inPhrase-Links inRecord of reStructuredText Syntax Alternatives.

Alternative choices are carets (#10) and TeX-style quotes (#11). Forexamples of TeX-style quoting, seehttp://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor.

Some existing uses of backquotes:

1. As a synonym for repr() in Python.

2. For command-interpolation in shell scripts.

3. Used as open-quotes in TeX code (and carried over into plaintextby TeXies).

The inline markup start-string and end-string recognition rulesdefined by thereStructuredText markup specification would allowall of these cases inside inline literals, with very few exceptions.As a fallback, literal blocks could handle all cases.

Outside of inline literals, the above uses of backquotes would requirebackslash-escaping. However, these are all prime examples of textthat 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 ofTeX-quotes should be done (at least at first). If TeX-quotes have tobe 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 forbackslash-escaping:

like this::    Here, we can do ``absolutely'' anything `'`'\|/|\ we like!

No mechanism for inline literals is perfect, just as no escapingmechanism is perfect. No matter what we use, complicated inlineexpressions involving the inline literal quote and/or the backslashwill end up looking ugly. We can only choose the least often uglyoption.

reStructuredText will use double backquotes for inline literals, andsingle backqoutes for interpreted text.

Hyperlinks

There are three forms of hyperlink currently inStructuredText:

1. (Absolute & relative URIs.) Text enclosed by double quotesfollowed by a colon, a URI, and concluded by punctuation plus whitespace, 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 acomma, one or more spaces, an absolute URI and concluded bypunctuation plus white space, or just white space, is treated as ahyperlink:

   "mail me", mailto:me@mail.com

3. (Endnotes.) Text enclosed by brackets link to an endnote at theend of the document: at the beginning of the line, two dots, aspace, and the same text in brackets, followed by the end noteitself:

   Please refer to the fine manual [GVR2001]... [GVR2001] Python Documentation, Release 2.1, van Rossum,   Drake, et al., http://www.python.org/doc/

The problem with forms 1 and 2 is that they are neither intuitive norunobtrusive (they break design goals 5 & 2). They overloaddouble-quotes, which are too often used in ordinary text (potentiallybreaking design goal 4). The brackets in form 3 are also too commonin ordinary text (such as [nested] asides and Python lists like [12]).

Alternatives:

1. Have no special markup for hyperlinks.

2. 1. Interpret and mark up hyperlinks as any contiguous textcontaining '://' or ':...@' (absolute URI) or '@' (emailaddress) after an alphanumeric word. To de-emphasize the URI,simply enclose it in parentheses:

      Python (http://www.python.org/)

   2. Leave special hyperlink markup as a domain-specific extension.Hyperlinks in ordinary reStructuredText documents would berequired to be standalone (i.e. the URI text inline in thedocument text). Processed hyperlinks (where the URI text ishidden behind the link) are important enough to warrant syntax.

3. The originalSetext introduced a mechanism of indirect hyperlinks.A source link word ('hot word') in the text was given a trailingunderscore:

   Here is some text with a hyperlink_ built in.

   The hyperlink itself appeared at the end of the document on a lineby itself, beginning with two dots, a space, the link word with aleading underscore, whitespace, and the URI itself:

   .. _hyperlink http://www.123.xyz

   Setext usedunderscores_instead_of_spaces_ for phrase links.

With some modification, alternative 3 best satisfies the design goals.It has the advantage of being readable and relatively unobtrusive.Since each source link must match up to a target, the odd variableending in an underscore can be spared being marked up (although itshould generate a "no such link target" warning). The onlydisadvantage is that phrase-links aren't possible without someobtrusive syntax.

We could achieve phrase-links if we enclose the link text:

1. in double quotes:

   "like this"_

2. in brackets:

   [like this]_

3. or in backquotes:

   `like this`_

Each gives us somewhat obtrusive markup, but that is unavoidable. Thebracketed syntax (#2) is reminiscent of links on many web pages(intuitive), although it is somewhat obtrusive. Alternative #3 ismuch less obtrusive, and is consistent with interpreted text: thetrailing underscore indicates the interpretation of the phrase, as ahyperlink. #3 also disambiguates hyperlinks from footnote references.Alternative #3 wins.

The same trailing underscore markup can also be used for footnote andcitation references, removing the problem with ordinary bracketed textand Python lists:

Please refer to the fine manual [GVR2000]_... [GVR2000] Python Documentation, van Rossum, Drake, et al.,   http://www.python.org/doc/

The two-dots-and-a-space syntax was generalized by Setext forcomments, which are removed from the (visible) processed output.reStructuredText uses this syntax for comments, footnotes, and linktarget, collectively termed "explicit markup". For link targets, inorder to eliminate ambiguity with comments and footnotes,reStructuredText specifies that a colon always follow the link targetword/phrase. The colon denotes 'maps to'. There is no reason torestrict target links to the end of the document; they could just aseasily be interspersed.

Internal hyperlinks (links from one point to another within a singledocument) can be expressed by a source link as before, and a targetlink with a colon but no URI. In effect, these targets 'map to' theelement immediately following.

As an added bonus, we now have a perfect candidate forreStructuredText directives, a simple extension mechanism: explicitmarkup containing a single word followed by two colons and whitespace.The interpretation of subsequent data on the directive line orfollowing is directive-dependent.

To summarize:

.. This is a comment... The line below is an example of a directive... version:: 1This is a footnote [1]_.This internal hyperlink will take us to the footnotes_ area below.Here is a one-word_ external hyperlink.Here is `a hyperlink phrase`_... _footnotes:.. [1] Footnote text goes here... external hyperlink target mappings:.. _one-word: http://www.123.xyz.. _a hyperlink phrase: http://www.123.xyz

The presence or absence of a colon after the target linkdifferentiates an indirect hyperlink from a footnote, respectively. Afootnote requires brackets. Backquotes around a target link word orphrase are required if the phrase contains a colon, optionalotherwise.

Below are examples using no markup, the two StructuredText hypertextstyles, and the reStructuredText hypertext style. Each examplecontains an indirect link, a direct link, a footnote/endnote, andbracketed 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><P><A NAME="eggs2000">[eggs2000]</A> "Spam, Spam, Spam, Eggs,Bacon, and Spam"</P>

1. No markup:

   A URI http://spam.org, see eggs2000 (in Bacon [Publisher]).Also see http://eggs.org.eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam"

2. StructuredText absolute/relative URI syntax("text":http://www.url.org):

   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"

   Note that StructuredText does not recognize standalone URIs,forcing doubling up as shown in the second line of the exampleabove.

3. StructuredText absolute-only URI syntax("text",mailto:you@your.com):

   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"

4. reStructuredText syntax:

   4. A URI_, see [eggs2000]_ (in Bacon [Publisher]).   Also see http://eggs.org.   .. _URI: http:/spam.org   .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"

The bracketed text '[Publisher]' may be problematic withStructuredText (syntax 2 & 3).

reStructuredText's syntax (#4) is definitely the most readable. Thetext is separated from the link URI and the footnote, resulting incleanly readable text.