diff options
Diffstat (limited to 'docutils/docs/dev')
| -rw-r--r-- | docutils/docs/dev/pysource.dtd | 258 | ||||
| -rw-r--r-- | docutils/docs/dev/pysource.txt | 130 | ||||
| -rw-r--r-- | docutils/docs/dev/rst/alternatives.txt | 2005 | ||||
| -rw-r--r-- | docutils/docs/dev/rst/problems.txt | 870 | ||||
| -rw-r--r-- | docutils/docs/dev/semantics.txt | 119 | ||||
| -rw-r--r-- | docutils/docs/dev/todo.txt | 2114 |
6 files changed, 0 insertions, 5496 deletions
diff --git a/docutils/docs/dev/pysource.dtd b/docutils/docs/dev/pysource.dtd deleted file mode 100644 index 79a074cec..000000000 --- a/docutils/docs/dev/pysource.dtd +++ /dev/null @@ -1,258 +0,0 @@ -<!-- -====================================================================== - Docutils Python Source DTD -====================================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This DTD has been placed in the public domain. -:Filename: pysource.dtd - -This DTD (document type definition) extends the Generic DTD (see -below). - -More information about this DTD and the Docutils project can be found -at http://docutils.sourceforge.net/. The latest version of this DTD -is available from http://docutils.sourceforge.net/spec/pysource.dtd. - -The formal public identifier for this DTD is:: - - +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML ---> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Parameter Entity Overrides -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ENTITY % additional.section.elements - " | package_section | module_section | class_section - | method_section | function_section - | module_attribute_section | function_attribute_section - | class_attribute_section | instance_attribute_section "> - -<!ENTITY % additional.inline.elements - " | package | module | class | method | function - | variable | parameter | type | attribute - | module_attribute | class_attribute | instance_attribute - | exception_class | warning_class "> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Generic DTD -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This DTD extends the Docutils Generic DTD, available from -http://docutils.sourceforge.net/spec/docutils.dtd. ---> - -<!ENTITY % docutils PUBLIC - "+//IDN python.org//DTD Docutils Generic//EN//XML" - "docutils.dtd"> -%docutils; - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Section Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT package_section - (package, fullname?, import_list?, %structure.model;)> -<!ATTLIST package_section %basic.atts;> - -<!ELEMENT module_section - (module, fullname?, import_list?, %structure.model;)> -<!ATTLIST module_section %basic.atts;> - -<!ELEMENT class_section - (class, inheritance_list?, fullname?, subclasses?, - %structure.model;)> -<!ATTLIST class_section %basic.atts;> - -<!ELEMENT method_section - (method, parameter_list?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST method_section %basic.atts;> - -<!ELEMENT function_section - (function, parameter_list?, fullname?, %structure.model;)> -<!ATTLIST function_section %basic.atts;> - -<!ELEMENT module_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST module_attribute_section %basic.atts;> - -<!ELEMENT function_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST function_attribute_section %basic.atts;> - -<!ELEMENT class_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST class_attribute_section %basic.atts;> - -<!ELEMENT instance_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST instance_attribute_section %basic.atts;> - -<!-- - Section Subelements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT fullname - (package | module | class | method | function | attribute)+> -<!ATTLIST fullname %basic.atts;> - -<!ELEMENT import_list (import_item+)> -<!ATTLIST import_list %basic.atts;> - -<!-- -Support ``import module``, ``import module as alias``, ``from module -import identifier``, and ``from module import identifier as alias``. ---> -<!ELEMENT import_item (fullname, identifier?, alias?)> -<!ATTLIST import_item %basic.atts;> - -<!ELEMENT inheritance_list (class+)> -<!ATTLIST inheritance_list %basic.atts;> - -<!ELEMENT subclasses (class+)> -<!ATTLIST subclasses %basic.atts;> - -<!ELEMENT parameter_list - ((parameter_item+, optional_parameters*) | optional_parameters+)> -<!ATTLIST parameter_list %basic.atts;> - -<!ELEMENT parameter_item - ((parameter | parameter_tuple), parameter_default?)> -<!ATTLIST parameter_item %basic.atts;> - -<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)> -<!ATTLIST optional_parameters %basic.atts;> - -<!ELEMENT parameter_tuple (parameter | parameter_tuple)+> -<!ATTLIST parameter_tuple %basic.atts;> - -<!ELEMENT parameter_default (#PCDATA)> -<!ATTLIST parameter_default %basic.atts;> - -<!ELEMENT overrides (fullname+)> -<!ATTLIST overrides %basic.atts;> - -<!ELEMENT initial_value (#PCDATA)> -<!ATTLIST initial_value %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Inline Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Also used as the `package_section` identifier/title. --> -<!ELEMENT package (#PCDATA)> -<!ATTLIST package - %basic.atts; - %reference.atts;> - -<!-- Also used as the `module_section` identifier/title. --> -<!ELEMENT module (#PCDATA)> -<!ATTLIST module - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `class_section` identifier/title, and in the -`inheritance` element. ---> -<!ELEMENT class (#PCDATA)> -<!ATTLIST class - %basic.atts; - %reference.atts;> - -<!-- Also used as the `method_section` identifier/title. --> -<!ELEMENT method (#PCDATA)> -<!ATTLIST method - %basic.atts; - %reference.atts;> - -<!-- Also used as the `function_section` identifier/title. --> -<!ELEMENT function (#PCDATA)> -<!ATTLIST function - %basic.atts; - %reference.atts;> - -<!-- -??? Use this instead of the ``*_attribute`` elements below? Add a -"type" attribute to differentiate? - -Also used as the identifier/title for `module_attribute_section`, -`class_attribute_section`, and `instance_attribute_section`. ---> -<!ELEMENT attribute (#PCDATA)> -<!ATTLIST attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `module_attribute_section` identifier/title. A module -attribute is an exported module-level global variable. ---> -<!ELEMENT module_attribute (#PCDATA)> -<!ATTLIST module_attribute - %basic.atts; - %reference.atts;> - -<!-- Also used as the `class_attribute_section` identifier/title. --> -<!ELEMENT class_attribute (#PCDATA)> -<!ATTLIST class_attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `instance_attribute_section` identifier/title. ---> -<!ELEMENT instance_attribute (#PCDATA)> -<!ATTLIST instance_attribute - %basic.atts; - %reference.atts;> - -<!ELEMENT variable (#PCDATA)> -<!ATTLIST variable - %basic.atts; - %reference.atts;> - -<!-- Also used in `parameter_list`. --> -<!ELEMENT parameter (#PCDATA)> -<!ATTLIST parameter - %basic.atts; - %reference.atts; - excess_positional %yesorno; #IMPLIED - excess_keyword %yesorno; #IMPLIED> - -<!ELEMENT type (#PCDATA)> -<!ATTLIST type - %basic.atts; - %reference.atts;> - -<!ELEMENT exception_class (#PCDATA)> -<!ATTLIST exception_class - %basic.atts; - %reference.atts;> - -<!ELEMENT warning_class (#PCDATA)> -<!ATTLIST warning_class - %basic.atts; - %reference.atts;> - -<!-- -Local Variables: -mode: sgml -indent-tabs-mode: nil -fill-column: 70 -End: ---> diff --git a/docutils/docs/dev/pysource.txt b/docutils/docs/dev/pysource.txt deleted file mode 100644 index ab677a004..000000000 --- a/docutils/docs/dev/pysource.txt +++ /dev/null @@ -1,130 +0,0 @@ -====================== - Python Source Reader -====================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document explores issues around extracting and processing -docstrings from Python modules. - -For definitive element hierarchy details, see the "Python Plaintext -Document Interface DTD" XML document type definition, pysource.dtd_ -(which modifies the generic docutils.dtd_). Descriptions below list -'DTD elements' (XML 'generic identifiers' or tag names) corresponding -to syntax constructs. - - -.. contents:: - - -Model -===== - -The Python Source Reader ("PySource") model that's evolving in my mind -goes something like this: - -1. Extract the docstring/namespace [#]_ tree from the module(s) and/or - package(s). - - .. [#] See `Docstring Extractor`_ below. - -2. Run the parser on each docstring in turn, producing a forest of - doctrees (per nodes.py). - -3. Join the docstring trees together into a single tree, running - transforms: - - - merge hyperlinks - - merge namespaces - - create various sections like "Module Attributes", "Functions", - "Classes", "Class Attributes", etc.; see spec/ppdi.dtd - - convert the above special sections to ordinary doctree nodes - -4. Run transforms on the combined doctree. Examples: resolving - cross-references/hyperlinks (including interpreted text on Python - identifiers); footnote auto-numbering; first field list -> - bibliographic elements. - - (Or should step 4's transforms come before step 3?) - -5. Pass the resulting unified tree to the writer/builder. - -I've had trouble reconciling the roles of input parser and output -writer with the idea of modes ("readers" or "directors"). Does the -mode govern the tranformation of the input, the output, or both? -Perhaps the mode should be split into two. - -For example, say the source of our input is a Python module. Our -"input mode" should be the "Python Source Reader". It discovers (from -``__docformat__``) that the input parser is "reStructuredText". If we -want HTML, we'll specify the "HTML" output formatter. But there's a -piece missing. What *kind* or *style* of HTML output do we want? -PyDoc-style, LibRefMan style, etc. (many people will want to specify -and control their own style). Is the output style specific to a -particular output format (XML, HTML, etc.)? Is the style specific to -the input mode? Or can/should they be independent? - -I envision interaction between the input parser, an "input mode" , and -the output formatter. The same intermediate data format would be used -between each of these, being transformed as it progresses. - - -Docstring Extractor -=================== - -We need code that scans a parsed Python module, and returns an ordered -tree containing the names, docstrings (including attribute and -additional docstrings), and additional info (in parentheses below) of -all of the following objects: - -- packages -- modules -- module attributes (+ values) -- classes (+ inheritance) -- class attributes (+ values) -- instance attributes (+ values) -- methods (+ formal parameters & defaults) -- functions (+ formal parameters & defaults) - -(Extract comments too? For example, comments at the start of a module -would be a good place for bibliographic field lists.) - -In order to evaluate interpreted text cross-references, namespaces for -each of the above will also be required. - -See python-dev/docstring-develop thread "AST mining", started on -2001-08-14. - - -Interpreted Text -================ - -DTD elements: package, module, class, method, function, -module_attribute, class_attribute, instance_attribute, variable, -parameter, type, exception_class, warning_class. - -To classify identifiers explicitly, the role is given along with the -identifier in either prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - -The role may be one of 'package', 'module', 'class', 'method', -'function', 'module_attribute', 'class_attribute', -'instance_attribute', 'variable', 'parameter', 'type', -'exception_class', 'exception', 'warning_class', or 'warning'. Other -roles may be defined. - -.. _pysource.dtd: http://docutils.sourceforge.net/spec/pysource.dtd -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - End: diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt deleted file mode 100644 index b089d58b2..000000000 --- a/docutils/docs/dev/rst/alternatives.txt +++ /dev/null @@ -1,2005 +0,0 @@ -================================================== - A Record of reStructuredText Syntax Alternatives -================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -The following are ideas, alternatives, and justifications that were -considered for reStructuredText syntax, which did not originate with -Setext_ or StructuredText_. For an analysis of constructs which *did* -originate with StructuredText or Setext, please see `Problems With -StructuredText`_. See the `reStructuredText Markup Specification`_ -for full details of the established syntax. - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage -.. _Problems with StructuredText: problems.html -.. _reStructuredText Markup Specification: reStructuredText.html - - -.. contents:: - - -... Or Not To Do? -================= - -This is the realm of the possible but questionably probable. These -ideas are kept here as a record of what has been proposed, for -posterity and in case any of them prove to be useful. - - -Compound Enumerated Lists -------------------------- - -Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to -allow for nested enumerated lists without indentation? - - -Sloppy Indentation of List Items --------------------------------- - -Perhaps the indentation shouldn't be so strict. Currently, this is -required:: - - 1. First line, - second line. - -Anything wrong with this? :: - - 1. First line, - second line. - -Problem? :: - - 1. First para. - - Block quote. (no good: requires some indent relative to first - para) - - Second Para. - - 2. Have to carefully define where the literal block ends:: - - Literal block - - Literal block? - -Hmm... Non-strict indentation isn't such a good idea. - - -Lazy Indentation of List Items ------------------------------- - -Another approach: Going back to the first draft of reStructuredText -(2000-11-27 post to Doc-SIG):: - - - This is the fourth item of the main list (no blank line above). - The second line of this item is not indented relative to the - bullet, which precludes it from having a second paragraph. - -Change that to *require* a blank line above and below, to reduce -ambiguity. This "loosening" may be added later, once the parser's -been nailed down. However, a serious drawback of this approach is to -limit the content of each list item to a single paragraph. - - -David's Idea for Lazy Indentation -````````````````````````````````` - -Consider a paragraph in a word processor. It is a single logical line -of text which ends with a newline, soft-wrapped arbitrarily at the -right edge of the page or screen. We can think of a plaintext -paragraph in the same way, as a single logical line of text, ending -with two newlines (a blank line) instead of one, and which may contain -arbitrary line breaks (newlines) where it was accidentally -hard-wrapped by an application. We can compensate for the accidental -hard-wrapping by "unwrapping" every unindented second and subsequent -line. The indentation of the first line of a paragraph or list item -would determine the indentation for the entire element. Blank lines -would be required between list items when using lazy indentation. - -The following example shows the lazy indentation of multiple body -elements:: - - - This is the first paragraph - of the first list item. - - Here is the second paragraph - of the first list item. - - - This is the first paragraph - of the second list item. - - Here is the second paragraph - of the second list item. - -A more complex example shows the limitations of lazy indentation:: - - - This is the first paragraph - of the first list item. - - Next is a definition list item: - - Term - Definition. The indentation of the term is - required, as is the indentation of the definition's - first line. - - When the definition extends to more than - one line, lazy indentation may occur. (This is the second - paragraph of the definition.) - - - This is the first paragraph - of the second list item. - - - Here is the first paragraph of - the first item of a nested list. - - So this paragraph would be outside of the nested list, - but inside the second list item of the outer list. - - But this paragraph is not part of the list at all. - -And the ambiguity remains:: - - - Look at the hyphen at the beginning of the next line - - is it a second list item marker, or a dash in the text? - - Similarly, we may want to refer to numbers inside enumerated - lists: - - 1. How many socks in a pair? There are - 2. How many pants in a pair? Exactly - 1. Go figure. - -Literal blocks and block quotes would still require consistent -indentation for all their lines. For block quotes, we might be able -to get away with only requiring that the first line of each contained -element be indented. For example:: - - Here's a paragraph. - - This is a paragraph inside a block quote. - Second and subsequent lines need not be indented at all. - - - A bullet list inside - the block quote. - - Second paragraph of the - bullet list inside the block quote. - -Although feasible, this form of lazy indentation has problems. The -document structure and hierarchy is not obvious from the indentation, -making the source plaintext difficult to read. This will also make -keeping track of the indentation while writing difficult and -error-prone. However, these problems may be acceptable for Wikis and -email mode, where we may be able to rely on less complex structure -(few nested lists, for example). - - -Multiple Roles in Interpreted Text ----------------------------------- - -In reStructuredText, inline markup cannot be nested (yet; `see -below`__). This also applies to interpreted text. In order to -simultaneously combine multiple roles for a single piece of text, a -syntax extension would be necessary. Ideas: - -1. Initial idea:: - - `interpreted text`:role1,role2: - -2. Suggested by Jason Diamond:: - - `interpreted text`:role1:role2: - -If a document is so complex as to require nested inline markup, -perhaps another markup system should be considered. By design, -reStructuredText does not have the flexibility of XML. - -__ `Nested Inline Markup`_ - - -Parameterized Interpreted Text ------------------------------- - -In some cases it may be expedient to pass parameters to interpreted -text, analogous to function calls. Ideas: - -1. Parameterize the interpreted text role itself (suggested by Jason - Diamond):: - - `interpreted text`:role1(foo=bar): - - Positional parameters could also be supported:: - - `CSS`:acronym(Cascading Style Sheets): is used for HTML, and - `CSS`:acronym(Content Scrambling System): is used for DVDs. - - Technical problem: current interpreted text syntax does not - recognize roles containing whitespace. Design problem: this smells - like programming language syntax, but reStructuredText is not a - programming language. - -2. Put the parameters inside the interpreted text:: - - `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and - `CSS (Content Scrambling System)`:acronym: is used for DVDs. - - Although this could be defined on an individual basis (per role), - we ought to have a standard. Hyperlinks with embedded URIs already - use angle brackets; perhaps they could be used here too:: - - `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and - `CSS <Content Scrambling System>`:acronym: is used for DVDs. - - Do angle brackets connote URLs too much for this to be acceptable? - How about the "tag" connotation -- does it save them or doom them? - -Does this push inline markup too far? Readability becomes a serious -issue. Substitutions may provide a better alternative (at the expense -of verbosity and duplication) by pulling the details out of the text -flow:: - - |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. - - .. |CSS| acronym:: Cascading Style Sheets - .. |CSS-DVD| acronym:: Content Scrambling System - :text: CSS - ----------------------------------------------------------------------- - -This whole idea may be going beyond the scope of reStructuredText. -Documents requiring this functionality may be better off using XML or -another markup system. - -This argument comes up regularly when pushing the envelope of -reStructuredText syntax. I think it's a useful argument in that it -provides a check on creeping featurism. In many cases, the resulting -verbosity produces such unreadable plaintext that there's a natural -desire *not* to use it unless absolutely necessary. It's a matter of -finding the right balance. - - -Character Processing --------------------- - -Several people have suggested adding some form of character processing -to reStructuredText: - -* Some sort of automated replacement of ASCII sequences: - - - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). - - Convert quotes to curly quote entities. (Essentially impossible - for HTML? Unnecessary for TeX.) - - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to . Problem with line-wrapping though: it could - end up escaping the newline. - - Escaped newlines to <BR>. - - Escaped period or quote or dash as a disappearing catalyst to - allow character-level inline markup? - -* XML-style character entities, such as "©" for the copyright - symbol. - -Docutils has no need of a character entity subsystem. Supporting -Unicode and text encodings, character entities should be directly -represented in the text: a copyright symbol should be represented by -the copyright symbol character. If this is not possible in an -authoring environment, a pre-processing stage can be added, or a table -of substitution definitions can be devised. - -A "unicode" directive has been implemented to allow direct -specification of esoteric characters. In combination with the -substitution construct, "include" files defining common sets of -character entities can be defined and used. - -To allow for `character-level inline markup`_, a limited form of -character processing has been added to the spec and parser: escaped -whitespace characters are removed from the processed document. Any -further character processing will be of this functional type, rather -than of the character-encoding type. - -.. _character-level inline markup: - reStructuredText.html#character-level-inline-markup - - -Field Lists -=========== - -Prior to the syntax for field lists being finalized, several -alternatives were proposed. - -1. Unadorned RFC822_ everywhere:: - - Author: Me - Version: 1 - - Advantages: clean, precedent (RFC822-compliant). Disadvantage: - ambiguous (these paragraphs are a prime example). - - Conclusion: rejected. - -2. Special case: use unadorned RFC822_ for the very first or very last - text block of a document:: - - """ - Author: Me - Version: 1 - - The rest of the document... - """ - - Advantages: clean, precedent (RFC822-compliant). Disadvantages: - special case, flat (unnested) field lists only, still ambiguous:: - - """ - Usage: cmdname [options] arg1 arg2 ... - - We obviously *don't* want the like above to be interpreted as a - field list item. Or do we? - """ - - Conclusion: rejected for the general case, accepted for specific - contexts (PEPs, email). - -3. Use a directive:: - - .. fields:: - - Author: Me - Version: 1 - - Advantages: explicit and unambiguous, RFC822-compliant. - Disadvantage: cumbersome. - - Conclusion: rejected for the general case (but such a directive - could certainly be written). - -4. Use Javadoc-style:: - - @Author: Me - @Version: 1 - @param a: integer - - Advantages: unambiguous, precedent, flexible. Disadvantages: - non-intuitive, ugly, not RFC822-compliant. - - Conclusion: rejected. - -5. Use leading colons:: - - :Author: Me - :Version: 1 - - Advantages: unambiguous, obvious (*almost* RFC822-compliant), - flexible, perhaps even elegant. Disadvantages: no precedent, not - quite RFC822-compliant. - - Conclusion: accepted! - -6. Use double colons:: - - Author:: Me - Version:: 1 - - Advantages: unambiguous, obvious? (*almost* RFC822-compliant), - flexible, similar to syntax already used for literal blocks and - directives. Disadvantages: no precedent, not quite - RFC822-compliant, similar to syntax already used for literal blocks - and directives. - - Conclusion: rejected because of the syntax similarity & conflicts. - -Why is RFC822 compliance important? It's a universal Internet -standard, and super obvious. Also, I'd like to support the PEP format -(ulterior motive: get PEPs to use reStructuredText as their standard). -But it *would* be easy to get used to an alternative (easy even to -convert PEPs; probably harder to convert python-deviants ;-). - -Unfortunately, without well-defined context (such as in email headers: -RFC822 only applies before any blank lines), the RFC822 format is -ambiguous. It is very common in ordinary text. To implement field -lists unambiguously, we need explicit syntax. - -The following question was posed in a footnote: - - Should "bibliographic field lists" be defined at the parser level, - or at the DPS transformation level? In other words, are they - reStructuredText-specific, or would they also be applicable to - another (many/every other?) syntax? - -The answer is that bibliographic fields are a -reStructuredText-specific markup convention. Other syntaxes may -implement the bibliographic elements explicitly. For example, there -would be no need for such a transformation for an XML-based markup -syntax. - -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt - - -Interpreted Text "Roles" -======================== - -The original purpose of interpreted text was as a mechanism for -descriptive markup, to describe the nature or role of a word or -phrase. For example, in XML we could say "<function>len</function>" -to mark up "len" as a function. It is envisaged that within Python -docstrings (inline documentation in Python module source files, the -primary market for reStructuredText) the role of a piece of -interpreted text can be inferred implicitly from the context of the -docstring within the program source. For other applications, however, -the role may have to be indicated explicitly. - -Interpreted text is enclosed in single backquotes (`). - -1. Initially, it was proposed that an explicit role could be indicated - as a word or phrase within the enclosing backquotes: - - - As a prefix, separated by a colon and whitespace:: - - `role: interpreted text` - - - As a suffix, separated by whitespace and a colon:: - - `interpreted text :role` - - There are problems with the initial approach: - - - There could be ambiguity with interpreted text containing colons. - For example, an index entry of "Mission: Impossible" would - require a backslash-escaped colon. - - - The explicit role is descriptive markup, not content, and will - not be visible in the processed output. Putting it inside the - backquotes doesn't feel right; the *role* isn't being quoted. - -2. Tony Ibbs suggested that the role be placed outside the - backquotes:: - - role:`prefix` or `suffix`:role - - This removes the embedded-colons ambiguity, but limits the role - identifier to be a single word (whitespace would be illegal). - Since roles are not meant to be visible after processing, the lack - of whitespace support is not important. - - The suggested syntax remains ambiguous with respect to ratios and - some writing styles. For example, suppose there is a "signal" - identifier, and we write:: - - ...calculate the `signal`:noise ratio. - - "noise" looks like a role. - -3. As an improvement on #2, we can bracket the role with colons:: - - :role:`prefix` or `suffix`:role: - - This syntax is similar to that of field lists, which is fine since - both are doing similar things: describing. - - This is the syntax chosen for reStructuredText. - -4. Another alternative is two colons instead of one:: - - role::`prefix` or `suffix`::role - - But this is used for analogies ("A:B::C:D": "A is to B as C is to - D"). - - Both alternative #2 and #4 lack delimiters on both sides of the - role, making it difficult to parse (by the reader). - -5. Some kind of bracketing could be used: - - - Parentheses:: - - (role)`prefix` or `suffix`(role) - - - Braces:: - - {role}`prefix` or `suffix`{role} - - - Square brackets:: - - [role]`prefix` or `suffix`[role] - - - Angle brackets:: - - <role>`prefix` or `suffix`<role> - - (The overlap of \*ML tags with angle brackets would be too - confusing and precludes their use.) - -Syntax #3 was chosen for reStructuredText. - - -Comments -======== - -A problem with comments (actually, with all indented constructs) is -that they cannot be followed by an indented block -- a block quote -- -without swallowing it up. - -I thought that perhaps comments should be one-liners only. But would -this mean that footnotes, hyperlink targets, and directives must then -also be one-liners? Not a good solution. - -Tony Ibbs suggested a "comment" directive. I added that we could -limit a comment to a single text block, and that a "multi-block -comment" could use "comment-start" and "comment-end" directives. This -would remove the indentation incompatibility. A "comment" directive -automatically suggests "footnote" and (hyperlink) "target" directives -as well. This could go on forever! Bad choice. - -Garth Kidd suggested that an "empty comment", a ".." explicit markup -start with nothing on the first line (except possibly whitespace) and -a blank line immediately following, could serve as an "unindent". An -empty comment does **not** swallow up indented blocks following it, -so block quotes are safe. "A tiny but practical wart." Accepted. - - -Anonymous Hyperlinks -==================== - -Alan Jaffray came up with this idea, along with the following syntax:: - - Search the `Python DOC-SIG mailing list archives`{}_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -The idea is sound and useful. I suggested a "double underscore" -syntax:: - - Search the `Python DOC-SIG mailing list archives`__. - - .. __: http://mail.python.org/pipermail/doc-sig/ - -But perhaps single underscores are okay? The syntax looks better, but -the hyperlink itself doesn't explicitly say "anonymous":: - - Search the `Python DOC-SIG mailing list archives`_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -Mixing anonymous and named hyperlinks becomes confusing. The order of -targets is not significant for named hyperlinks, but it is for -anonymous hyperlinks:: - - Hyperlinks: anonymous_, named_, and another anonymous_. - - .. _named: named - .. _: anonymous1 - .. _: anonymous2 - -Without the extra syntax of double underscores, determining which -hyperlink references are anonymous may be difficult. We'd have to -check which references don't have corresponding targets, and match -those up with anonymous targets. Keeping to a simple consistent -ordering (as with auto-numbered footnotes) seems simplest. - -reStructuredText will use the explicit double-underscore syntax for -anonymous hyperlinks. An alternative (see `Reworking Explicit -Markup`_ below) for the somewhat awkward ".. __:" syntax is "__":: - - An anonymous__ reference. - - __ http://anonymous - - -Reworking Explicit Markup -========================= - -Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added -to reStructuredText. Subsequently it was asserted that hyperlinks -(especially anonymous hyperlinks) would play an increasingly important -role in reStructuredText documents, and therefore they require a -simpler and more concise syntax. This prompted a review of the -current and proposed explicit markup syntaxes with regards to -improving usability. - -1. Original syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - .. Note:: - - The comment text was intentionally made to look like a hyperlink - target. - - Origins: - - * Except for the colon (a delimiter necessary to allow for - phrase-links), hyperlink target ``.. _blah:`` comes from Setext. - * Comment syntax from Setext. - * Footnote syntax from StructuredText ("named links"). - * Directives and anonymous hyperlinks original to reStructuredText. - - Advantages: - - + Consistent explicit markup indicator: "..". - + Consistent hyperlink syntax: ".. _" & ":". - - Disadvantages: - - - Anonymous target markup is awkward: ".. __:". - - The explicit markup indicator ("..") is excessively overloaded? - - Comment text is limited (can't look like a footnote, hyperlink, - or directive). But this is probably not important. - -2. Alan Jaffray's proposed syntax #1:: - - __ _blah internal hyperlink target - __ blah: http://somewhere external hyperlink target - __ blah: blahblah_ indirect hyperlink target - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - __ [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - The hyperlink-connoted underscores have become first-level syntax. - - Advantages: - - + Anonymous targets are simpler. - + All hyperlink targets are one character shorter. - - Disadvantages: - - - Inconsistent internal hyperlink targets. Unlike all other named - hyperlink targets, there's no colon. There's an extra leading - underscore, but we can't drop it because without it, "blah" looks - like a relative URI. Unless we restore the colon:: - - __ blah: internal hyperlink target - - - Obtrusive markup? - -3. Alan Jaffray's proposed syntax #2:: - - .. _blah internal hyperlink target - .. blah: http://somewhere external hyperlink target - .. blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - !! blah: http://somewhere directive - ## blah: http://somewhere comment - - Leading underscores have been (almost) replaced by "..", while - comments and directives have gained their own syntax. - - Advantages: - - + Anonymous hyperlinks are simpler. - + Unique syntax for comments. Connotation of "comment" from - some programming languages (including our favorite). - + Unique syntax for directives. Connotation of "action!". - - Disadvantages: - - - Inconsistent internal hyperlink targets. Again, unlike all other - named hyperlink targets, there's no colon. There's a leading - underscore, matching the trailing underscores of references, - which no other hyperlink targets have. We can't drop that one - leading underscore though: without it, "blah" looks like a - relative URI. Again, unless we restore the colon:: - - .. blah: internal hyperlink target - - - All (except for internal) hyperlink targets lack their leading - underscores, losing the "hyperlink" connotation. - - - Obtrusive syntax for comments. Alternatives:: - - ;; blah: http://somewhere - (also comment syntax in Lisp & others) - ,, blah: http://somewhere - ("comma comma": sounds like "comment"!) - - - Iffy syntax for directives. Alternatives? - -4. Tony Ibbs' proposed syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - This is the same as the current syntax, except for anonymous - targets which drop their "__: ". - - Advantage: - - + Anonymous targets are simpler. - - Disadvantages: - - - Anonymous targets lack their leading underscores, losing the - "hyperlink" connotation. - - Anonymous targets are almost indistinguishable from comments. - (Better to know "up front".) - -5. David Goodger's proposed syntax: Perhaps going back to one of - Alan's earlier suggestions might be the best solution. How about - simply adding "__ " as a synonym for ".. __: " in the original - syntax? These would become equivalent:: - - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - -Alternative 5 has been adopted. - - -Backquotes in Phrase-Links -========================== - -[From a 2001-06-05 Doc-SIG post in reply to questions from Doug -Hellmann.] - -The first draft of the spec, posted to the Doc-SIG in November 2000, -used square brackets for phrase-links. I changed my mind because: - -1. In the first draft, I had already decided on single-backquotes for - inline literal text. - -2. However, I wanted to minimize the necessity for backslash escapes, - for example when quoting Python repr-equivalent syntax that uses - backquotes. - -3. The processing of identifiers (function/method/attribute/module - etc. names) into hyperlinks is a useful feature. PyDoc recognizes - identifiers heuristically, but it doesn't take much imagination to - come up with counter-examples where PyDoc's heuristics would result - in embarassing failure. I wanted to do it deterministically, and - that called for syntax. I called this construct "interpreted - text". - -4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the - idea of using double-backquotes as syntax. - -5. I worked out some rules for inline markup recognition. - -6. In combination with #5, double backquotes lent themselves to inline - literals, neatly satisfying #2, minimizing backslash escapes. In - fact, the spec says that no interpretation of any kind is done - within double-backquote inline literal text; backslashes do *no* - escaping within literal text. - -7. Single backquotes are then freed up for interpreted text. - -8. I already had square brackets required for footnote references. - -9. Since interpreted text will typically turn into hyperlinks, it was - a natural fit to use backquotes as the phrase-quoting syntax for - trailing-underscore hyperlinks. - -The original inspiration for the trailing underscore hyperlink syntax -was Setext. But for phrases Setext used a very cumbersome -``underscores_between_words_like_this_`` syntax. - -The underscores can be viewed as if they were right-pointing arrows: -``-->``. So ``hyperlink_`` points away from the reference, and -``.. _hyperlink:`` points toward the target. - - -Substitution Mechanism -====================== - -Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by -Alan Jaffray, "reStructuredText inline markup". It reminded me of a -missing piece of the reStructuredText puzzle, first referred to in my -contribution to "Documentation markup & processing / PEPs" (Doc-SIG -2001-06-21). - -Substitutions allow the power and flexibility of directives to be -shared by inline text. They are a way to allow arbitrarily complex -inline objects, while keeping the details out of the flow of text. -They are the equivalent of SGML/XML's named entities. For example, an -inline image (using reference syntax alternative 4d (vertical bars) -and definition alternative 3, the alternatives chosen for inclusion in -the spec):: - - The |biohazard| symbol must be used on containers used to dispose - of medical waste. - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -The ``|biohazard|`` substitution reference will be replaced in-line by -whatever the ``.. |biohazard|`` substitution definition generates (in -this case, an image). A substitution definition contains the -substitution text bracketed with vertical bars, followed by a an -embedded inline-compatible directive, such as "image". A transform is -required to complete the substitution. - -Syntax alternatives for the reference: - -1. Use the existing interpreted text syntax, with a predefined role - such as "sub":: - - The `biohazard`:sub: symbol... - - Advantages: existing syntax, explicit. Disadvantages: verbose, - obtrusive. - -2. Use a variant of the interpreted text syntax, with a new suffix - akin to the underscore in phrase-link references:: - - (a) `name`@ - (b) `name`# - (c) `name`& - (d) `name`/ - (e) `name`< - (f) `name`:: - (g) `name`: - - - Due to incompatibility with other constructs and ordinary text - usage, (f) and (g) are not possible. - -3. Use interpreted text syntax with a fixed internal format:: - - (a) `:name:` - (b) `name:` - (c) `name::` - (d) `::name::` - (e) `%name%` - (f) `#name#` - (g) `/name/` - (h) `&name&` - (i) `|name|` - (j) `[name]` - (k) `<name>` - (l) `&name;` - (m) `'name'` - - To avoid ML confusion (k) and (l) are definitely out. Square - brackets (j) won't work in the target (the substitution definition - would be indistinguishable from a footnote). - - The ```/name/``` syntax (g) is reminiscent of "s/find/sub" - substitution syntax in ed-like languages. However, it may have a - misleading association with regexps, and looks like an absolute - POSIX path. (i) is visually equivalent and lacking the - connotations. - - A disadvantage of all of these is that they limit interpreted text, - albeit only slightly. - -4. Use specialized syntax, something new:: - - (a) #name# - (b) @name@ - (c) /name/ - (d) |name| - (e) <<name>> - (f) //name// - (g) ||name|| - (h) ^name^ - (i) [[name]] - (j) ~name~ - (k) !name! - (l) =name= - (m) ?name? - (n) >name< - - "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes - looks just like a POSIX path; it is likely for such usage to appear - in text. - - "|" (d) and "^" (h) are feasible. - -5. Redefine the trailing underscore syntax. See definition syntax - alternative 4, below. - -Syntax alternatives for the definition: - -1. Use the existing directive syntax, with a predefined directive such - as "sub". It contains a further embedded directive resolving to an - inline-compatible object:: - - .. sub:: biohazard - .. image:: biohazard.png - [height=20 width=20] - - .. sub:: parrot - That bird wouldn't *voom* if you put 10,000,000 volts - through it! - - The advantages and disadvantages are the same as in inline - alternative 1. - -2. Use syntax as in #1, but with an embedded directivecompressed:: - - .. sub:: biohazard image:: biohazard.png - [height=20 width=20] - - This is a bit better than alternative 1, but still too much. - -3. Use a variant of directive syntax, incorporating the substitution - text, obviating the need for a special "sub" directive name. If we - assume reference alternative 4d (vertical bars), the matching - definition would look like this:: - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) - - Instead of adding new syntax, redefine the trailing underscore - syntax to mean "substitution reference" instead of "hyperlink - reference". Alan's example:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj [user=jhl] - .. _Zope: http://www.zope.org/ - - A problem with the proposed syntax is that URIs which look like - simple reference names (alphanum plus ".", "-", "_") would be - indistinguishable from substitution directive names. A more - consistent syntax would be:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj:: user=jhl - .. _Zope: http://www.zope.org/ - - (``::`` after ``.. _Jonathan: lj``.) - - The "Zope" target is a simple external hyperlink, but the - "Jonathan" target contains a directive. Alan proposed is that the - reference text be replaced by whatever the referenced directive - (the "directive target") produces. A directive reference becomes a - hyperlink reference if the contents of the directive target resolve - to a hyperlink. If the directive target resolves to an icon, the - reference is replaced by an inline icon. If the directive target - resolves to a hyperlink, the directive reference becomes a - hyperlink reference. - - This seems too indirect and complicated for easy comprehension. - - The reference in the text will sometimes become a link, sometimes - not. Sometimes the reference text will remain, sometimes not. We - don't know *at the reference*:: - - This is a `hyperlink reference`_; its text will remain. - This is an `inline icon`_; its text will disappear. - - That's a problem. - -The syntax that has been incorporated into the spec and parser is -reference alternative 4d with definition alternative 3:: - - The |biohazard| symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -We can also combine substitution references with hyperlink references, -by appending a "_" (named hyperlink reference) or "__" (anonymous -hyperlink reference) suffix to the substitution reference. This -allows us to click on an image-link:: - - The |biohazard|_ symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - .. _biohazard: http://www.cdc.gov/ - -There have been several suggestions for the naming of these -constructs, originally called "substitution references" and -"substitutions". - -1. Candidate names for the reference construct: - - (a) substitution reference - (b) tagging reference - (c) inline directive reference - (d) directive reference - (e) indirect inline directive reference - (f) inline directive placeholder - (g) inline directive insertion reference - (h) directive insertion reference - (i) insertion reference - (j) directive macro reference - (k) macro reference - (l) substitution directive reference - -2. Candidate names for the definition construct: - - (a) substitution - (b) substitution directive - (c) tag - (d) tagged directive - (e) directive target - (f) inline directive - (g) inline directive definition - (h) referenced directive - (i) indirect directive - (j) indirect directive definition - (k) directive definition - (l) indirect inline directive - (m) named directive definition - (n) inline directive insertion definition - (o) directive insertion definition - (p) insertion definition - (q) insertion directive - (r) substitution definition - (s) directive macro definition - (t) macro definition - (u) substitution directive definition - (v) substitution definition - -"Inline directive reference" (1c) seems to be an appropriate term at -first, but the term "inline" is redundant in the case of the -reference. Its counterpart "inline directive definition" (2g) is -awkward, because the directive definition itself is not inline. - -"Directive reference" (1d) and "directive definition" (2k) are too -vague. "Directive definition" could be used to refer to any -directive, not just those used for inline substitutions. - -One meaning of the term "macro" (1k, 2s, 2t) is too -programming-language-specific. Also, macros are typically simple text -substitution mechanisms: the text is substituted first and evaluated -later. reStructuredText substitution definitions are evaluated in -place at parse time and substituted afterwards. - -"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that -something new is getting added rather than one construct being -replaced by another. - -Which brings us back to "substitution". The overall best names are -"substitution reference" (1a) and "substitution definition" (2v). A -long way to go to add one word! - - -Reworking Footnotes -=================== - -As a further wrinkle (see `Reworking Explicit Markup`_ above), in the -wee hours of 2002-02-28 I posted several ideas for changes to footnote -syntax: - - - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... - - Differentiate (with new DTD elements) author-date "citations" - (``[GVR2002]``) from numbered footnotes? ... - - Render footnote references as superscripts without "[]"? ... - -These ideas are all related, and suggest changes in the -reStructuredText syntax as well as the docutils tree model. - -The footnote has been used for both true footnotes (asides expanding -on points or defining terms) and for citations (references to external -works). Rather than dealing with one amalgam construct, we could -separate the current footnote concept into strict footnotes and -citations. Citations could be interpreted and treated differently -from footnotes. Footnotes would be limited to numerical labels: -manual ("1") and auto-numbered (anonymous "#", named "#label"). - -The footnote is the only explicit markup construct (starts with ".. ") -that directly translates to a visible body element. I've always been -a little bit uncomfortable with the ".. " marker for footnotes because -of this; ".. " has a connotation of "special", but footnotes aren't -especially "special". Printed texts often put footnotes at the bottom -of the page where the reference occurs (thus "foot note"). Some HTML -designs would leave footnotes to be rendered the same positions where -they're defined. Other online and printed designs will gather -footnotes into a section near the end of the document, converting them -to "endnotes" (perhaps using a directive in our case); but this -"special processing" is not an intrinsic property of the footnote -itself, but a decision made by the document author or processing -system. - -Citations are almost invariably collected in a section at the end of a -document or section. Citations "disappear" from where they are -defined and are magically reinserted at some well-defined point. -There's more of a connection to the "special" connotation of the ".. " -syntax. The point at which the list of citations is inserted could be -defined manually by a directive (e.g., ".. citations::"), and/or have -default behavior (e.g., a section automatically inserted at the end of -the document) that might be influenced by options to the Writer. - -Syntax proposals: - -+ Footnotes: - - - Current syntax:: - - .. [1] Footnote 1 - .. [#] Auto-numbered footnote. - .. [#label] Auto-labeled footnote. - - - The syntax proposed in the original 2002-02-28 Doc-SIG post: - remove the ".. ", prefix a "_":: - - _[1] Footnote 1 - _[#] Auto-numbered footnote. - _[#label] Auto-labeled footnote. - - The leading underscore syntax (earlier dropped because - ``.. _[1]:`` was too verbose) is a useful reminder that footnotes - are hyperlink targets. - - - Minimal syntax: remove the ".. [" and "]", prefix a "_", and - suffix a ".":: - - _1. Footnote 1. - _#. Auto-numbered footnote. - _#label. Auto-labeled footnote. - - ``_1.``, ``_#.``, and ``_#label.`` are markers, - like list markers. - - Footnotes could be rendered something like this in HTML - - | 1. This is a footnote. The brackets could be dropped - | from the label, and a vertical bar could set them - | off from the rest of the document in the HTML. - - Two-way hyperlinks on the footnote marker ("1." above) would also - help to differentiate footnotes from enumerated lists. - - If converted to endnotes (by a directive/transform), a horizontal - half-line might be used instead. Page-oriented output formats - would typically use the horizontal line for true footnotes. - -+ Footnote references: - - - Current syntax:: - - [1]_, [#]_, [#label]_ - - - Minimal syntax to match the minimal footnote syntax above:: - - 1_, #_, #label_ - - As a consequence, pure-numeric hyperlink references would not be - possible; they'd be interpreted as footnote references. - -+ Citation references: no change is proposed from the current footnote - reference syntax:: - - [GVR2001]_ - -+ Citations: - - - Current syntax (footnote syntax):: - - .. [GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - - Possible new syntax:: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - _[DJG2002] - Docutils: Python Documentation Utilities project; Goodger - et al.; http://docutils.sourceforge.net/ - - Without the ".. " marker, subsequent lines would either have to - align as in one of the above, or we'd have to allow loose - alignment (I'd rather not):: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - -I proposed adopting the "minimal" syntax for footnotes and footnote -references, and adding citations and citation references to -reStructuredText's repertoire. The current footnote syntax for -citations is better than the alternatives given. - -From a reply by Tony Ibbs on 2002-03-01: - - However, I think easier with examples, so let's create one:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - .. [1] That is, little bits of referenced text at the - bottom of the page. - .. [2] Because Terry himself does, of course [3]_. - .. [3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - .. [4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - and look at it with the second syntax proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - _[1] That is, little bits of referenced text at the - bottom of the page. - _[2] Because Terry himself does, of course [3]_. - _[3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _[4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - (I note here that if I have gotten the indentation of the - footnotes themselves correct, this is clearly not as nice. And if - the indentation should be to the left margin instead, I like that - even less). - - and the third (new) proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes 1_ in their own writings than other people - 2_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style 4_, particularly in emails (not a medium that - lends itself to footnotes). - - _1. That is, little bits of referenced text at the - bottom of the page. - _2. Because Terry himself does, of course 3_. - _3. Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _4. Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - I think I don't, in practice, mind the targets too much (the use - of a dot after the number helps a lot here), but I do have a - problem with the body text, in that I don't naturally separate out - the footnotes as different than the rest of the text - instead I - keep wondering why there are numbers interspered in the text. The - use of brackets around the numbers ([ and ]) made me somehow parse - the footnote references as "odd" - i.e., not part of the body text - - and thus both easier to skip, and also (paradoxically) easier to - pick out so that I could follow them. - - Thus, for the moment (and as always susceptable to argument), I'd - say -1 on the new form of footnote reference (i.e., I much prefer - the existing ``[1]_`` over the proposed ``1_``), and ambivalent - over the proposed target change. - - That leaves David's problem of wanting to distinguish footnotes - and citations - and the only thing I can propose there is that - footnotes are numeric or # and citations are not (which, as a - human being, I can probably cope with!). - -From a reply by Paul Moore on 2002-03-01: - - I think the current footnote syntax ``[1]_`` is *exactly* the - right balance of distinctness vs unobtrusiveness. I very - definitely don't think this should change. - - On the target change, it doesn't matter much to me. - -From a further reply by Tony Ibbs on 2002-03-01, referring to the -"[1]" form and actual usage in email: - - Clearly this is a form people are used to, and thus we should - consider it strongly (in the same way that the usage of ``*..*`` - to mean emphasis was taken partly from email practise). - - Equally clearly, there is something "magical" for people in the - use of a similar form (i.e., ``[1]``) for both footnote reference - and footnote target - it seems natural to keep them similar. - - ... - - I think that this established plaintext usage leads me to strongly - believe we should retain square brackets at both ends of a - footnote. The markup of the reference end (a single trailing - underscore) seems about as minimal as we can get away with. The - markup of the target end depends on how one envisages the thing - - if ".." means "I am a target" (as I tend to see it), then that's - good, but one can also argue that the "_[1]" syntax has a neat - symmetry with the footnote reference itself, if one wishes (in - which case ".." presumably means "hidden/special" as David seems - to think, which is why one needs a ".." *and* a leading underline - for hyperlink targets. - -Given the persuading arguments voiced, we'll leave footnote & footnote -reference syntax alone. Except that these discussions gave rise to -the "auto-symbol footnote" concept, which has been added. Citations -and citation references have also been added. - - -Auto-Enumerated Lists -===================== - -The advantage of auto-numbered enumerated lists would be similar to -that of auto-numbered footnotes: lists could be written and rearranged -without having to manually renumber them. The disadvantages are also -the same: input and output wouldn't match exactly; the markup may be -ugly or confusing (depending on which alternative is chosen). - -1. Use the "#" symbol. Example:: - - #. Item 1. - #. Item 2. - #. Item 3. - - Advantages: simple, explicit. Disadvantage: enumeration sequence - cannot be specified (limited to arabic numerals); ugly. - -2. As a variation on #1, first initialize the enumeration sequence? - For example:: - - a) Item a. - #) Item b. - #) Item c. - - Advantages: simple, explicit, any enumeration sequence possible. - Disadvantages: ugly; perhaps confusing with mixed concrete/abstract - enumerators. - -3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: - - 1. Item 1. - 1. Item 2. - 1. Item 3. - - Advantages: enumeration sequence is explicit (could be multiple - "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise - erroneous input (e.g., a duplicate item "1.") would pass silently, - either causing a problem later in the list (if no blank lines - between items) or creating two lists (with blanks). - - Take this input for example:: - - 1. Item 1. - - 1. Unintentional duplicate of item 1. - - 2. Item 2. - - Currently the parser will produce two list, "1" and "1,2" (no - warnings, because of the presence of blank lines). Using Fred's - notation, the current behavior is "1,1,2 -> 1 1,2" (without blank - lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What - should the behavior be with auto-numbering? - - Fred has produced a patch__, whose initial behavior is as follows:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2,3 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2,3 [WARNING] 3 - 1,1,2 -> 1,2 [WARNING] 2 - - (After the "[WARNING]", the "3" would begin a new list.) - - I have mixed feelings about adding this functionality to the spec & - parser. It would certainly be useful to some users (myself - included; I often have to renumber lists). Perhaps it's too - clever, asking the parser to guess too much. What if you *do* want - three one-item lists in a row, each beginning with "1."? You'd - have to use empty comments to force breaks. Also, I question - whether "1,2,2 -> 1,2,3" is optimal behavior. - - In response, Fred came up with "a stricter and more explicit rule - [which] would be to only auto-number silently if *all* the - enumerators of a list were identical". In that case:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2 [WARNING] 2 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2 [WARNING] 2,3 - 1,1,2 -> 1,2 [WARNING] 2 - - Should any start-value be allowed ("3,3,3"), or should - auto-numbered lists be limited to begin with ordinal-1 ("1", "A", - "a", "I", or "i")? - - __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 - &group_id=38414&atid=422032 - -4. Alternative proposed by Tony Ibbs:: - - #1. First item. - #3. Aha - I edited this in later. - #2. Second item. - - The initial proposal required unique enumerators within a list, but - this limits the convenience of a feature of already limited - applicability and convenience. Not a useful requirement; dropped. - - Instead, simply prepend a "#" to a standard list enumerator to - indicate auto-enumeration. The numbers (or letters) of the - enumerators themselves are not significant, except: - - - as a sequence indicator (arabic, roman, alphabetic; upper/lower), - - - and perhaps as a start value (first list item). - - Advantages: explicit, any enumeration sequence possible. - Disadvantages: a bit ugly. - - -Inline External Targets -======================= - -Currently reStructuredText has two hyperlink syntax variations: - -* Named hyperlinks:: - - This is a named reference_ of one word ("reference"). Here is - a `phrase reference`_. Phrase references may even cross `line - boundaries`_. - - .. _reference: http://www.example.org/reference/ - .. _phrase reference: http://www.example.org/phrase_reference/ - .. _line boundaries: http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - Each target may be reused multiple times (e.g., just write - ``"reference_"`` again). - - No syncronized ordering of references and targets is necessary. - - + Disadvantages: - - - The reference text must be repeated as target names; could lead - to mistakes. - - The target URLs may be located far from the references, and hard - to find in the plaintext. - -* Anonymous hyperlinks (in current reStructuredText):: - - This is an anonymous reference__. Here is an anonymous - `phrase reference`__. Phrase references may even cross `line - boundaries`__. - - __ http://www.example.org/reference/ - __ http://www.example.org/phrase_reference/ - __ http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - The reference text does not have to be repeated. - - + Disadvantages: - - - References and targets must be kept in sync. - - Targets cannot be reused. - - The target URLs may be located far from the references. - -For comparison and historical background, StructuredText also has two -syntaxes for hyperlinks: - -* First, ``"reference text":URL``:: - - This is a "reference":http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase - reference":http://www.example.org/phrase_reference/. - -* Second, ``"reference text", http://example.com/absolute_URL``:: - - This is a "reference", http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase reference", - http://www.example.org/phrase_reference/. - -Both syntaxes share advantages and disadvantages: - -+ Advantages: - - - The target is specified immediately adjacent to the reference. - -+ Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused. - - Both syntaxes use double quotes, common in ordinary text. - - In the first syntax, the URL and the last word are stuck - together, exacerbating the line wrap problem. - - The second syntax is too magical; text could easily be written - that way by accident (although only absolute URLs are recognized - here, perhaps because of the potential for ambiguity). - -A new type of "inline external hyperlink" has been proposed. - -1. On 2002-06-28, Simon Budig proposed__ a new syntax for - reStructuredText hyperlinks:: - - This is a reference_(http://www.example.org/reference/) of one - word ("reference"). Here is a `phrase - reference`_(http://www.example.org/phrase_reference/). Are - these examples, (single-underscore), named? If so, `anonymous - references`__(http://www.example.org/anonymous/) using two - underscores would probably be preferable. - - __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html - - The syntax, advantages, and disadvantages are similar to those of - StructuredText. - - + Advantages: - - - The target is specified immediately adjacent to the reference. - - + Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused (unless named, but the semantics are - unclear). - - + Problems: - - - The ``"`ref`_(URL)"`` syntax forces the last word of the - reference text to be joined to the URL, making a potentially - very long word that can't be wrapped (URLs can be very long). - The reference and the URL should be separate. This is a - symptom of the following point: - - - The syntax produces a single compound construct made up of two - equally important parts, *with syntax in the middle*, *between* - the reference and the target. This is unprecedented in - reStructuredText. - - - The "inline hyperlink" text is *not* a named reference (there's - no lookup by name), so it shouldn't look like one. - - - According to the IETF standards RFC 2396 and RFC 2732, - parentheses are legal URI characters and curly braces are legal - email characters, making their use prohibitively difficult. - - - The named/anonymous semantics are unclear. - -2. After an analysis__ of the syntax of (1) above, we came up with the - following compromise syntax:: - - This is an anonymous reference__ - __<http://www.example.org/reference/> of one word - ("reference"). Here is a `phrase reference`__ - __<http://www.example.org/phrase_reference/>. `Named - references`_ _<http://www.example.org/anonymous/> use single - underscores. - - __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html - - The syntax builds on that of the existing "inline internal - targets": ``an _`inline internal target`.`` - - + Advantages: - - - The target is specified immediately adjacent to the reference, - improving maintainability: - - - References and targets are easily kept in sync. - - The reference text does not have to be repeated. - - - The construct is executed in two parts: references identical to - existing references, and targets that are new but not too big a - stretch from current syntax. - - - There's overwhelming precedent for quoting URLs with angle - brackets [#]_. - - + Disadvantages: - - - Poor plaintext readability. - - Lots of "line noise". - - Targets cannot be reused (unless named; see below). - - To alleviate the readability issue slightly, we could allow the - target to appear later, such as after the end of the sentence:: - - This is a named reference__ of one word ("reference"). - __<http://www.example.org/reference/> Here is a `phrase - reference`__. __<http://www.example.org/phrase_reference/> - - Problem: this could only work for one reference at a time - (reference/target pairs must be proximate [refA trgA refB trgB], - not interleaved [refA refB trgA trgB] or nested [refA refB trgB - trgA]). This variation is too problematic; references and inline - external targets will have to be kept imediately adjacent (see (3) - below). - - The ``"reference__ __<target>"`` syntax is actually for "anonymous - inline external targets", emphasized by the double underscores. It - follows that single trailing and leading underscores would lead to - *implicitly named* inline external targets. This would allow the - reuse of targets by name. So after ``"reference_ _<target>"``, - another ``"reference_"`` would point to the same target. - - .. [#] - From RFC 2396 (URI syntax): - - The angle-bracket "<" and ">" and double-quote (") - characters are excluded [from URIs] because they are often - used as the delimiters around URI in text documents and - protocol fields. - - Using <> angle brackets around each URI is especially - recommended as a delimiting style for URI that contain - whitespace. - - From RFC 822 (email headers): - - Angle brackets ("<" and ">") are generally used to indicate - the presence of a one machine-usable reference (e.g., - delimiting mailboxes), possibly including source-routing to - the machine. - -3. If it is best for references and inline external targets to be - immediately adjacent, then they might as well be integrated. - Here's an alternative syntax embedding the target URL in the - reference:: - - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a `phrase - reference <http://www.example.org/phrase_reference/>`__. - - Advantages and disadvantages are similar to those in (2). - Readability is still an issue, but the syntax is a bit less - heavyweight (reduced line noise). Backquotes are required, even - for one-word references; the target URL is included within the - reference text, forcing a phrase context. - - We'll call this variant "embedded URIs". - - Problem: how to refer to a title like "HTML Anchors: <a>" (which - ends with an HTML/SGML/XML tag)? We could either require more - syntax on the target (like ``"`reference text - __<http://example.com/>`__"``), or require the odd conflicting - title to be escaped (like ``"`HTML Anchors: \<a>`__"``). The - latter seems preferable, and not too onerous. - - Similarly to (2) above, a single trailing underscore would convert - the reference & inline external target from anonymous to implicitly - named, allowing reuse of targets by name. - - I think this is the least objectionable of the syntax alternatives. - -Other syntax variations have been proposed (by Brett Cannon and Benja -Fallenstein):: - - `phrase reference`->http://www.example.com - - `phrase reference`@http://www.example.com - - `phrase reference`__ ->http://www.example.com - - `phrase reference` [-> http://www.example.com] - - `phrase reference`__ [-> http://www.example.com] - - `phrase reference` <http://www.example.com>_ - -None of these variations are clearly superior to #3 above. Some have -problems that exclude their use. - -With any kind of inline external target syntax it comes down to the -conflict between maintainability and plaintext readability. I don't -see a major problem with reStructuredText's maintainability, and I -don't want to sacrifice plaintext readability to "improve" it. - -The proponents of inline external targets want them for easily -maintainable web pages. The arguments go something like this: - -- Named hyperlinks are difficult to maintain because the reference - text is duplicated as the target name. - - To which I said, "So use anonymous hyperlinks." - -- Anonymous hyperlinks are difficult to maintain becuase the - references and targets have to be kept in sync. - - "So keep the targets close to the references, grouped after each - paragraph. Maintenance is trivial." - -- But targets grouped after paragraphs break the flow of text. - - "Surely less than URLs embedded in the text! And if the intent is - to produce web pages, not readable plaintext, then who cares about - the flow of text?" - -Many participants have voiced their objections to the proposed syntax: - - Garth Kidd: "I strongly prefer the current way of doing it. - Inline is spectactularly messy, IMHO." - - Tony Ibbs: "I vehemently agree... that the inline alternatives - being suggested look messy - there are/were good reasons they've - been taken out... I don't believe I would gain from the new - syntaxes." - - Paul Moore: "I agree as well. The proposed syntax is far too - punctuation-heavy, and any of the alternatives discussed are - ambiguous or too subtle." - -Others have voiced their support: - - fantasai: "I agree with Simon. In many cases, though certainly - not in all, I find parenthesizing the url in plain text flows - better than relegating it to a footnote." - - Ken Manheimer: "I'd like to weigh in requesting some kind of easy, - direct inline reference link." - -(Interesting that those *against* the proposal have been using -reStructuredText for a while, and those *for* the proposal are either -new to the list ["fantasai", background unknown] or longtime -StructuredText users [Ken Manheimer].) - -I was initially ambivalent/against the proposed "inline external -targets". I value reStructuredText's readability very highly, and -although the proposed syntax offers convenience, I don't know if the -convenience is worth the cost in ugliness. Does the proposed syntax -compromise readability too much, or should the choice be left up to -the author? Perhaps if the syntax is *allowed* but its use strongly -*discouraged*, for aesthetic/readability reasons? - -After a great deal of thought and much input from users, I've decided -that there are reasonable use cases for this construct. The -documentation should strongly caution against its use in most -situations, recommending independent block-level targets instead. -Syntax #3 above ("embedded URIs") will be used. - - -Doctree Representation of Transitions -===================================== - -(Although not reStructuredText-specific, this section fits best in -this document.) - -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: - - Document - ======== - - Paragraph 1 - - -------- - - Paragraph 2 - -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 - -There are several possibilities for the implementation: - -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. - -2. Treating "divisions" uniformly brings us to the second - possibility:: - - <document> - <section name="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. - -3. Implement them as "transitions", empty elements:: - - <document> - <section name="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 - - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. - -Solution 3 was chosen for incorporation into the document tree model. - -.. _HTML: http://www.w3.org/MarkUp/ - - -Nested Inline Markup -==================== - -These are collected notes on a long-discussed issue. The original -mailing list messages should be referred to for details. - -* In a 2001-10-31 discussion I wrote: - - Try, for example, `Ed Loper's 2001-03-21 post`_, which details - some rules for nested inline markup. I think the complexity is - prohibitive for the marginal benefit. (And if you can understand - that tree without going mad, you're a better man than I. ;-) - - Inline markup is already fragile. Allowing nested inline markup - would only be asking for trouble IMHO. If it proves absolutely - necessary, it can be added later. The rules for what can appear - inside what must be well thought out first though. - - .. _Ed Loper's 2001-03-21 post: - http://mail.python.org/pipermail/doc-sig/2001-March/001487.html - - -- http://mail.python.org/pipermail/doc-sig/2001-October/002354.html - -* In a 2001-11-09 Doc-SIG post, I wrote: - - The problem is that in the - what-you-see-is-more-or-less-what-you-get markup language that - is reStructuredText, the symbols used for inline markup ("*", - "**", "`", "``", etc.) may preclude nesting. - - I've rethought this position. Nested markup is not precluded, just - tricky. People and software parse "double and 'single' quotes" all - the time. Continuing, - - I've thought over how we might implement nested inline - markup. The first algorithm ("first identify the outer inline - markup as we do now, then recursively scan for nested inline - markup") won't work; counterexamples were given in my `last post - <http://mail.python.org/pipermail/doc-sig/2001-November/002363.html>`__. - - The second algorithm makes my head hurt:: - - while 1: - scan for start-string - if found: - push on stack - scan for start or end string - if new start string found: - recurse - elif matching end string found: - pop stack - elif non-matching end string found: - if its a markup error: - generate warning - elif the initial start-string was misinterpreted: - # e.g. in this case: ***strong** in emphasis* - restart with the other interpretation - # but it might be several layers back ... - ... - - This is similar to how the parser does section title - recognition, but sections are much more regular and - deterministic. - - Bottom line is, I don't think the benefits are worth the effort, - even if it is possible. I'm not going to try to write the code, - at least not now. If somebody codes up a consistent, working, - general solution, I'll be happy to consider it. - - -- http://mail.python.org/pipermail/doc-sig/2001-November/002388.html - -* In a `2003-05-06 Docutils-Users post`__ Paul Tremblay proposed a new - syntax to allow for easier nesting. It eventually evolved into - this:: - - :role:[inline text] - - The duplication with the existing interpreted text syntax is - problematic though. - - __ http://article.gmane.org/gmane.text.docutils.user/317 - -* Could the parser be extended to parse nested interpreted text? :: - - :emphasis:`Some emphasized text with :strong:`some more - emphasized text` in it and **perhaps** :reference:`a link`` - -* In a `2003-06-18 Docutils-Develop post`__, Mark Nodine reported on - his implementation of a form of nested inline markup in his - Perl-based parser (unpublished). He brought up some interesting - ideas. The implementation was flawed, however, by the change in - semantics required for backslash escapes. - - __ http://article.gmane.org/gmane.text.docutils.devel/795 - -It may be possible to accomplish nested inline markup in general with -a more powerful inline markup parser. There may be some issues, but -I'm not averse to the idea of nested inline markup in general. I just -don't have the time or inclination to write a new parser now. Of -course, a good patch would be welcome! - -I envisage something like this. Explicit-role interpreted text must -be nestable. Prefix-based is probably preferred, since suffix-based -will look like inline literals:: - - ``text`:role1:`:role2: - -But it can be disambiguated, so it ought to be left up to the author:: - - `\ `text`:role1:`:role2: - -In addition, other forms of inline markup may be nested if -unambiguous:: - - *emphasized ``literal`` and |substitution ref| and link_* - -IOW, the parser ought to be as permissive as possible. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/rst/problems.txt b/docutils/docs/dev/rst/problems.txt deleted file mode 100644 index a8747af88..000000000 --- a/docutils/docs/dev/rst/problems.txt +++ /dev/null @@ -1,870 +0,0 @@ -============================== - Problems With StructuredText -============================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -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 -proposes solutions to be incorporated into the reStructuredText_ -specification. - - -.. contents:: - - -Formal Specification -==================== - -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. - - -Understanding and Extending the Code -==================================== - -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 -inadequate for the complexity of the code itself. - -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. - - -Section Structure via Indentation -================================= - -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 -immediately succeeding paragraphs are lower level is treated as a -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. - -Python's use of significant whitespace is a wonderful (if not -original) innovation, however requiring indentation in ordinary -written text is hypergeneralization. - -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). - - -Character Escaping Mechanism -============================ - -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? - -1. ``!`` (http://dev.zope.org/Members/jim/StructuredTextWiki/NGEscaping) -2. ``\`` -3. ``~`` -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 -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.) - -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. - -A carefully constructed set of recognition rules for inline markup -will obviate the need for backslash-escapes in almost all cases; see -`Delimitation of Inline Markup`_ below. - -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. - - -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 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, -including list items, even when boundaries are obvious from the markup -itself. - -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. - - -Bullet List Markup -================== - -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 - o al trabajo. - - (Call me at home or at work.) - -And in Japanese (when romanized):: - - Senshuu no doyoubi ni tegami - o kakimashita. - - ([I] wrote a letter on Saturday last week.) - -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. - -In reStructuredText_, '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 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. - -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. - -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: - - 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. - - 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. - - For an enumerated list to be recognized, the following must be - true: - - - the list must consist of multiple adjacent list items (2 or - more) - - the enumerators must all have the same format - - the enumerators must be sequential - - -Definition List Markup -====================== - -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 -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. - -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 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). - - -Literal Blocks -============== - -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). - -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. 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`_:: - - +------------+------------+------------+--------------+ - | 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 the - characters '-', '=', '|', 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 table - mode). - - The vertical bar ('|') is used for for vertical lines (column - separators). - - The plus sign ('+') is used for intersections of horizontal and - vertical lines. - - 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 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. :: - - ============ ============ ============ ============== - 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 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. - -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 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 - ==== ===== ======== ======== ======= ==== ===== ===== - - 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. - - This table sums up the features. Using all the features in such a - small 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 first - column could be used to indicate row starts. Multi-line rows are - possible, 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 of - the row. To indicate a real bullet list within a first-column - cell, simply nest the bullets. - -5. 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:: - - ===== ===== - 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 column *must* contain some text; blank cells - would lead to a misinterpretation. An empty comment ("..") is - sufficient. - -6. 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. - -Alternatives 1 and 5 has been adopted by reStructuredText. - - -Delimitation of Inline Markup -============================= - -StructuredText specifies that inline markup must begin with -whitespace, precluding such constructs as parenthesized or quoted -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. - - -Underlining -=========== - -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": - - 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 *complete* 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. - -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 single -quotes ('literals'). The problem with single quotes is that they are -too 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,' he - said, 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, and -apostrophes. 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 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`__. - -__ alternatives.html#backquotes-in-phrase-links -__ 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. - -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 plaintext - by TeXies). - -The inline markup start-string and end-string recognition rules -defined by the `reStructuredText markup specification`_ would allow -all 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 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 -backslash-escaping:: - - like this:: - - Here, we can do ``absolutely'' anything `'`'\|/|\ we like! - -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. - -reStructuredText will use double backquotes for inline literals, and -single backqoutes for interpreted text. - - -Hyperlinks -========== - -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 - hyperlink:: - - "mail me", mailto:me@mail.com - -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]. - - .. [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 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: - -1. Have no special markup for hyperlinks. - -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: - - Python (http://www.python.org/) - - B. 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. - -3. The original Setext_ introduced a mechanism of indirect hyperlinks. - A source link word ('hot word') in the text was given a trailing - underscore:: - - Here is some text with a hyperlink_ built in. - - 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:: - - .. _hyperlink http://www.123.xyz - - Setext used ``underscores_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 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. - -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. 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 -citation references, removing the problem with ordinary bracketed text -and 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 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. - -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. - -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. - -To summarize:: - - .. 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 - -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> - - <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 example - above. - -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 with -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. - -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _detailed description: - http://www.tibsnjoan.demon.co.uk/STNG-format.html -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html -.. _StructuredTextNG: - http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/ - python/python/dist/src/README -.. _Emacs table mode: http://table.sourceforge.net/ -.. _reStructuredText Markup Specification: reStructuredText.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/semantics.txt b/docutils/docs/dev/semantics.txt deleted file mode 100644 index cd20e15f6..000000000 --- a/docutils/docs/dev/semantics.txt +++ /dev/null @@ -1,119 +0,0 @@ -===================== - Docstring Semantics -===================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -These are notes for a possible future PEP providing the final piece of -the Python docstring puzzle: docstring semantics or documentation -methodology. `PEP 257`_, Docstring Conventions, sketches out some -guidelines, but does not get into methodology details. - -I haven't explored documentation methodology more because, in my -opinion, it is a completely separate issue from syntax, and it's even -more controversial than syntax. Nobody wants to be told how to lay -out their documentation, a la JavaDoc_. I think the JavaDoc way is -butt-ugly, but it *is* an established standard for the Java world. -Any standard documentation methodology has to be formal enough to be -useful but remain light enough to be usable. If the methodology is -too strict, too heavy, or too ugly, many/most will not want to use it. - -I think a standard methodology could benefit the Python community, but -it would be a hard sell. A PEP would be the place to start. For most -human-readable documentation needs, the free-form text approach is -adequate. We'd only need a formal methodology if we want to extract -the parameters into a data dictionary, index, or summary of some kind. - - -PythonDoc -========= - -(Not to be confused with Daniel Larsson's pythondoc_ project.) - -A Python version of the JavaDoc_ semantics (not syntax). A set of -conventions which are understood by the Docutils. What JavaDoc has -done is to establish a syntax that enables a certain documentation -methodology, or standard *semantics*. JavaDoc is not just syntax; it -prescribes a methodology. - -- Use field lists or definition lists for "tagged blocks". By this I - mean that field lists can be used similarly to JavaDoc's ``@tag`` - syntax. That's actually one of the motivators behind field lists. - For example, we could have:: - - """ - :Parameters: - - `lines`: a list of one-line strings without newlines. - - `until_blank`: Stop collecting at the first blank line if - true (1). - - `strip_indent`: Strip common leading indent if true (1, - default). - - :Return: - - a list of indented lines with mininum indent removed; - - the amount of the indent; - - whether or not the block finished with a blank line or at - the end of `lines`. - """ - - This is taken straight out of docutils/statemachine.py, in which I - experimented with a simple documentation methodology. Another - variation I've thought of exploits the Grouch_-compatible - "classifier" element of definition lists. For example:: - - :Parameters: - `lines` : [string] - List of one-line strings without newlines. - `until_blank` : boolean - Stop collecting at the first blank line if true (1). - `strip_indent` : boolean - Strip common leading indent if true (1, default). - -- Field lists could even be used in a one-to-one correspondence with - JavaDoc ``@tags``, although I doubt if I'd recommend it. Several - ports of JavaDoc's ``@tag`` methodology exist in Python, most - recently Ed Loper's "epydoc_". - - -Other Ideas -=========== - -- Can we extract comments from parsed modules? Could be handy for - documenting function/method parameters:: - - def method(self, - source, # path of input file - dest # path of output file - ): - - This would save having to repeat parameter names in the docstring. - - Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG] - Documentation tool": - - it would be quite hard to add a new param to this method without - realising you should document it - -- Frederic Giacometti's `iPhrase Python documentation conventions`_ is - an attachment to his Doc-SIG post of 2001-05-30. - - -.. _PEP 257: http://www.python.org/peps/pep-0257.html -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _epydoc: http://epydoc.sf.net/ -.. _iPhrase Python documentation conventions: - http://mail.python.org/pipermail/doc-sig/2001-May/001840.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt deleted file mode 100644 index eab2208fe..000000000 --- a/docutils/docs/dev/todo.txt +++ /dev/null @@ -1,2114 +0,0 @@ -================= - Docutils_ Notes -================= -:Author: David Goodger (with input from many) -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - - -To Do -===== - -Priority items are marked with "@" symbols. The more @s, the higher -the priority. Items in question form (containing "?") are ideas which -require more thought and debate; they are potential to-do's. - -Many of these items are awaiting champions. If you see something -you'd like to tackle, please do! - - -Bugs ----- - -* The "contents" directive now automatically names the "topic" - produced (using its title), so that it can be referred to by name. - However, this naming happens late in the game, after most references - have been resolved. So the following indirect target produces a - warning because the name "contents" is not available when resolved:: - - .. contents:: - - .. _alternate name for contents: contents_ - - Fixing this may be tricky, and isn't a high priority. - - Idea: two-pass hyperlink resolution, ignoring errors on the first - pass? - - Perhaps the directive should do a bit more work up-front: create the - "topic" and "title", and leave the "pending" node for contents. - -* The parser doesn't know anything about double-width characters such - as Chinese hanza & Japanese kanji/kana. Also, it's dependent on - whitespace and punctuation as markup delimiters, which may not be - applicable in these languages. - -* In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need a "base_node" parameter. There's a test in - test/test_parsers/test_rst/test_directives/test_include.py - (commented out, because the test fails). - -* tools/buildhtml.py needs a mechanism to skip directories - (e.g. licenses, test). Perhaps a ".prune-buildhtml" file? A - command-line option wouldn't work because it would require user - action. - - -General -------- - -* Refactor - - - Rename methods & variables according to the `Python coding - conventions`_ below. - - - The name-to-id conversion and hyperlink resolution code needs to be - checked for correctness and refactored. I'm afraid it's a bit of - a spaghetti mess now. - -* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. - -* Ask Python-dev for opinions (GvR for a pronouncement) on special - variables (__author__, __version__, etc.): convenience vs. namespace - pollution. Ask opinions on whether or not Docutils should recognize - & use them. - -* In ``docutils.readers.get_reader_class`` (& ``parsers`` & - ``writers`` too), should we be importing "standalone" or - "docutils.readers.standalone"? (This would avoid importing - top-level modules if the module name is not in docutils/readers. - Potential nastiness.) - -* Perhaps store a _`name-to-id mapping file`? This could be stored - permanently, read by subsequent processing runs, and updated with - new entries. ("Persistent ID mapping"?) - -* Need a Unicode to HTML entities codec for HTML writer? - -* Perhaps the ``Component.supports`` method should deal with - individual features ("meta" etc.) instead of formats ("html" etc.)? - -* Standalone Reader: Implement an option to turn off the DocTitle - transform? - -* Add /usr/etc/docutils.conf to config file list? System-wide, - whereas /etc/docutils.conf is machine-specific. - /usr/local/etc/docutils.conf too? See the `Filesystem Hierarchy - Standard`_. - - .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. - -* Add _`object numbering and object references` (tables & figures). - These would be the equivalent of DocBook's "formal" elements. - - We may need _`persistent sequences`, such as chapter numbers. See - `OpenOffice.org XML`_ "fields". Should the sequences be automatic - or manual (user-specifyable)? - - We need to name the objects: - - - "name" option for the "figure" directive? :: - - .. figure:: image.png - :name: image's name - - To name tables, we could use a "table" directive:: - - .. table:: optional title here - :name: table's name - - ===== ===== - x not x - ===== ===== - True False - False True - ===== ===== - - This would also allow other options to be set, like border - styles. The same technique could be used for other objects. - - - The object could also be done this way:: - - .. _figure name: - - .. figure:: image.png - - This may be a more general solution, equally applicable to tables. - However, explicit naming using an option seems simpler to users. - - We'll also need syntax for object references. See `OpenOffice.org - XML`_ "reference fields": - - - Parameterized substitutions? For example:: - - See |figure (figure name)|, on |page (figure name)|. - - .. |figure (name)| figure-ref:: (name) - .. |page (name)| page-ref:: (name) - - The result would be:: - - See figure 3.11 on page 157. - - But this would require substitution directives to be processed at - reference-time, not at definition-time as they are now. Or, - perhaps the directives could just leave ``pending`` elements - behind, and the transforms do the work? How to pass the data - through? Too complicated. - - - An interpreted text approach is simpler and better:: - - See :figure:`figure name` on :page:`figure name`. - - The "figure" and "page" roles could generate appropriate - boilerplate text. The position of the role (prefix or suffix) - could also be utilized. - - See `Interpreted Text`_ below. - - .. _OpenOffice.org XML: http://xml.openoffice.org/ - -* Think about large documents made up of multiple subdocument files. - Issues: continuity (`persistent sequences`_ above), cross-references - (`name-to-id mapping file`_ above and `targets in other documents`_ - below). - - When writing a book, the author probably wants to split it up into - files, perhaps one per chapter (but perhaps even more detailed). - However, we'd like to be able to have references from one chapter to - another, and have continuous numbering (pages and chapters, as - applicable). Of course, none of this is implemented yet. There has - been some thought put into some aspects; see `the "include" - directive`__ and the `Reference Merging`_ transform below. - - When I was working with SGML in Japan, we had a system where there - was a top-level coordinating file, book.sgml, which contained the - top-level structure of a book: the <book> element, containing the - book <title> and empty component elements (<preface>, <chapter>, - <appendix>, etc.), each with filename attributes pointing to the - actual source for the component. Something like this:: - - <book id="bk01"> - <title>Title of the Book</title> - <preface inrefid="pr01"></preface> - <chapter inrefid="ch01"></chapter> - <chapter inrefid="ch02"></chapter> - <chapter inrefid="ch03"></chapter> - <appendix inrefid="ap01"></appendix> - </book> - - (The "inrefid" attribute stood for "insertion reference ID".) - - The processing system would process each component separately, but - it would recognize and use the book file to coordinate chapter and - page numbering, and keep a persistent ID to (title, page number) - mapping database for cross-references. Docutils could use a similar - system for large-scale, multipart documents. - - __ rst/directives.html#including-an-external-document-fragment - - Aahz's idea: - - First the ToC:: - - .. ToC-list:: - Introduction.txt - Objects.txt - Data.txt - Control.txt - - Then a sample use:: - - .. include:: ToC.txt - - As I said earlier in chapter :chapter:`Objects.txt`, the - reference count gets increased every time a binding is made. - - Which produces:: - - As I said earlier in chapter 2, the - reference count gets increased every time a binding is made. - - The ToC in this form doesn't even need to be references to actual - reST documents; I'm simply doing it that way for a minimum of - future-proofing, in case I do want to add the ability to pick up - references within external chapters. - - Perhaps, instead of ToC (which would overload the "contents" - directive concept already in use), we could use "manifest". A - "manifest" directive might associate local reference names with - files:: - - .. manifest:: - intro: Introduction.txt - objects: Objects.txt - data: Data.txt - control: Control.txt - - Then the sample becomes:: - - .. include:: manifest.txt - - As I said earlier in chapter :chapter:`objects`, the - reference count gets increased every time a binding is made. - -* Add functional testing to Docutils: Readers, Writers, front ends. - -* Changes to sandbox/davidg/infrastructure/docutils-update? - - - Modify the script to only update the snapshots if files have - actually changed in CVS (saving some SourceForge server cycles). - - - Make passing the test suite a prerequisite to snapshot update, - but only if the process is completely automatic. - - - Rewrite in Python? - -* Publisher: "Ordinary setup" shouldn't requre specific ordering; at - the very least, there ought to be error checking higher up in the - call chain. [Aahz] - - ``Publisher.get_settings`` requires that all components be set up - before it's called. Perhaps the I/O *objects* shouldn't be set, but - I/O *classes*. Then options are set up (``.set_options``), and - ``Publisher.set_io`` (or equivalent code) is called with source & - destination paths, creating the I/O objects. - - Perhaps I/O objects shouldn't be instantiated until required. For - split output, the Writer may be called multiple times, once for each - doctree, and each doctree should have a separate Output object (with - a different path). Is the "Builder" pattern applicable here? - -* Perhaps I/O objects should become full-fledged components (i.e. - subclasses of ``docutils.Component``, as are Readers, Parsers, and - Writers now), and thus have associated option/setting specs and - transforms. - -* Multiple file I/O suggestion from Michael Hudson: use a file-like - object or something you can iterate over to get file-like objects. - -* Language modules: in accented languages it may be useful to have - both accented and unaccented entries in the ``bibliographic_fields`` - mapping for versatility. - -* Add a "--strict-language" option & setting: no English fallback for - language-dependent features. - -* Add an "--input-language" option & setting? Specify a different - language module for input (bibliographic fields, directives) than - for output. The "--language" option would set both input & output - languages. - -* Auto-generate reference tables for language-dependent features? - Could be generated from the source modules. A special command-line - option could be added to Docutils front ends to do this. (Idea from - Engelbert Gruber.) - -* Change the "class" attribute of elements (set with - Element.set_class) to a list? - -* Enable feedback of some kind from internal decisions, such as - reporting the successful input encoding. Modify runtime settings? - System message? Simple stderr output? - -* Perhaps we need to re-evaluate the config file format, possibly - enabling a section for each Docutils component so that (for example) - HTML's and LaTeX's stylesheets don't interfere with each other. - - Idea: adopt sections in the config file corresponding to Docutils - components, which define flat namespaces that can be applied in an - overlay fashion defined by the components themselves. For example, - if the "pep_html" writer defines itself as derivative of the - "html4css1" writer, the "stylesheet" setting in the "[html4css1]" - section will be used unless the "[pep_html]" section overrides it. - In the absence of any "stylesheet" setting in either section, a - "stylesheet" setting in "[general]" would be used. This would also - allow component-specific definitions of general or - other-component-specific settings, such as writer-specific overrides - for the "trim_footnote_reference_space" parser setting. - -* The "docutils.conf" included with Docutils should become complete, - with examples of every setting (possibly commented). It's currently - sparse, requiring doc lookups. - -* Add internationalization to footer boilerplate text (resulting from - "--generator", "--source-link", and "--date" etc.), allowing - translations. - - -Documentation -------------- - -* User docs. What's needed? - - -Implementation Docs -``````````````````` - -* Internal module documentation (docstrings). - -* spec/doctree.txt: DTD element structural relationships, semantics, - and attributes. In progress; element descriptions to be completed. - -* How-to docs: In spec/howto/. - - - How a Writer works & how to write one - - - Transforms - -* Document the ``pending`` elements, how they're generated and what - they do. - -* Document the transforms (perhaps in docstrings?): how they're used, - what they do, dependencies & order considerations. - -* Document the HTML classes used by html4css1.py. - - -Specification -````````````` - -* Complete PEP 258 Docutils Design Specification. - - - Fill in the blanks in API details. - - - Specify the nodes.py internal data structure implementation? - - [Tibs:] Eventually we need to have direct documentation in - there on how it all hangs together - the DTD is not enough - (indeed, is it still meant to be correct? [Yes, it is. - --DG]). - -* Rework PEP 257, separating style from spec from tools, wrt Docutils? - See Doc-SIG from 2001-06-19/20. - - -Web Site -```````` - -* Add an "examples" directory, beside "tools" and "docs", for - interesting examples of Docutils usage? Have a top-level README.txt - file and a subdirectory for each example. (Martin Blais) - - -Python Source Reader --------------------- - -General: - -* Analyze Tony Ibbs' PySource code. - -* Analyze Doug Hellmann's HappyDoc project. - -* Investigate how POD handles literate programming. - -* Take the best ideas and integrate them into Docutils 0.3. - -Miscellaneous ideas: - -* If we can detect that a comment block begins with ``##``, a la - JavaDoc, it might be useful to indicate interspersed section headers - & explanatory text in a module. For example:: - - """Module docstring.""" - - ## - # Constants - # ========= - - a = 1 - b = 2 - - ## - # Exception Classes - # ================= - - class MyException(Exception): pass - - # etc. - -* Should standalone strings also become (module/class) docstrings? - Under what conditions? We want to prevent arbitrary strings from - becomming docstrings of prior attribute assignments etc. Assume - that there must be no blank lines between attributes and attribute - docstrings? (Use lineno of NEWLINE token.) - - Triple-quotes are sometimes used for multi-line comments (such as - commenting out blocks of code). How to reconcile? - -* HappyDoc's idea of using comment blocks when there's no docstring - may be useful to get around the conflict between `additional - docstrings`_ and ``from __future__ import`` for module docstrings. - A module could begin like this:: - - #!/usr/bin/env python - # :Author: Me - # :Copyright: whatever - - """This is the public module docstring (``__doc__``).""" - - # More docs, in comments. - # All comments at the beginning of a module could be - # accumulated as docstrings. - # We can't have another docstring here, because of the - # ``__future__`` statement. - - from __future__ import division - - Using the JavaDoc convention of a doc-comment block beginning with - ``##`` is useful though. It allows doc-comments and implementation - comments. - - .. _additional docstrings: pep-0258.html#additional-docstrings - -* HappyDoc uses an initial comment block to set "parser configuration - values". Do the same thing for Docutils, to set runtime settings on - a per-module basis? I.e.:: - - # Docutils:setting=value - - Could be used to turn on/off function parameter comment recognition - & other marginal features. Could be used as a general mechanism to - augment config files and command-line options (but which takes - precedence?). - -* Multi-file output should be divisible at arbitrary level. - -* Support all forms of ``import`` statements: - - - ``import module``: listed as "module" - - ``import module as alias``: "alias (module)" - - ``from module import identifier``: "identifier (from module)" - - ``from module import identifier as alias``: "alias (identifier - from module)" - - ``from module import *``: "all identifiers (``*``) from module" - -* Have links to colorized Python source files from API docs? And - vice-versa: backlinks from the colorized source files to the API - docs! - -* In summaries, use the first *sentence* of a docstring if the first - line is not followed by a blank line. - - -reStructuredText Parser ------------------------ - -Also see the `... Or Not To Do?`__ list. - -__ rst/alternatives.html#or-not-to-do - -* Clean up the code; refactor as required. - -* Add motivation sections for constructs in spec. - -* Allow very long titles (on two or more lines)? - -* And for the sake of completeness, should definition list terms be - allowed to be very long (two or more lines) also? - -* Support generic hyperlink references to _`targets in other - documents`? Not in an HTML-centric way, though (it's trivial to say - ``http://www.example.com/doc#name``, and useless in non-HTML - contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG - 2001-08-10. - -* .. _adaptable file extensions: - - In target URLs, it would be useful to not explicitly specify the - file extension. If we're generating HTML, then ".html" is - appropriate; if PDF, then ".pdf"; etc. How about using ".*" to - indicate "choose the most appropriate filename extension? For - example:: - - .. _Another Document: another.* - - Should the choice be from among existing files only? Documents - only, or objects (images, etc.) also? (How to differentiate? - Element context [within "image"]?) - - This may not be just a parser issue though; it may need framework - support. - -* Implement the header row separator modification to table.el. (Wrote - to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting - support for "=====" header rows. On 2001-08-17 he replied, saying - he'd put it on his to-do list, but "don't hold your breath".) - -* Tony says inline markup rule 7 could do with a *little* more - exposition in the spec, to make clear what is going on for people - with head colds. - -* @@ Fix the parser's indentation handling to conform with the - stricter definition in the spec. (Explicit markup blocks should be - strict or forgiving?) - -* @@ Tighten up the spec for indentation of "constructs using complex - markers": field lists and option lists? Bodies may begin on the - same line as the marker or on a subsequent line (with blank lines - optional). Require that for bodies beginning on the same line as - the marker, all lines be in strict alignment. Currently, this is - acceptable:: - - :Field-name-of-medium-length: Field body beginning on the same - line as the field name. - - This proposal would make the above example illegal, instead - requiring strict alignment. A field body may either begin on the - same line:: - - :Field-name-of-medium-length: Field body beginning on the same - line as the field name. - - Or it may begin on a subsequent line:: - - :Field-name-of-medium-length: - Field body beginning on a line subsequent to that of the - field name. - - This would be especially relevant in degenerate cases like this:: - - :Number-of-African-swallows-requried-to-carry-a-coconut: - It would be very difficult to align the field body with - the left edge of the first line if it began on the same - line as the field name. - -* Allow for variant styles by interpreting indented lists as if they - weren't indented? For example, currently the list below will be - parsed as a list within a block quote:: - - paragraph - - * list item 1 - * list item 2 - - But a lot of people seem to write that way, and HTML browsers make - it look as if that's the way it should be. The parser could check - the contents of block quotes, and if they contain only a single - list, remove the block quote wrapper. There would be two problems: - - 1. What if we actually *do* want a list inside a block quote? - - 2. What if such a list comes immediately after an indented - construct, such as a literal block? - - Both could be solved using empty comments (problem 2 already exists - for a block quote after a literal block). But that's a hack. - - Perhaps a runtime setting, allowing or disabling this convenience, - would be appropriate. But that raises issues too: - - User A, who writes lists indented (and their config file is set - up to allow it), sends a file to user B, who doesn't (and their - config file disables indented lists). The result of processing - by the two users will be different. - - It may seem minor, but it adds ambiguity to the parser, which is - bad. - - See the Doc-SIG discussion starting 2001-04-18 with Ed Loper's - "Structuring: a summary; and an attempt at EBNF", item 4. Also - docutils-users, 2003-02-17. - -* Make the parser modular. Allow syntax constructs to be added or - disabled at run-time. Or is subclassing enough? - -* Continue to report (info, level 1) enumerated lists whose start - value is not ordinal-1? - -* Generalize the "doctest block" construct (which is overly - Python-centric) to other interactive sessions? "Doctest block" - could be renamed to "I/O block" or "interactive block", and each of - these could also be recognized as such by the parser: - - - Shell sessions:: - - $ cat example1.txt - A block beginning with a "$ " prompt is interpreted as a shell - session interactive block. As with Doctest blocks, the - interactive block ends with the first blank line, and wouldn't - have to be indented. - - - Root shell sessions:: - - # cat example2.txt - A block beginning with a "# " prompt is interpreted as a root - shell session (the user is or has to be logged in as root) - interactive block. Again, the block ends with a blank line. - - Other standard (and unambiguous) interactive session prompts could - easily be added (such as "> " for WinDOS). - - Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread - "docutils feedback"). - -* Generalize the "literal block" construct to allow blocks with a - per-line quoting to avoid indentation? For example, in this email - reply quoting the original, the block quoted with "``>``" (and - prefaced by "``::``") would be treated as a literal block:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - - The literal block would have to be a continuous text block (the - first blank line ends it) where every line begins with the same - non-alphanumeric non-whitespace character. - -* Should the "doctest" element go away, and the construct simply be a - front-end to generic literal blocks? - -* Add support for pragma (syntax-altering) directives. - - Some pragma directives could be local-scope unless explicitly - specified as global/pragma using ":global:" options. - -* Remove leading numbers from section titles for implicit link names? - A section titled "3. Conclusion" could then be referred to by - "``Conclusion_``" (i.e., without the "3."). - -* Syntax for the "line-block" directive? How about a - literal-block-like prefix, perhaps "``;;``"? (It is, after all, a - *semi-literal* literal block, no?) Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - Another idea: in an ordinary paragraph, if the first line ends with - a backslash (escaping the newline), interpret the entire paragraph - as a verse block? For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (And arguably invalid, since in Japanese the word "haiku" contains - three syllables.) - -* Implement auto-enumerated lists? See `Auto-Enumerated Lists`__. - - __ rst/alternatives.html#auto-enumerated-lists - -* Support whitespace in angle-bracketed standalone URLs according to - Appendix E ("Recommendations for Delimiting URI in Context") of `RFC - 2396`_. - - .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt - -* Use the vertical spacing of the source text to determine the - corresponding vertical spacing of the output? - -* [From Mark Nodine] For cells in simple tables that comprise a - single line, the justification can be inferred according to the - following rules: - - 1. If the text begins at the leftmost column of the cell, - then left justification, ELSE - 2. If the text begins at the rightmost column of the cell, - then right justification, ELSE - 3. Center justification. - - The onus is on the author to make the text unambiguous by adding - blank columns as necessary. There should be a parser setting to - turn off justification-recognition (normally on would be fine). - - Decimal justification? - -* Make enumerated list parsing more strict, so that this would parse - as a paragraph with an info message:: - - 1. line one - 3. line two - -* Line numbers in system messages are inconsistent in the parser. - Fix? - -* Generalize the "target-notes" directive into a command-line option - somehow? See docutils-develop 2003-02-13. - -* Include the _`character entity substitution definition files` - `temporarily stored here <tmp/charents>`__, perhaps in a - ``docutils/parsers/rst/includes/`` directory. See `misc.include`_ - below. - -* Should ^L (or something else in reST) be defined to mean - force/suggest page breaks in whatever output we have? - - A "break" or "page-break" directive would be easy to add. A new - doctree element would be required though (perhaps "break"). The - final behavior would be up to the Writer. The directive argument - could be one of page/column/recto/verso for added flexibility. - - Currently ^L (Python's "\f") characters are treated as whitespace. - They're converted to single spaces, actually, as are vertical tabs - (^K, Python's "\v"). It would be possible to recognize form feeds - as markup, but it requires some thought and discussion first. Are - there any downsides? Many editing environments do not allow the - insertion of control characters. Will it cause any harm? It would - be useful as a shorthand for the directive. - - It's common practice to use ^L before Emacs "Local Variables" - lists:: - - ^L - .. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: - - These are already present in many PEPs and Docutils project - documents. From the Emacs manual (info): - - A "local variables list" goes near the end of the file, in the - last page. (It is often best to put it on a page by itself.) - - It would be unfortunate if this construct caused a final blank page - to be generated (for those Writers that recognize the page breaks). - We'll have to add a transform that looks for a "break" plus zero or - more comments at the end of a document, and removes them. - -* Could the "break" concept above be extended to inline forms? - E.g. "^L" in the middle of a sentence could cause a line break. - Only recognize it at the end of a line (i.e., "\f\n")? - - Or is formfeed inappropriate? Perhaps vertical tab ("\v"), but even - that's a stretch. Can't use carriage returns, since they're - commonly used for line endings. - -* Allow a "::"-only paragraph (first line, actually) to introduce a - literal block without a blank line? (Idea from Paul Moore.) :: - - :: - This is a literal block - - Is indentation enough to make the separation between a paragraph - which contains just a ``::`` and the literal text unambiguous? - There's one problem with this concession. What if one wants a - definition list item which defines the term "::"? We'd have to - escape it. Currenty, "\::" doesn't work (although it should; - **bug**), and ":\:" is misinterpreted as a field name (name "\"; - also a **bug**). Assuming these bugs are squashed, I suppose it's a - useful special case. It would only be reasonable to apply it to - "::"-only paragraphs though. I think the blank line is visually - necessary if there's text before the "::":: - - The text in this paragraph needs separation - from the literal block following:: - This doesn't look right. - - Another idea. Would it be worthwhile to allow literal blocks to - begin without a newline after the "::"? Example:: - - :: while True: - print 'hello world' - - Perhaps. Perhaps not. - -* Add new syntax for _`nested inline markup`? Or extend the parser to - parse nested inline markup somehow? See the `collected notes - <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. - -* Idea from Beni Cherniavsky:: - - I'm writing a README document linking to all other interesting - files in its directory. If these were full URLs I could just - write them in the text but these are relative links that can't - be auto-recognized. The shortest way to make such links that I - found was `file_name <file_name>`_. Perhaps a shortcut for such - usage could be added, e.g. `<file_name>`_ would take the target - as the link name? - - IOW these would be equivalent:: - - `<file_name>`_ - `file_name <file_name>`_ - - Another possibility is to drop the backticks. Should the angle - brackets be kept in the output or not? This syntax could be adopted - in addition to the one above:: - - <file_name>_ - - -Directives -`````````` - -Directives below are often referred to as "module.directive", the -directive function. The "module." is not part of the directive name -when used in a document. - -* Allow directives to be added at run-time? - -* Use the language module for directive option names? - -* Add "substitution_only" and "substitution_ok" function attributes, - and automate context checking? - -* Implement options on existing directives: - - - Add a "name" option to directives, to set an author-supplied - identifier? - - - _`images.image`: "border"? "link"? - - Units of measure? (See docutils-users, 2003-03-02.) - - - _`images.figure`: "title" and "number", to indicate a formal - figure? - - - _`parts.sectnum`: "local"?, "start", "refnum" - - A "local" option could enable numbering for sections from a - certain point down, and sections in the rest of the document are - not numbered. For example, a reference section of a manual might - be numbered, but not the rest. OTOH, an all-or-nothing approach - would probably be enough. - - The "start" option will specify the sequence set to use at the - same time as the starting value, for the first part of the section - number (i.e., section, not subsection). For example:: - - .. sectnum: :start: 1 - - .. sectnum: :start: A - - .. sectnum: :start: 5 - - .. sectnum: :start: I - - The first one is the default: start at 1, numbered. The second - one specifies letters, and start at "A". The third specifies - numbers, start at 5. The last example could signal Roman - numerals, although I don't know if they'd be applicable here. - Enumerated lists already do all this; perhaps that code could be - reused. - - Here comes the tricky part. The "sectnum" directive should be - usable multiple times in a single document. For example, in a - long document with "chapter" and "appendix" sections, there could - be a second "sectnum" before the first appendix, changing the - sequence used (from 1,2,3... to A,B,C...). This is where the - "local" concept comes in. This part of the implementation can be - left for later. - - A "refnum" option (better name?) would insert reference names - (targets) consisting of the reference number. Then a URL could be - of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow - internal references by number? Allow name-based *and* - number-based ids at the same time, or only one or the other (which - would the table of contents use)? Usage issue: altering the - section structure of a document could render hyperlinks invalid. - - - _`parts.contents`: Add a "suppress" or "prune" option? It would - suppress contents display for sections in a branch from that point - down. Or a new directive, like "prune-contents"? - - Add an option to include topics in the TOC? Another for sidebars? - See docutils-develop 2003-01-29. - - - _`misc.include`: - - - "encoding" option? Take default from runtime settings. Use - Input component to read it in? - - - Option to select a range of lines? - - - Option to label lines? - - - Default directory for "built-in includes", using the C syntax - ``#include <name>``? - - Use C-preprocessor semantics for locating include files? - E.g., ``.. include:: file.txt`` will read another file into - the current one, relative to the current file's directory, - and ``.. include:: <standard>`` will read a standard include - file from ``docutils/include/``. (Should "quotes" be - required around non-standard include files?) - - -- http://sf.net/mailarchive/message.php?msg_id=1938401 - - I now think that ``docutils/parsers/rst/include/`` is a better - place for these files, since they're reStructuredText-specific. - - Keeping standard data files together with the package code makes - sense to me. It seems much less complex to implement than a - separate system data directory, such as ``/usr/share/docutils``. - Any reason a system data directory should be used? How does - Distutils handle data files? - - How about an environment variable, say RSTINCLUDEPATH or - RSTPATH? This could be combined with a setting/option to allow - user-defined include directories. - - For a specific application, see the discussion of `character - entity substitution definition files`_ above. - -* Implement directives. Each of the list items below begins with an - identifier of the form, "module_name.directive_function_name". The - directive name itself could be the same as the - directive_function_name, or it could differ. - - - _`html.imagemap` (Useful outside of HTML? If not, replace with - image only in non-HTML writers?) - - - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_. - - - _`parts.citations`: See `Footnote & Citation Gathering`_. - - - _`misc.exec`: Execute Python code & insert the results. Perhaps - dangerous? Call it "python" to allow for other languages? - - - _`misc.system`?: Execute an ``os.system()`` call, and insert the - results (possibly as a literal block). Definitely dangerous! How - to make it safe? Perhaps such processing should be left outside - of the document, in the user's production system (a makefile or a - script or whatever). Or, the directive could be disabled by - default and only enabled with an explicit command-line option or - config file setting. Even then, an interactive prompt may be - useful, such as: - - The file.txt document you are processing contains a "system" - directive requesting that the ``sudo rm -rf /`` command be - executed. Allow it to execute? (y/N) - - - _`misc.eval`: Evaluate an expression & insert the text. At parse - time or at substitution time? Dangerous? Perhaps limit to canned - macros; see text.date_ below. - - - _`misc.encoding`: Specify the character encoding of the input - data. But there are problems: - - - When it sees the directive, the parser will already have read - the input data, and encoding determination will already have - been done. - - - If a file with an "encoding" directive is edited and saved with - a different encoding, the directive may cause data corruption. - - - _`misc.language`: Specify the language of a document. There is a - problem similar to the first problem listed for misc.encoding_, - although to a lesser degree. - - - _`misc.settings`: Set any Docutils runtime setting from within a - document? - - - _`misc.charents`: Equivalent to:: - - .. include:: {includepath}/charents.txt - - - Docutils already has the ability to say "use this content for - Writer X" (via the "raw" directive), but it doesn't have the - ability to say "use this content for any Writer other than X". It - wouldn't be difficult to add this ability though. - - My first idea would be to add a set of conditional directives. - Let's call them "writer-is" and "writer-is-not" for discussion - purposes (don't worry about implemention details). We might - have:: - - .. writer-is:: text-only - - :: - - +----------+ - | SNMP | - +----------+ - | UDP | - +----------+ - | IP | - +----------+ - | Ethernet | - +----------+ - - .. writer-is:: pdf - - .. figure:: protocol_stack.eps - - .. writer-is-not:: text-only pdf - - .. figure:: protocol_stack.png - - This could be an interface to the Filter transform - (docutils.transforms.components.Filter). - - The ideas in `adaptable file extensions`_ above may also be - applicable here. - - Here's an example of a directive that could produce multiple - outputs (*both* raw troff pass-through *and* a GIF, for example) - and allow the Writer to select. :: - - .. eqn:: - - .EQ - delim %% - .EN - %sum from i=o to inf c sup i~=~lim from {m -> inf} - sum from i=0 to m sup i% - .EQ - delim off - .EN - - - _`body.qa` (directive a.k.a. "faq", "questions"): Questions & - Answers. Implement as a generic two-column marked list? As a - standalone (non-directive) construct? (Is the markup ambiguous?) - Add support to parts.contents. - - New elements would be required. Perhaps:: - - <!ELEMENT question_list (question_list_item+)> - <!ATTLIST question_list - numbering (none | local | global) - #IMPLIED - start NUMBER #IMPLIED> - <!ELEMENT question_list_item (question, answer*)> - <!ELEMENT question %text.model;> - <!ELEMENT answer (%body.elements;)+> - - Originally I thought of implementing a Q&A list with special - syntax:: - - Q: What am I? - - A: You are a question-and-answer - list. - - Q: What are you? - - A: I am the omniscient "we". - - Where each "Q" and "A" could also be numbered (e.g., "Q1"). - However, a simple enumerated or bulleted list will do just fine - for syntax. A directive could treat the list specially; e.g. the - first paragraph could be treated as a question, the remainder as - the answer (multiple answers could be represented by nested - lists). Without special syntax, this directive becomes low - priority. - - - _`body.example`: Examples; suggested by Simon Hefti. Semantics as - per Docbook's "example"; admonition-style, numbered, reference, - with a caption/title. - - - _`body.index`: Index targets. - - Were I writing a book with an index, I guess I'd need two - different kinds of index targets: inline/implicit and - out-of-line/explicit. For example:: - - In this `paragraph`:index:, several words are being - `marked`:index: inline as implicit `index`:index: - entries. - - .. index:: markup - .. index:: syntax - - The explicit index directives above would refer to - this paragraph. - - The words "paragraph", "marked", and "index" would become index - entries pointing at the words in the first paragraph. The index - entry words appear verbatim in the text. (Don't worry about the - ugly ":index:" part; if indexing is the only/main application of - interpreted text in your documents, it can be implicit and - omitted.) The two directives provide manual indexing, where the - index entry words ("markup" and "syntax") do not appear in the - main text. We could combine the two directives into one:: - - .. index:: markup; syntax - - Semicolons instead of commas because commas could *be* part of the - index target, like:: - - .. index:: van Rossum, Guido - - Another reason for index directives is because other inline markup - wouldn't be possible within inline index targets. - - Sometimes index entries have multiple levels. Given:: - - .. index:: statement syntax: expression statements - - In a hypothetical index, combined with other entries, it might - look like this:: - - statement syntax - expression statements ..... 56 - assignment ................ 57 - simple statements ......... 58 - compound statements ....... 60 - - Inline multi-level index targets could be done too. Perhaps - something like:: - - When dealing with `expression statements <statement syntax:>`, - we must remember ... - - The opposite sense could also be possible:: - - When dealing with `index entries <:multi-level>`, there are - many permutations to consider. - - Also "see / see also" index entries. - - Given:: - - Here's a paragraph. - - .. index:: paragraph - - (The "index" directive above actually targets the *preceding* - object.) The directive should produce something like this XML:: - - <paragraph> - <index_entry text="paragraph"/> - Here's a paragraph. - </paragraph> - - This kind of content model would also allow true inline - index-entries:: - - Here's a `paragraph`:index:. - - If the "index" role were the default for the application, it could be - dropped:: - - Here's a `paragraph`. - - Both of these would result in this XML:: - - <paragraph> - Here's a <index_entry>paragraph</index_entry>. - </paragraph> - - - _`body.literal`: Literal block, possibly "formal" (see `object - numbering and object references`_ above). Possible options: - - - "highlight" a range of lines - - "number" or "line-numbers" - - See docutils-users 2003-03-03. - - - _`body.sidebar`: Add to the already implemented directive. Allow - internal section structure, with adornment styles independent of - the main document. - - - _`colorize.python`: Colorize Python code. Fine for HTML output, - but what about other formats? Revert to a literal block? Do we - need some kind of "alternate" mechanism? Perhaps use a "pending" - transform, which could switch its output based on the "format" in - use. Use a factory function "transformFF()" which returns either - "HTMLTransform()" instance or "GenericTransform" instance? - - If we take a Python-to-HTML pretty-printer and make it output a - Docutils internal doctree (as per nodes.py) instead of HTML, then - each output format's stylesheet (or equivalent) mechanism could - take care of the rest. The pretty-printer code could turn this - doctree fragment:: - - <literal_block xml:space="preserve"> - print 'This is Python code.' - for i in range(10): - print i - </literal_block> - - into something like this ("</>" is end-tag shorthand):: - - <literal_block xml:space="preserve" class="python"> - <keyword>print</> <string>'This is Python code.'</> - <keyword>for</> <identifier>i</> <keyword - >in</> <expression>range(10)</>: - <keyword>print</> <expression>i</> - </literal_block> - - But I'm leaning toward adding a single new general-purpose - element, "phrase", equivalent to HTML's <span>. Here's the - example rewritten using the generic "phrase":: - - <literal_block xml:space="preserve" class="python"> - <phrase class="keyword">print</> <phrase - class="string">'This is Python code.'</> - <phrase class="keyword">for</> <phrase - class="identifier">i</> <phrase class="keyword">in</> <phrase - class="expression">range(10)</>: - <phrase class="keyword">print</> <phrase - class="expression">i</> - </literal_block> - - It's more verbose but more easily extensible and more appropriate - for the case at hand. It allows us to edit style sheets to add - support for new formats, not the Docutils code itself. - - Perhaps a single directive with a format parameter would be - better:: - - .. colorize:: python - - print 'This is Python code.' - for i in range(10): - print i - - But directives can have synonyms for convenience. "format:: - python" was suggested, but "format" seems too generic. - - - _`text.date`: Datestamp. For substitutions. The directive could - be followed by a formatting string, using strftime codes. Default - is "%Y-%m-%d" (ISO 8601 date), but time fields can also be used. - - - Combined with the "include" directive, implement canned macros? - E.g.:: - - .. include:: <macros> - - Today's date is |date|. - - Where "macros" contains ``.. |date| date::``, among others. - - - _`text.time`: Timestamp. For substitutions. Shortcut for - ``.. date:: %H:%M``. Date fields can also be used. - - - _`pysource.usage`: Extract a usage message from the program, - either by running it at the command line with a ``--help`` option - or through an exposed API. [Suggestion for Optik.] - - -Interpreted Text -```````````````` - -Interpreted text is entirely a reStructuredText markup construct, a -way to get around built-in limitations of the medium. Some roles are -intended to introduce new doctree elements, such as "title-reference". -Others are merely convenience features, like "RFC". - -All supported interpreted text roles must be known by the Parser. -Adding a new role often involves adding a new element to the DTD and -may require extensive support, therefore such additions should be well -thought-out. There should be a limited number of roles. - -The only place where no limit is placed on variation is at the start, -at the Reader/Parser interface. Transforms are inserted by the Reader -into the Transformer's queue, where non-standard elements are -converted. Once past the Transformer, no variation from the standard -Docutils doctree is possible. - -An example is the Python Source Reader, which will use interpreted -text extensively. The default role will be "Python identifier", which -will be further interpreted by namespace context into <class>, -<method>, <module>, <attribute>, etc. elements (see -spec/pysource.dtd), which will be transformed into standard hyperlink -references, which will be processed by the various Writers. No Writer -will need to have any knowledge of the Python-Reader origin of these -elements. - -* @@@ Add a test for language mappings of roles. - -* Alan Jaffray suggested (and I agree) that it would be sensible to: - - - have a directive and/or command-line option to specify a default - role for interpreted text - - allow the reST processor to take an argument for the default role - (this will be subsumed by the above via the runtime settings - mechanism) - - issue a warning when processing documents with no default role - which contain interpreted text with no explicitly specified role - (there will always be a default role, so this won't happen) - -* Add a directive establishing a mapping of interpreted text role - aliases? A set of default roles (index, acronym, etc.) could exist, - and the directive could assign abbreviations (i, a, etc.) or other - alternatives. - -* Add explicit interpreted text roles for the rest of the implicit - inline markup constructs: named-reference, anonymous-reference, - footnote-reference, citation-reference, substitution-reference, - target, uri-riference (& synonyms). - -* Add directives for each role as well? This would allow indirect - nested markup:: - - This text contains |nested inline markup|. - - .. |nested inline markup| emphasis:: - - nested ``inline`` markup - -* Add document-local _`role bindings`, associating directives with - roles? :: - - ``She wore ribbons in her hair and it lay with streaks of - grey``:rewrite: - - .. :rewrite: class:: rewrite - - The syntax is similar to that of substitution declarations, and the - directive/role association may resolve implementation issues. The - semantics, ramifications, and implementation details do need to be - worked out though. Syntax idea from Jeffrey C. Jacobs. - - The example above would implement the "rewrite" role as adding a - ``class="rewrite"`` attribute to the interpreted text ("inline" - element). The stylesheet would then pick up on the "class" - attribute to do the actual formatting. - - The same thing could be done with a directive, albeit a bit more - verbosely:: - - .. role:: rewrite - :class: rewrite - - The advantage of the new syntax would be flexibility. Uses other - than "class" may present themselves. - -* Perhaps a "role" directive can modify existing roles with - attributes? :: - - .. :api-ti: role:: api - :base: twisted.internet - - To start the reactor, use the :api-ti:`reactor.run` method. To - stop it, use :api-ti:`reactor.stop`. - -* Implement roles: - - - "acronym" and "abbreviation": Associate the full text with a short - form. Jason Diamond's description: - - I want to translate ```reST`:acronym:`` into ``<acronym - title='reStructuredText'>reST</acronym>``. The value of the - title attribute has to be defined out-of-band since you can't - parameterize interpreted text. Right now I have them in a - separate file but I'm experimenting with creating a directive - that will use some form of reST syntax to let you define them. - - Should Docutils complain about undefined acronyms or - abbreviations? - - What to do if there are multiple definitions? How to - differentiate between CSS (Content Scrambling System) and CSS - (Cascading Style Sheets) in a single document? - - How to define the full text? Possibilities: - - 1. With a directive and a definition list? :: - - .. acronyms:: - - reST - reStructuredText - DPS - Docstring Processing System - - Would this list remain in the document as a glossary, or would - it simply build an internal lookup table? A "glossary" - directive could be used to make the intention clear. - Acronyms/abbreviations and glossaries could work together. - - Then again, a glossary could be formed by gathering individual - definitions from around the document. - - 2. Some kind of `inline parameter syntax`__? :: - - `reST <reStructuredText>`:acronym: is `WYSIWYG <what you - see is what you get>`:acronym: plaintext markup. - - __ rst/alternatives.html#parameterized-interpreted-text - - 3. A combination of 1 & 2? - - The multiple definitions issue could be handled by establishing - rules of priority. For example, directive-based lookup tables - have highest priority, followed by the first inline definition. - Multiple definitions in directive-based lookup tables would - trigger warnings, similar to the rules of `implicit hyperlink - targets`__. - - __ rst/reStructuredText.html#implicit-hyperlink-targets - - - "annotation": The equivalent of the HTML "title" attribute. This - is secondary information that may "pop up" when the pointer hovers - over the main text. A corresponding directive would be required - to associate annotations with the original text (by name, or - positionally as in anonymous targets?). - - - "figure", "table", "listing", "chapter", "page", etc: See `object - numbering and object references`_ above. - - - "term"?: Unfamiliar or specialized terminology. - - - "glossary-term": This would establish a link to a glossary. It - would require an associated "glossary-entry" directive, whose - contents could be a definition list:: - - .. glossary-entry:: - - term1 - definition1 - term2 - definition2 - - This would allow entries to be defined anywhere in the document, - and collected (via a "glossary" directive perhaps) at one point. - - -Unimplemented Transforms ------------------------- - -Footnote & Citation Gathering -````````````````````````````` - -Collect and move footnotes & citations to the end of a document. -(Separate transforms.) - - -Hyperlink Target Gathering -`````````````````````````` - -It probably comes in two phases, because in a Python context we need -to *resolve* them on a per-docstring basis [do we? --DG], but if the -user is trying to do the callout form of presentation, they would -then want to group them all at the end of the document. - - -Reference Merging -````````````````` - -When merging two or more subdocuments (such as docstrings), -conflicting references may need to be resolved. There may be: - -* duplicate reference and/or substitution names that need to be made - unique; and/or -* duplicate footnote numbers that need to be renumbered. - -Should this be done before or after reference-resolving transforms -are applied? What about references from within one subdocument to -inside another? - - -Document Splitting -`````````````````` - -If the processed document is written to multiple files (possibly in a -directory tree), it will need to be split up. Internal references -will have to be adjusted. - -(HTML only? Initially, yes. Eventually, anything should be -splittable.) - -Idea: insert a "split here" attribute into the root element of each -split-out document, containing the path/filename. The Output object -will recognize this attribute and split out the files accordingly. -Must allow for common headers & footers, prev/next, breadcrumbs, etc. - - -Navigation -`````````` - -If a document is split up, each segment will need navigation links: -parent, children (small TOC), previous (preorder), next (preorder). -Part of `Document Splitting`_? - - -List of System Messages -``````````````````````` - -The ``system_message`` elements are inserted into the document tree, -adjacent to the problems themselves where possible. Some (those -generated post-parse) are kept until later, in ``document.messages``, -and added as a special final section, "Docutils System Messages". - -Docutils could be made to generate hyperlinks to all known -system_messages and add them to the document, perhaps to the end of -the "Docutils System Messages" section. - -Fred L. Drake, Jr. wrote: - - I'd like to propose that both parse- and transformation-time - messages are included in the "Docutils System Messages" section. - If there are no objections, I can make the change. - -The advantage of the current way of doing things is that parse-time -system messages don't require a transform; they're already in the -document. This is valuable for testing (unit tests, -tools/quicktest.py). So if we do decide to make a change, I think the -insertion of parse-time system messages ought to remain as-is and the -Messages transform ought to move all parse-time system messages -(remove from their originally inserted positions, insert in System -Messages section). - - -Filtering System Messages -````````````````````````` - -Currently the Writer is responsible for filtering out system messages -that are below the current threshold. Should the filtering be in a -separate transform? It would then happen regardless of the writer -used. Perhaps some writers don't want system messages filtered? - - -Others -`````` - -Index - - -HTML Writer ------------ - -* @@ Construct a _`templating system`, as in ht2html/yaptu, using - directives and substitutions for dynamic stuff. Or a specialized - writer to generate .ht & links.h files for ht2html? - -* Add a setting (or another writer) which produces just the contents - of the <body> element. What about the rest; it should be accessible - somehow, especially the docinfo fields. Part of the ht2html - implementation? Generic component output? - - I think a separate writer which inherits from html4css1.py would be - a good start. An "inline" or body-only HTML writer has to omit some - of the information given by the full HTML writer. Some applications - won't need this information, but others will; they'll want to deal - with it in different ways. I envision such a writer returning a set - of values: body html, and everything else (metadata). Perhaps a - tuple of this form:: - - (body_html, {'title': value, - 'subtitle': value, - 'docinfo': (tuple of (name, value) pairs), - etc.}) - - By having a separate writer, a different return data structure is - possible. We may need to add support to all of docutils to allow - for this variant output. Should the metadata values be simple text - strings, or HTML snippets (they may contain markup), or both? There - may be other issues to be worked out. - -* Add more support for <link> elements, especially for navigation - bars. - -* Make the admonitions more distinctive and varied. - -* Make the "class" attributes optional? Implies no stylesheet? - -* Add a setting to customize the header tag levels, i.e. <h1>. - -* Base list compaction on the spacing of source list? Would require - parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.) - -* Add a tool tip ("title" attribute?) to footnote back-links - identifying them as such. Text in Docutils language module. - -* Add an option to restrict the document title to <head><title> only, - and not include it in the document body. Subtitle? - - -Front-End Tools ---------------- - -* What about if we don't know which Reader and/or Writer we are - going to use? If the Reader/Writer is specified on the - command-line? (Will this ever happen?) - - Perhaps have different types of front ends: - - a) _`Fully qualified`: Reader and Writer are hard-coded into the - front end (e.g. ``pep2html [options]``, ``pysource2pdf - [options]``). - - b) _`Partially qualified`: Reader is hard-coded, and the Writer is - specified a sub-command (e.g. ``pep2 html [options]``, - ``pysource2 pdf [options]``). The Writer is known before option - processing happens, allowing the OptionParser to be built - dynamically. Alternatively, the Writer could be hard-coded and - the Reader specified as a sub-command (e.g. ``htmlfrom pep - [options]``). - - c) _`Unqualified`: Reader and Writer are specified as subcommands - (e.g. ``publish pep html [options]``, ``publish pysource pdf - [options]``). A single front end would be sufficient, but - probably only useful for testing purposes. - - d) _`Dynamic`: Reader and/or Writer are specified by options, with - defaults if unspecified (e.g. ``publish --writer pdf - [options]``). Is this possible? The option parser would have - to be told about new options it needs to handle, on the fly. - Component-specific options would have to be specified *after* - the component-specifying option. - - Allow common options before subcommands, as in CVS? Or group all - options together? In the case of the `fully qualified`_ - front ends, all the options will have to be grouped together - anyway, so there's no advantage (we can't use it to avoid - conflicts) to splitting common and component-specific options - apart. - -* Parameterize help text & defaults somehow? Perhaps a callback? Or - initialize ``settings_spec`` in ``__init__`` or ``init_options``? - -* Disable common options that don't apply? - -* Implement the "sectnum" directive as a command-line option also? - -* @@@ Come up with better names for the most-used tools, and install - them as scripts. - -* Create a single dynamic_ or unqualified_ front end that can be - installed? - - -Project Policies -================ - -A few quotes sum up the policies of the Docutils project. The IETF's -classic credo (by MIT professor Dave Clark) is an ideal we can aspire -to: - - We reject: kings, presidents, and voting. We believe in: rough - consensus and running code. - -As architect, chief cook and bottle-washer, I currently function as -BDFN (Benevolent Dictator For Now), but I would happily abdicate the -throne given a suitable candidate. Any takers? - -Eric S. Raymond, anthropologist of the hacker subculture, writes in -his essay `The Magic Cauldron`_: - - The number of contributors [to] projects is strongly and inversely - correlated with the number of hoops each project makes a user go - through to contribute. - - .. _The Magic Cauldron: - http://www.tuxedo.org/~esr/writings/magic-cauldron/ - -Therefore, we will endeavour to keep the barrier to entry as low as -possible. The policies below should not be thought of as barriers, -but merely as a codification of experience to date. These are "best -practices", not absolutes; exceptions are expected, tolerated, and -used as a source of improvement. - -As for control issues, Emmett Plant (CEO of the Xiph.org Foundation, -originators of Ogg Vorbis) put it well when he said: - - Open source dictates that you lose a certain amount of control - over your codebase, and that's okay with us. - - -Python Coding Conventions -------------------------- - -These are the conventions I use in my own code. Contributed code will -not be refused merely because it does not strictly adhere to these -conditions; as long as it's internally consistent, clean, and correct, -it probably will be accepted. But don't be surprised if the -"offending" code gets fiddled over time to conform to these -conventions. - -The Docutils project shall follow the generic coding conventions as -specified in the `Style Guide for Python Code`_ and `Docstring -Conventions`_ PEPs, with the following clarifications (from most to -least important): - -* 4 spaces per indentation level. No tabs. Indent continuation lines - according to the Emacs python-mode standard. - -* Use only ASCII, no 8-bit strings. See `Docutils - Internationalization`_. - -* No one-liner compound statements (i.e., no ``if x: return``: use two - lines & indentation), except for degenerate class or method - definitions (i.e., ``class X: pass`` is O.K.). - -* Lines should be no more than 78 characters long. - -* Use "StudlyCaps" for class names (except for element classes in - docutils.nodes). - -* Use "lowercase" or "lowercase_with_underscores" for function, - method, and variable names. For short names, maximum two words, - joined lowercase may be used (e.g. "tagname"). For long names with - three or more words, or where it's hard to parse the split between - two words, use lowercase_with_underscores (e.g., - "note_explicit_target", "explicit_target"). If in doubt, use - underscores. - -* Use 'single quotes' for string literals, and """triple double - quotes""" for docstrings. - -.. _Style Guide for Python Code: - http://www.python.org/peps/pep-0008.html -.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html -.. _Docutils Internationalization: howto/i18n.html#python-code - - -Copyrights and Licensing ------------------------- - -The majority of the Docutils project code and documentation has been -placed in the public domain. Unless clearly and explicitly indicated -otherwise, any patches (modifications to existing files) submitted to -the project for inclusion (via CVS, SourceForge trackers, mailing -lists, or private email) are assumed to be in the public domain as -well. - -Any new files contributed to the project should clearly state their -intentions regarding copyright, in one of the following ways: - -* Public domain (preferred): include the statement "This - module/document has been placed in the public domain." - -* Copyright & open source license: include a copyright notice, along - with either an embedded license statement, a reference to an - accompanying license file, or a license URL. - -One of the goals of the Docutils project, once complete, is to be -incorporated into the Python standard library. At that time copyright -of the Docutils code will be assumed by or transferred to the Python -Software Foundation (PSF), and will be released under Python's -license. If the copyright/license option is chosen for new files, the -license should be compatible with Python's current license, and the -author(s) of the files should be willing to assign copyright to the -PSF. - - -CVS Check-ins -------------- - -Instructions for CVS access can be found at -http://sourceforge.net/cvs/?group_id=38414. Anyone can access the CVS -repository anonymously. Only project developers can make changes. - -Unless you really *really* know what you're doing, please limit your -CVS commands to ``cvs checkout``, ``cvs commit/checkin``, and ``cvs -add``. Do **NOT** use ``cvs import`` unless you're absolutely sure -you know what you're doing. Even then, grab a copy of the `nightly -CVS tarball <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, -set it up on your own machine, and experiment *there* first. - -The `main source tree`_ ("docutils" CVS module) should always be kept -in a stable state (usable and as problem-free as possible). The -Docutils project shall follow the `Python Check-in Policies`_ (as -applicable), with particular emphasis as follows: - -* Before checking in any changes, run the entire Docutils test suite - to be sure that you haven't broken anything. From a shell:: - - cd docutils/test - alltests.py - -* When adding new functionality (or fixing bugs), be sure to add test - cases to the test suite. Practise test-first programming; it's fun, - it's addictive, and it works! - -* The `sandbox CVS directory`_ is the place to put new, incomplete or - experimental code. See `Additions to Docutils`_ and `The Sandbox`_ - below. - -* For bugs or omissions that have an obvious fix and can't possibly - mess up anything else, go right ahead and check it in directly. - -* For larger changes, use your best judgement. If you're unsure of - the impact, or feel that you require advice or approval, patches or - `the sandbox`_ are the way to go. - -Docutils will pursue an open and trusting policy for as long as -possible, and deal with any abberations if (and hopefully not when) -they happen. I'd rather see a torrent of loose contributions than -just a trickle of perfect-as-they-stand changes. The occasional -mistake is easy to fix. That's what CVS is for. - -.. _main source tree: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/ -.. _Python Check-in Policies: http://www.python.org/dev/tools.html -.. _sandbox CVS directory: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ - - -Additions to Docutils -````````````````````` - -Additions to the project, such as new components, should be developed -in the `sandbox CVS directory`_ until they're in `good shape`_, -usable_, and `reasonably complete`_. Adding to the `main source -tree`_ or to a `parallel project`_ implies a commitment to the -Docutils user community. - -* Why the sandbox? - - Developers should be able to try out new components while they're - being developed for addition to main source tree. See `The - Sandbox`_ below. - -* _`Good shape` means that the component code is clean, readable, and - free of junk code (unused legacy code; by analogy with "junk DNA"). - -* _`Usable` means that the code does what it claims to do. An "XYZ - Writer" should produce reasonable XYZ. - -* _`Reasonably complete` means that the code must handle all input. - Here "handle" means that no input can cause the code to fail (cause - an exception, or silently and incorrectly produce nothing). - "Reasonably complete" does not mean "finished" (no work left to be - done). For example, a writer must handle every standard element - from the Docutils document model; for unimplemented elements, it - must *at the very least* warn that "Output for element X is not yet - implemented in writer Y". - -If you really want to check code into the main source tree, you can, -but you'll have to be prepared to work on it intensively and complete -it quickly. People will start to use it and they will expect it to -work! If there are any issues with your code, or if you only have -time for gradual development, you should put it in the sandbox first. -It's easy to move code over to the main source tree once it's closer -to completion. - - -Mailing Lists -------------- - -Developers should subscribe to the mailing lists: - -* The `Python Documentation Special Interest Group (Doc-SIG) mailing - list`__ for high-level discussions on syntax, strategy, and design - (email to Doc-SIG@python.org). -* Docutils-develop__, for implementation discussions - (email to docutils-develop@lists.sourceforge.net). -* Docutils-checkins__, to monitor CVS checkin messages (automatically - generated; normally read-only). - -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins - - -The Sandbox ------------ - -The `sandbox CVS directory`_ is a place to play around, to try out and -share ideas. It's a part of the CVS repository but it isn't -distributed as part of Docutils releases. Feel free to check in code -to the CVS sandbox; that way people can try it out but you won't have -to worry about it working 100% error-free, as is the goal of the `main -source tree`_. Each developer who wants to play in the sandbox should -create their own subdirectory (suggested name: SourceForge ID, -nickname, or given name + family initial). It's OK to make a mess! -But please, play nice. - -Please update the `sandbox README`_ file with links and a brief -description of your work. - -In order to minimize the work necessary for others to install and try -out new, experimental components, the following sandbox directory -structure is recommended:: - - sandbox/ - userid/ - component_name/ # A verbose name is best. - README.txt # Please explain requirements, - # purpose/goals, and usage. - docs/ - ... - component.py # The component is a single module. - # *OR* (but *not* both) - component/ # The component is a package. - __init__.py # Contains the Reader/Writer class. - other1.py # Other modules and data files used - data.txt # by this component. - ... - test/ # Test suite. - ... - tools/ # For front ends etc. - ... - setup.py # Use Distutils to install the component - # code and tools/ files into the right - # places in Docutils. - -Some sandbox projects are destined to become Docutils components once -completed. Others, such as add-ons to Docutils or applications of -Docutils, graduate to become `parallel projects`_. - -.. _sandbox README: http://docutils.sf.net/sandbox/README.html - - -.. _parallel project: - -Parallel Projects ------------------ - -Parallel projects contain useful code that is not central to the -functioning of Docutils. Examples are specialized add-ons or -plug-ins, and applications of Docutils. They use Docutils, but -Docutils does not require their presence to function. - -An official parallel project will have its own CVS directory beside -(or parallel to) the main Docutils CVS directory. It can have its own -web page in the docutils.sourceforge.net domain, its own file releases -and downloadable CVS snapshots, and even a mailing list if that proves -useful. However, an official parallel project has implications: it is -expected to be maintained and continue to work with changes to the -core Docutils. - -A parallel project requires a project leader, who must commit to -coordinate and maintain the implementation: - -* Answer questions from users and developers. -* Review suggestions, bug reports, and patches. -* Monitor changes and ensure the quality of the code and - documentation. -* Coordinate with Docutils to ensure interoperability. -* Put together official project releases. - -Of course, related projects may be created independently of Docutils. -The advantage of a parallel project is that the SourceForge -environment and the developer and user communities are already -established. Core Docutils developers are available for consultation -and may contribute to the parallel project. It's easier to keep the -projects in sync when there are changes made to the core Docutils -code. - - -Release Procedure -================= - -1. Edit the version number in the following files: - - * docutils: - - - setup.py - - HISTORY.txt - - docutils/__init__.py - - * web: index.txt - -2. Run the test suite: ``cd test ; alltests.py``. - -3. Isolate from outside influence: - - (a) Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py for pre-2.3 - installations). - - (b) Clear/unset the PYTHONPATH environment variable. - -4. Create the release tarball: - - (a) Create a new empty directory and ``cd`` into it. - - (b) Get a clean snapshot of the CVS files:: - - cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \ - export -rHEAD docutils - - (c) Use Distutils to create the release tarball:: - - cd docutils - python setup.py sdist - -5. Expand and install the release tarball **in isolation** (as per - step 3 above): - - (a) Expand the tarball in a new location, not over any existing - files. - - (b) Install from expanded directory:: - - cd docutils-X.Y - python setup.py install - - The "install" command may require root permissions. - -6. Run the test suite from the expanded archive directory: ``cd test ; - alltests.py``. - -7. Run ``cd tools ; buildhtml.py ..`` to confirm that there are no - unexpected issues with the docs. - -8. Upload the release tarball:: - - $ ftp upload.sourceforge.net - Connected to osdn.dl.sourceforge.net. - ... - Name (upload.sourceforge.net:david): anonymous - 331 Anonymous login ok, send your complete e-mail address as password. - Password: - ... - 230 Anonymous access granted, restrictions apply. - ftp> bin - 200 Type set to I. - ftp> cd /incoming - 250 CWD command successful. - ftp> put filename - -9. Log in to the SourceForge web interface. - -10. Access the file release system on SourceForge (Admin interface). - Fill in the fields: - - :Package ID: docutils - :Release Name: <use release number only, e.g. 0.3> - :Release Date: <today's date> - :Status: Active - :File Name: <select the file just uploaded> - :File Type: Source .gz - :Processor Type: Platform-Independent - :Release Notes: <insert README.txt file here> - :Change Log: <insert summary from announcement> - - Also check the "Preserve my pre-formatted text" box. - -11. Wait up to 30 minutes for the file to become available on - SourceForge. - -12. Download the release tarball and verify its integrity by walking - through an installation, as outlined above (steps 5, 6, & 7). - -13. Add a SourceForge News item, with title "Docutils 0.x released" - and containing the release tarball's download URL. - -14. Send announcement email to: - - * docutils-develop@lists.sourceforge.net - * docutils-users@lists.sourceforge.net - * doc-sig@python.org - * python-list@python.org - * python-announce@python.org - -15. Register - - (a) with PyPI (Fill in details. ``python setup.py register``? - How to log in?) - (b) with Vaults of Parnassus - (c) with FreshMeat? - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |