/usr/share/doc/docutils-doc/docs/dev/rst/problems.html is in docutils-doc 0.14+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>Problems With StructuredText</title>
<meta name="author" content="David Goodger" />
<meta name="date" content="2012-01-03" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="problems-with-structuredtext">
<h1 class="title">Problems With StructuredText</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>David Goodger</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7302</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2012-01-03</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<p>There are several problems, unresolved issues, and areas of
controversy within <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> (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
proposes solutions to be incorporated into the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
specification.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#formal-specification" id="id3">Formal Specification</a></li>
<li><a class="reference internal" href="#understanding-and-extending-the-code" id="id4">Understanding and Extending the Code</a></li>
<li><a class="reference internal" href="#section-structure-via-indentation" id="id5">Section Structure via Indentation</a></li>
<li><a class="reference internal" href="#character-escaping-mechanism" id="id6">Character Escaping Mechanism</a></li>
<li><a class="reference internal" href="#blank-lines-in-lists" id="id7">Blank Lines in Lists</a></li>
<li><a class="reference internal" href="#bullet-list-markup" id="id8">Bullet List Markup</a></li>
<li><a class="reference internal" href="#enumerated-list-markup" id="id9">Enumerated List Markup</a></li>
<li><a class="reference internal" href="#definition-list-markup" id="id10">Definition List Markup</a></li>
<li><a class="reference internal" href="#literal-blocks" id="id11">Literal Blocks</a></li>
<li><a class="reference internal" href="#tables" id="id12">Tables</a></li>
<li><a class="reference internal" href="#delimitation-of-inline-markup" id="id13">Delimitation of Inline Markup</a></li>
<li><a class="reference internal" href="#underlining" id="id14">Underlining</a></li>
<li><a class="reference internal" href="#inline-literals" id="id15">Inline Literals</a></li>
<li><a class="reference internal" href="#hyperlinks" id="id16">Hyperlinks</a></li>
</ul>
</div>
<div class="section" id="formal-specification">
<h1><a class="toc-backref" href="#id3">Formal Specification</a></h1>
<p>The description in the original StructuredText.py has been criticized
for being vague. For practical purposes, "the code <em>is</em> the spec."
Tony Ibbs has been working on deducing a <a class="reference external" href="http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html">detailed description</a> from
the documentation and code of <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG">StructuredTextNG</a>. Edward Loper's
<a class="reference external" href="http://www.cis.upenn.edu/~edloper/pydoc/stminus.html">STMinus</a> is another attempt to formalize a spec.</p>
<p>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.</p>
</div>
<div class="section" id="understanding-and-extending-the-code">
<h1><a class="toc-backref" href="#id4">Understanding and Extending the Code</a></h1>
<p>The original <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> 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. <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG">StructuredTextNG</a> has
been designed to allow input (syntax) and output extensions, but its
documentation (both internal [comments & docstrings], and external) is
inadequate for the complexity of the code itself.</p>
<p>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
the specification preaches.</p>
</div>
<div class="section" id="section-structure-via-indentation">
<h1><a class="toc-backref" href="#id5">Section Structure via Indentation</a></h1>
<p><a class="reference external" href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a> required that body text be indented by 2 spaces. The original
<a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> and <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG">StructuredTextNG</a> 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 <em>itself</em> should
indicate that it is a section title.</p>
<p>The original StructuredText states that "A single-line paragraph whose
immediately succeeding paragraphs are lower level is treated as a
header." Requiring indentation in this way is:</p>
<ul class="simple">
<li>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.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>Python's use of significant whitespace is a wonderful (if not
original) innovation, however requiring indentation in ordinary
written text is hypergeneralization.</p>
<p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> 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
<a class="reference external" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/python/python/dist/src/README">README</a> file).</p>
</div>
<div class="section" id="character-escaping-mechanism">
<h1><a class="toc-backref" href="#id6">Character Escaping Mechanism</a></h1>
<p>No matter what characters are chosen for markup, some day someone will
want to write documentation <em>about</em> 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 '&ast;'
are out. So an escaping mechanism is in. However, with carefully
chosen markup, it should be necessary to use the escaping mechanism
only infrequently.</p>
<p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> 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?</p>
<ol class="arabic simple">
<li><tt class="docutils literal">!</tt>
(<a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping">http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping</a>)</li>
<li><tt class="docutils literal">\</tt></li>
<li><tt class="docutils literal">~</tt></li>
<li>doubling of characters</li>
</ol>
<p>The best choice for this is the backslash (<tt class="docutils literal">\</tt>). 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.</p>
<p>(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
escapes, saying, "'nuff said. Backslash it is." Although neither
legally binding nor irrevocable nor any kind of guarantee of anything,
it is a good sign.)</p>
<p>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.</p>
<p>A carefully constructed set of recognition rules for inline markup
will obviate the need for backslash-escapes in almost all cases; see
<a class="reference internal" href="#delimitation-of-inline-markup">Delimitation of Inline Markup</a> below.</p>
<p>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.</p>
<p>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.</p>
</div>
<div class="section" id="blank-lines-in-lists">
<h1><a class="toc-backref" href="#id7">Blank Lines in Lists</a></h1>
<p>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.
<a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> requires blank lines between all body elements,
including list items, even when boundaries are obvious from the markup
itself.</p>
<p>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.</p>
</div>
<div class="section" id="bullet-list-markup">
<h1><a class="toc-backref" href="#id8">Bullet List Markup</a></h1>
<p><a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> 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:</p>
<pre class="literal-block">
Llamame a la casa
o al trabajo.
(Call me at home or at work.)
</pre>
<p>And in Japanese (when romanized):</p>
<pre class="literal-block">
Senshuu no doyoubi ni tegami
o kakimashita.
([I] wrote a letter on Saturday last week.)
</pre>
<p>If a paragraph containing an 'o' word wraps such that the 'o' is the
first text on a line, or if a paragraph begins with such a word, it
could be misinterpreted as a bullet list.</p>
<p>In <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>, 'o' is not used as a bullet character. '-',
'*', and '+' are the possible bullet characters.</p>
</div>
<div class="section" id="enumerated-list-markup">
<h1><a class="toc-backref" href="#id9">Enumerated List Markup</a></h1>
<p>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:</p>
<pre class="literal-block">
Mr. Creosote.
</pre>
<p>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.</p>
<p>Rather, the parser should recognize a variety of enumerator styles.
It is also recommended that the enumerator of the first list item be
ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be
able to begin a list at an arbitrary enumeration.</p>
<p>An initial idea was to require two or more consistent enumerated list
items in a row. This idea proved impractical and was dropped. In
practice, the presence of a proper enumerator is enough to reliably
recognize an enumerated list item; any ambiguities are reported by the
parser. Here's the original idea for posterity:</p>
<blockquote>
<p>The parser should recognize a variety of enumerator styles, mark
each block as a potential enumerated list item (PELI), and
interpret the enumerators of adjacent PELIs to decide whether they
make up a consistent enumerated list.</p>
<p>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.</p>
<p>For an enumerated list to be recognized, the following must be
true:</p>
<ul class="simple">
<li>the list must consist of multiple adjacent list items (2 or
more)</li>
<li>the enumerators must all have the same format</li>
<li>the enumerators must be sequential</li>
</ul>
</blockquote>
</div>
<div class="section" id="definition-list-markup">
<h1><a class="toc-backref" href="#id10">Definition List Markup</a></h1>
<p>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).</p>
<p>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
official 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.</p>
<p>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:</p>
<pre class="literal-block">
term 1
Definition.
term 2
Definition 2, paragraph 1.
Definition 2, paragraph 2.
</pre>
<p>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).</p>
</div>
<div class="section" id="literal-blocks">
<h1><a class="toc-backref" href="#id11">Literal Blocks</a></h1>
<p>The <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a> 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 '::'.</p>
<p>In <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> '::' at the end of a paragraph indicates that
subsequent <em>indented</em> 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).</p>
<p>Thus, a section could begin with a literal block as follows:</p>
<pre class="literal-block">
Section Title
-------------
::
print "this is example literal"
</pre>
</div>
<div class="section" id="tables">
<h1><a class="toc-backref" href="#id12">Tables</a></h1>
<p>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:</p>
<ol class="arabic">
<li><p class="first">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 <a class="reference external" href="http://table.sourceforge.net/">Emacs table mode</a>:</p>
<pre class="literal-block">
+------------+------------+------------+--------------+
| 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 |
+------------+------------+------------+--------------+
</pre>
<p>Tables are described with a visual outline made up of the
characters '-', '=', '|', and '+':</p>
<ul class="simple">
<li>The hyphen ('-') is used for horizontal lines (row separators).</li>
<li>The equals sign ('=') is optionally used as a header separator
(as of version 1.5.24, this is not supported by the Emacs table
mode).</li>
<li>The vertical bar ('|') is used for for vertical lines (column
separators).</li>
<li>The plus sign ('+') is used for intersections of horizontal and
vertical lines.</li>
</ul>
<p>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.</p>
</li>
<li><p class="first">Below is a simpler table structure. 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.</p>
<pre class="literal-block">
============ ============ ============ ==============
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
============ ============ ============ ==============
</pre>
<p>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.</p>
</li>
<li><p class="first">A minimalist alternative is as follows:</p>
<pre class="literal-block">
==== ===== ======== ======== ======= ==== ===== =====
Old State Input Action New State Notes
----------- -------- ----------------- -----------
ids types new type sys.msg. dupname ids types
==== ===== ======== ======== ======= ==== ===== =====
-- -- explicit -- -- new True
-- -- implicit -- -- new False
None False explicit -- -- new True
old False explicit implicit old new True
None True explicit explicit new None True
old True explicit explicit new,old None True [1]
None False implicit implicit new None False
old False implicit implicit new,old None False
None True implicit implicit new None True
old True implicit implicit new old True
==== ===== ======== ======== ======= ==== ===== =====
</pre>
<p>The table begins with a top border of equals signs with one or more
spaces at each column boundary (regardless of spans). There must
be at least two columns in the table (to differentiate it from
section headers). Each line starts a new row. The rightmost
column is unbounded; text may continue past the edge of the table.
Each row/line must contain spaces at column boundaries, except for
explicit column spans. Underlines of '-' can be used to indicate
column spans, but should be used sparingly if at all. Lines
containing column span underlines may not contain any other text.
The last of the optional head rows is underlined with '=', again
with spaces at column boundaries. The bottom boundary of the table
consists of '=' underlines. A blank line is required following a
table.</p>
<p>This table sums up the features. Using all the features in such a
small space is not pretty though:</p>
<pre class="literal-block">
======== ======== ========
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.
======== ======== ========
</pre>
</li>
<li><p class="first">As a variation of alternative 3, bullet list syntax in the first
column could be used to indicate row starts. Multi-line rows are
possible, but row spans are not. For example:</p>
<pre class="literal-block">
===== =====
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
===== =====
</pre>
<p>Column spans would be indicated on the line after the last line of
the row. To indicate a real bullet list within a first-column
cell, simply nest the bullets.</p>
</li>
<li><p class="first">In a further variation, we could simply assume that whitespace in
the first column implies a multi-line row; the text in other
columns is continuation text. For example:</p>
<pre class="literal-block">
===== =====
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
===== =====
</pre>
<p>Limitations of this approach:</p>
<ul class="simple">
<li>Cells in the first column are limited to one line of text.</li>
<li>Cells in the first column <em>must</em> contain some text; blank cells
would lead to a misinterpretation. An empty comment ("..") is
sufficient.</li>
</ul>
</li>
<li><p class="first">Combining alternative 3 and 4, a bullet list in the first column
could mean multi-line rows, and no bullet list means single-line
rows only.</p>
</li>
</ol>
<p>Alternatives 1 and 5 has been adopted by reStructuredText.</p>
</div>
<div class="section" id="delimitation-of-inline-markup">
<h1><a class="toc-backref" href="#id13">Delimitation of Inline Markup</a></h1>
<p>StructuredText specifies that inline markup must begin with
whitespace, precluding such constructs as parenthesized or quoted
emphatic text:</p>
<pre class="literal-block">
"**What?**" she cried. (*exit stage left*)
</pre>
<p>The <a class="reference external" href="../../ref/rst/restructuredtext.html">reStructuredText markup specification</a> 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
<em>emphasisze</em> them." The '(*)' will not be recognized as markup. This
reduces the need for markup escaping to the point where an escape
character is <em>almost</em> (but not quite!) unnecessary.</p>
</div>
<div class="section" id="underlining">
<h1><a class="toc-backref" href="#id14">Underlining</a></h1>
<p>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":</p>
<blockquote>
The tagging of underlined text with _'s is suboptimal. Underlines
shouldn't be used from a typographic perspective (underlines were
designed to be used in manuscripts to communicate to the
typesetter that the text should be italicized -- no well-typeset
book ever uses underlines), and conflict with double-underscored
Python variable names (__init__ and the like), which would get
truncated and underlined when that effect is not desired. Note
that while <em>complete</em> markup would prevent that truncation
('__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.</blockquote>
<p>Underlining is not part of the reStructuredText specification.</p>
</div>
<div class="section" id="inline-literals">
<h1><a class="toc-backref" href="#id15">Inline Literals</a></h1>
<p>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:</p>
<ul>
<li><p class="first">Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'.";</p>
</li>
<li><p class="first">Quoting text:</p>
<blockquote>
<p>First Bruce: "Well Bruce, I heard the prime minister use it.
'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he
said, and she smiled quietly to herself."</p>
</blockquote>
<p>In the UK, single quotes are used for dialogue in published works.</p>
</li>
<li><p class="first">String literals: s = ''</p>
</li>
</ul>
<p>Alternatives:</p>
<pre class="literal-block">
'text' \'text\' ''text'' "text" \"text\" ""text""
#text# @text@ `text` ^text^ ``text'' ``text``
</pre>
<p>The examples below contain inline literals, quoted text, and
apostrophes. Each example should evaluate to the following HTML:</p>
<pre class="literal-block">
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?
</pre>
<p>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.</p>
<p>Analogously with <tt class="docutils literal">*emph*</tt> & <tt class="docutils literal">**strong**</tt>, 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 <a class="reference external" href="alternatives.html#backquotes-in-phrase-links">Backquotes in
Phrase-Links</a> in <a class="reference external" href="alternatives.html">Record of reStructuredText Syntax Alternatives</a>.</p>
<p>Alternative choices are carets (#10) and TeX-style quotes (#11). For
examples of TeX-style quoting, see
<a class="reference external" href="http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor">http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor</a>.</p>
<p>Some existing uses of backquotes:</p>
<ol class="arabic simple">
<li>As a synonym for repr() in Python.</li>
<li>For command-interpolation in shell scripts.</li>
<li>Used as open-quotes in TeX code (and carried over into plaintext
by TeXies).</li>
</ol>
<p>The inline markup start-string and end-string recognition rules
defined by the <a class="reference external" href="../../ref/rst/restructuredtext.html">reStructuredText markup specification</a> would allow
all of these cases inside inline literals, with very few exceptions.
As a fallback, literal blocks could handle all cases.</p>
<p>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.</p>
<p>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.</p>
<p>Using literal blocks is a fallback option which removes the need for
backslash-escaping:</p>
<pre class="literal-block">
like this::
Here, we can do ``absolutely'' anything `'`'\|/|\ we like!
</pre>
<p>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.</p>
<p>reStructuredText will use double backquotes for inline literals, and
single backqoutes for interpreted text.</p>
</div>
<div class="section" id="hyperlinks">
<h1><a class="toc-backref" href="#id16">Hyperlinks</a></h1>
<p>There are three forms of hyperlink currently in <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a>:</p>
<ol class="arabic">
<li><p class="first">(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:</p>
<pre class="literal-block">
"Python":http://www.python.org/
</pre>
</li>
<li><p class="first">(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
hyperlink:</p>
<pre class="literal-block">
"mail me", mailto:me@mail.com
</pre>
</li>
<li><p class="first">(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:</p>
<pre class="literal-block">
Please refer to the fine manual [GVR2001].
.. [GVR2001] Python Documentation, Release 2.1, van Rossum,
Drake, et al., http://www.python.org/doc/
</pre>
</li>
</ol>
<p>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]).</p>
<p>Alternatives:</p>
<ol class="arabic">
<li><p class="first">Have no special markup for hyperlinks.</p>
</li>
<li><ol class="first upperalpha">
<li><p class="first">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:</p>
<blockquote>
<p>Python (<a class="reference external" href="http://www.python.org/">http://www.python.org/</a>)</p>
</blockquote>
</li>
<li><p class="first">Leave special hyperlink markup as a domain-specific extension.
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.</p>
</li>
</ol>
</li>
<li><p class="first">The original <a class="reference external" href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a> introduced a mechanism of indirect hyperlinks.
A source link word ('hot word') in the text was given a trailing
underscore:</p>
<pre class="literal-block">
Here is some text with a hyperlink_ built in.
</pre>
<p>The hyperlink itself appeared at the end of the document on a line
by itself, beginning with two dots, a space, the link word with a
leading underscore, whitespace, and the URI itself:</p>
<pre class="literal-block">
.. _hyperlink http://www.123.xyz
</pre>
<p>Setext used <tt class="docutils literal">underscores_instead_of_spaces_</tt> for phrase links.</p>
</li>
</ol>
<p>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 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.</p>
<p>We could achieve phrase-links if we enclose the link text:</p>
<ol class="arabic">
<li><p class="first">in double quotes:</p>
<pre class="literal-block">
"like this"_
</pre>
</li>
<li><p class="first">in brackets:</p>
<pre class="literal-block">
[like this]_
</pre>
</li>
<li><p class="first">or in backquotes:</p>
<pre class="literal-block">
`like this`_
</pre>
</li>
</ol>
<p>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.</p>
<p>The same trailing underscore markup can also be used for footnote and
citation references, removing the problem with ordinary bracketed text
and Python lists:</p>
<pre class="literal-block">
Please refer to the fine manual [GVR2000]_.
.. [GVR2000] Python Documentation, van Rossum, Drake, et al.,
http://www.python.org/doc/
</pre>
<p>The two-dots-and-a-space syntax was generalized by Setext for
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.</p>
<p>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.</p>
<p>As an added bonus, we now have a perfect candidate for
reStructuredText directives, a simple extension mechanism: explicit
markup containing a single word followed by two colons and whitespace.
The interpretation of subsequent data on the directive line or
following is directive-dependent.</p>
<p>To summarize:</p>
<pre class="literal-block">
.. This is a comment.
.. The line below is an example of a directive.
.. version:: 1
This 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
</pre>
<p>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.</p>
<p>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>
<pre class="literal-block">
<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>
</pre>
<ol class="arabic">
<li><p class="first">No markup:</p>
<pre class="literal-block">
A URI http://spam.org, see eggs2000 (in Bacon [Publisher]).
Also see http://eggs.org.
eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam"
</pre>
</li>
<li><p class="first">StructuredText absolute/relative URI syntax
("text":<a class="reference external" href="http://www.url.org">http://www.url.org</a>):</p>
<pre class="literal-block">
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"
</pre>
<p>Note that StructuredText does not recognize standalone URIs,
forcing doubling up as shown in the second line of the example
above.</p>
</li>
<li><p class="first">StructuredText absolute-only URI syntax
("text", <a class="reference external" href="mailto:you@your.com">mailto:you@your.com</a>):</p>
<pre class="literal-block">
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"
</pre>
</li>
<li><p class="first">reStructuredText syntax:</p>
<pre class="literal-block">
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"
</pre>
</li>
</ol>
<p>The bracketed text '[Publisher]' may be problematic with
StructuredText (syntax 2 & 3).</p>
<p>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.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>
</div>
</body>
</html>
|