Structured Text

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

Paragraph Features

A paragraph is represented as a sequence of lines terminated by a blank line.


Lists

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.


Unordered List Example:

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

Ordered List Example:

  1. Ordered lists are comprised of paragraph beginning with '*'
  2. a non-list paragraph terminates the list.
  3. Ordered 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

Nested List Examples:

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
  1. Unordered lists may include nested lists
    1. Nested lists may be unordered lists
    2. Such as this list, which begins with '##'
      1. Nesting may continue to an arbitrary depth
  2. 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

Definition lists are specified as they are in http://wikipedia.org/ formatting language

Definition List Example:

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.

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.

Preformatted Paragraphs

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.

Preformatted Paragraph Example:

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.

Headers

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.

Header Example:

The above (header) text was generated by:

==== Header Example: ==== header_example

Horizontal Rule

A horizontal rule is represented by a paragraph beginning with a '-'

Horizontal Rule Example:

The following horizontal rule was generated by:

----

Character Features

Typefaces

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.

strong
is represented ''thus''
italic
is represented '''thus'''
strike through
is represented --thus--
underline
is represented __thus__
small caps
is represented %%thus%%
superscript
is represented ^^thus^^
subscript
is represented ^^^thus^^^
big
is represented !!thus!!

Note: combinations of the above are possible thus

Note: The backslash character can be used to escape this special significance.


References

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 ]]


URL forms

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.


Images

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.

Image Examples

This is the logo125.gif tcl logo inline.

This effect was generated by:

This is the [image:logo125.gif] tcl logo inline.

logo125.gif logo125.gif 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.

Relaxed Interpretation

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.


Implementation

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.

STX translation API

To Be Done, meanwhile RTFS.

Source

The software should be available here.

Changelog

21 Apr 2005
[CMcC] Released
22 Apr 2005
[CMcC] move content into cdata tree elements
22 Apr 2005
[CMcC] allow compacted lists (nested lists don't start a new LI)
22 Apr 2005
[CMcC] added .toc (table of contents)