wxPython/samples/stxview/test.stx

   1 Structured Text Manipulation
   2
   3   Parse a structured text string into a form that can be used with
   4   structured formats, like html.
   5
   6   Structured text is text that uses indentation and simple
   7   symbology to indicate the structure of a document.
   8
   9   A structured string consists of a sequence of paragraphs separated by
  10   one or more blank lines.  Each paragraph has a level which is defined
  11   as the minimum indentation of the paragraph.  A paragraph is a
  12   sub-paragraph of another paragraph if the other paragraph is the last
  13   preceding paragraph that has a lower level.
  14
  15 Special symbology is used to indicate special constructs:
  16
  17     - A single-line paragraph whose immediately succeeding paragraphs are lower
  18     level is treated as a header.
  19
  20     - A paragraph that begins with a '-', '*', or 'o' is treated as an
  21     unordered list (bullet) element.
  22
  23     - A paragraph that begins with a sequence of digits followed by a
  24     white-space character is treated as an ordered list element.
  25
  26     - A paragraph that begins with a sequence of sequences, where each
  27     sequence is a sequence of digits or a sequence of letters followed
  28     by a period, is treated as an ordered list element.  If the sequence is
  29     made up of lower-case i's and v's, a lower-case roman-numeral list is
  30     generated.  If the sequence is made up of upper-case I's and V's, an
  31     upper-case roman-numeral list is generated.  If the sequence is made
  32     up of other lower case letters (typically a,b,c) a lowercase alphabetic
  33     list is generated.  If the sequence is made of of other upper case
  34     letters (typically, A,B,C) an uppercase alphabetic list is generated.
  35     If the sequence is something else (typically, 1,2,3), a arabic-numeral
  36     list is generated.
  37
  38     - A paragraph with a first line that contains some text, followed by
  39     some white-space and '--' is treated as a descriptive list element.
  40     The leading text is treated as the element title.
  41
  42     - Sub-paragraphs of a paragraph that ends in the word 'example' or the
  43     word 'examples', or '::' is treated as example code and is output as is.
  44
  45     - Text enclosed single quotes (with white-space to the left of the
  46     first quote and whitespace or puctuation to the right of the second quote)
  47     is treated as example code.
  48
  49     - Text surrounded by '*' characters (with white-space to the left of the
  50     first '*' and whitespace or puctuation to the right of the second '*')
  51     is *emphasized*.
  52
  53     - Text surrounded by '**' characters (with white-space to the left of the
  54     first '**' and whitespace or puctuation to the right of the second '**')
  55     is made **strong**.
  56
  57     - Text surrounded by '_' underscore characters (with whitespace to the left
  58     and whitespace or punctuation to the right) is made _underlined_.
  59
  60     - Text encloded by double quotes followed by a colon, a URL, and concluded
  61     by punctuation plus white space, *or* just white space, is treated as a
  62     hyper link. For example:
  63
  64     '"Zope":http://www.zope.org/ is ...'
  65
  66     Is interpreted as '<a href="http://www.zope.org/">Zope</a> is ...'
  67     Note: This works for relative as well as absolute URLs.
  68
  69     - Text enclosed by double quotes followed by a comma, one or more spaces,
  70     an absolute URL and concluded by punctuation plus white space, or just
  71     white space, is treated as a hyper link. For example:
  72
  73     "mail me", mailto:amos@digicool.com.
  74
  75     Is interpreted as '<a href="mailto:amos@digicool.com">mail me</a>.'
  76
  77     - Text enclosed in brackets which consists only of letters, digits,
  78     underscores and dashes is treated as hyper links within the document.
  79     For example:
  80
  81     As demonstrated by Smith [12] this technique is quite effective.
  82
  83     Is interpreted as '... by Smith <a href="#12">[12]</a> this ...'. Together
  84     with the next rule this allows easy coding of references or end notes.
  85
  86     - Text enclosed in brackets which is preceded by the start of a line, two
  87     periods and a space is treated as a named link. For example:
  88
  89     .. [12] "Effective Techniques" Smith, Joe ...
  90
  91     Is interpreted as '<a name="12">[12]</a> "Effective Techniques" ...'.
  92     Together with the previous rule this allows easy coding of references or
  93     end notes.
  94
  95
  96     - A paragraph that has blocks of text enclosed in '||' is treated as a
  97     table. The text blocks correspond to table cells and table rows are
  98     denoted by newlines. By default the cells are center aligned. A cell
  99     can span more than one column by preceding a block of text with an
 100     equivalent number of cell separators '||'. Newlines and '|' cannot
 101     be a part of the cell text. For example:
 102
 103     |||| **Ingredients** ||
 104     || *Name* || *Amount* ||
 105     ||Spam||10||
 106     ||Eggs||3||
 107
 108     is interpreted as::
 109
 110     <TABLE BORDER=1 CELLPADDING=2>
 111     <TR>
 112     <TD ALIGN=CENTER COLSPAN=2> <strong>Ingredients</strong> </TD>
 113     </TR>
 114     <TR>
 115     <TD ALIGN=CENTER COLSPAN=1> <em>Name</em> </TD>
 116     <TD ALIGN=CENTER COLSPAN=1> <em>Amount</em> </TD>
 117     </TR>
 118     <TR>
 119     <TD ALIGN=CENTER COLSPAN=1>Spam</TD>
 120     <TD ALIGN=CENTER COLSPAN=1>10</TD>
 121     </TR>
 122     <TR>
 123     <TD ALIGN=CENTER COLSPAN=1>Eggs</TD>
 124     <TD ALIGN=CENTER COLSPAN=1>3</TD>
 125     </TR>
 126     </TABLE>
 127