StructuredTextNGRules

Structured text is text that uses indentation and simple symbology to indicate the structure of a document.

A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level.

To propose new rules or rule changes, please edit NGRuleProposals

Special symbology is used to indicate special constructs:

• A single-line paragraph with subparagraphs is treated as a header.
• A paragraph that begins with a '-', *, or o is treated as an unordered list (bullet) element.
• A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element.
• A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element.
• A paragraph with a first line that contains some text, followed by some white-space and -- is treated as a descriptive list element. The leading text is treated as the element title.
• Sub-paragraphs of a paragraph that ends in the word example or the word examples, or :: is treated as example code and is output as in:

     For instance ::
  
      <table border=0>
        <tr>
          <td> Foo 
      </table>
  

• Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code:

      For example: '<dtml-var foo>'.
  

• Text surrounded by * characters (with white-space to the left of the first * and whitespace or puctuation to the right of the second *) is emphasized.
• Text surrounded by ** characters (with white-space to the left of the first ** and whitespace or puctuation to the right of the second **) is made strong.
• Text encloded by double quotes followed by a colon, an URL, and concluded by punctuation plus white space, or just white space, is treated as a hyper link.

  For example, "Zope":http://www.zope.org/ is interpreted as Zope

  Note: This works for relative as well as absolute URLs?.

• Text encloded by double quotes followed by a colon, the string img, another colon, an URL, and concluded by punctuation plus white space, or just white space, is treated as an inline image.

  For example, "Zope icon":img:http://www.zope.org/p_/zopelogo_jpg is interpreted as (in HTML, <img alt="Zope icon" src="http://www.zope.org/p_/zopelogo_jpg">)

  Note: This works for relative as well as absolute URLs?.

• Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URL and concluded by punctuation plus white space, or just white space, is treated as a hyper link.

  For example: "mail me", mailto:[email protected] is interpreted as mail me

• SGML text is ignored and outputed as is.
• tables

  Name	Favorite Color
  Jim	Red
  John	Blue

  Hm:

       |-------------------------------------------------|
       | Function  | Documentation                       |
       |=================================================|
       | '__str__' | This method converts the            |
       |           |  the object to a string.            |
       |           |                                     |
       |           | - Blah                              |
       |           |                                     |
       |           | - Blaf                              |
       |           |                                     |
       |           |       |--------------------------|  |
       |           |       |  Name   | Favorite       |  |
       |           |       |         | Color          |  |
       |           |       |==========================|  |
       |           |       | Jim     |  Red           |  |
       |           |       |--------------------------|  |
       |           |       | John    |  Blue          |  |
       |           |       |--------------------------|  |
       |-------------------------------------------------|
  

gvanrossum (Mar 29, 2001 6:13 pm; Comment #1)

The rule that SGML (you mean HTML?) text is passed through unchanged is evil, because now we get all sorts of unpredictable interactions between ST and HTML. Plus it's hard to quote examples of HTML markup, which occur very frequently when talking about Zope...

    <div class="someclass"><!-- someclass sets up a font size, color, etc.-->
    **Put my structured text here**
    </div>

 I'm then using ZPT in an HTML document to pull in the structured text.  The HTML document defines the style sheet for "someclass".