Written by Colin McCormack <colin@chinix.com>. April 2005.
Structured text is a wiki-inspired format to specify html (and other) documents.
Table Of Contents | |
1 | Structured Text |
1.1 | Paragraph Features |
1.1.1 | Lists |
1.1.1.1 | Unordered List Example: |
1.1.1.2 | Ordered List Example: |
1.1.1.3 | Nested List Examples: |
1.1.2 | Definition Lists |
1.1.2.1 | Definition List Example: |
1.1.3 | Preformatted Paragraphs |
1.1.3.1 | Preformatted Paragraph Example: |
1.1.4 | Headers |
1.1.4.1 | Header Example: |
1.1.5 | Horizontal Rule |
1.1.5.1 | Horizontal Rule Example: |
1.2 | Character Features |
1.2.1 | Typefaces |
1.2.2 | References |
1.2.3 | URL forms |
1.2.4 | Images |
1.2.4.1 | Image Examples |
2 | Relaxed Interpretation |
3 | Implementation |
3.0.1 | STX translation API |
3.1 | Source |
3.1.1 | Changelog |
A paragraph is represented as a sequence of lines terminated by a blank line.
Ordered and Unordered lists (and all nested variants thereof) are specified by a sequence of paragraphs beginning with some sequence of the characters '#' and '*'.
Note: as a special case, a list paragraph may run directly on from preceding list paragraphs (that is, without an intervening blank line.) This is for the convenience of authors and to improve document density.
The above text was generated by:
* Unordered lists are comprised of paragraph beginning with '*' * a non-list paragraph terminates the list. * unordered lists may nest, and may be nested
The above text was generated by:
# Ordered lists are comprised of paragraph beginning with '*' # a non-list paragraph terminates the list. # Ordered lists may nest, and may be nested
The above text was generated by:
* Unordered lists may include nested lists ** Nested lists may be unordered lists ** Such as this list, which begins with '**' *** Nesting may continue to an arbitrary depth *# Unordered lists may contain ordered lists *# Such as this list, which begins with '*#' * nested lists are compact
The above text was generated by:
# Unordered lists may include nested lists ## Nested lists may be unordered lists ## Such as this list, which begins with '##' ### Nesting may continue to an arbitrary depth #* Unordered lists may contain ordered lists #* Such as this list, which begins with '#*' # nested lists are compact
Definition lists are specified as they are in http://wikipedia.org/ formatting language
The above text was generated by:
;Definition List : a list comprised of pairs of terms and definitions ;Term : a thing to be associated with a definition ;Definition : a thing which describes a term. ;Circular Definition: this. ;Putative Definition: a definition which only appears to define. ;Ostensive Definition: a putative definition by example.
A paragraph comprised of lines which begin with a space character (' ') is not formatted in any way.
Note: a Simple Paragraph (one which is not a list, definition list, preformatted character, etc) must commence with a non-space character, but may have subsequent lines beginning with space.
This paragraph will not be reformatted in any way. Line breaks will be preserved. * special characters have no meaning * '''character level features''' and [references] are not interpreted.
A header is represented as a paragraph which begins with some number of '=' characters.
The number of '=' characters in the paragraph prefix determines the level of the header. Larger level headers are smaller.
Additionally, any text following subsequence (ie: non-prefix) '=' characters will be used to specify a tag, which (in the case of HTML translation) can be used as the local anchor of a link.
The above (header) text was generated by:
==== Header Example: ==== header_example
A horizontal rule is represented by a paragraph beginning with a '-'
The following horizontal rule was generated by:
----
In addition to paragraph formatting, Structured Text provides for character level features such as strong, italic, underlined, strike through, small caps, superscript, subscript and BIG typefaces.
Note: combinations of the above are possible thus
Note: The backslash character can be used to escape this special significance.
Anything within a paragraph which is contained in square brackets '[' & ']' is considered a link, or reference.
If the contents resembles a URL, subsequent contents are interpreted as descriptive text associated with the link.
Note: To avoid the special brace interpretation, double the braces, thus: [[ and ]]
Anything within a paragraph which resembles a URL, (ie: that commences with http:) will be turned into a Reference.
Additionally, [#: name some text] will be turned into an anchor suitable for local references.
Finally, [acronym: term | definition of term] will be turned into an html acronym.
The reference style [image:url] can be used to insert an inline image in text.
The reference style [left:url] can be used to insert an inline image in text with left flow-around, so that the image is positioned to the left and any subsequent text flows around it.
The reference style [right:url] can be used to insert an inline image in text with right flow-around, so that the image is positioned to the right and any subsequent text flows around it.
This is the tcl logo inline.
This effect was generated by:
This is the [image:logo125.gif] tcl logo inline.
This paragraph has two tcl logos, one with left and one with right flow-around.
Note: Horizontal Rule clears the image flow-around.
This effect was generated by:
[right:logo125.gif] [left:logo125.gif] This paragraph has two tcl logos, one with left and one with right flow-around.
In many cases a paragraph may be terminated by the introduction of a special paragraph formatting character on the first line of a subsequence line component, so the blank line terminates a paragraph rule is not absolutely enforced, however header lines must always be terminated by a blank line.
An stx2html.tcl script is provided to give a sample of translating Structured Text to HTML. It does nothing to prettify the text, leaving that to CSS.
This documentation is written in STX, and converted by stx2html into HTML.
The script stx.tcl converts STX formatted text into a tcl script suitable for evaluation within a namespace which interprets a set of commands semantically, and which emit the appropriate translation as functional return values.
To Be Done, meanwhile RTFS.
The software should be available here.