|
⇤ ← Revision 1 as of 2002-07-12 22:29:49
Size: 4448
Comment: missing edit-log entry for this revision
|
Size: 690
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| language like TeX, Troff or HTML/SGML/XML. | language like TeX, Troff or HTML/SGML/XML and being able to create richly structured documents without thinking about the markup. The StructuredText markup language is intiutive, minimal and unobtrusive. There are several different versions of StructuredText: * ClassicStructuredText * [http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG StructuredTextNG] * [http://docutils.sourceforge.net/mirror/setext/ Setext] * ReStructuredText |
| Line 6: | Line 15: |
The following text describes ClassicStructuredText and how it tries to make use of indentation and simple symbology to guess the structure of a document. For the next generation of structured text, see [http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG here]. 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. Special symbology is used to indicate special constructs: * A single-line paragraph whose immediately succeeding paragraphs are lower level 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 is. * 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. * 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 surrounded by '_' underscore characters (with whitespace to the left and whitespace or punctuation to the right) is made underlined. * Text encloded by double quotes followed by a colon, a 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 ... Is interpreted as '<a href="http://www.zope.org/">Zope</a> is ....' '''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:amos@digicool.com. Is interpreted as '<a href="mailto:amos@digicool.com">mail me</a>.' * Text enclosed in brackets which consists only of letters, digits, underscores and dashes is treated as hyper links within the document. For example: As demonstrated by Smith [12] this technique is quite effective. Is interpreted as '... by Smith <a href="#12">[12]</a> this ...'. Together with the next rule this allows easy coding of references or end notes. * Text enclosed in brackets which is preceded by the start of a line, two periods and a space is treated as a named link. For example: .. [12] "Effective Techniques" Smith, Joe ... Is interpreted as '<a name="12">[12]</a> "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes. * A paragraph that has blocks of text enclosed in '||' is treated as a table. The text blocks correspond to table cells and table rows are denoted by newlines. By default the cells are center aligned. A cell can span more than one column by preceding a block of text with an equivalent number of cell separators '||'. Newlines and '|' cannot be a part of the cell text. For example: {{{ |||| **Ingredients** || || *Name* || *Amount* || ||Spam||10|| ||Eggs||3|| }}} renders like this: |||| **Ingredients** || || *Name* || *Amount* || ||Spam||10|| ||Eggs||3|| |
The basic idea behind StructuredText is to avoid the necessity for a markup language like TeX, Troff or HTML/SGML/XML and being able to create richly structured documents without thinking about the markup. The StructuredText markup language is intiutive, minimal and unobtrusive.
There are several different versions of StructuredText:
[http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG StructuredTextNG]
One application of StructuredText which is currently discussed on the DocSig is the generation of documentation from Python DocStrings.