= Structured Text =

 Written by Colin McCormack <colin@chinix.com>.  April 2005.

Structured text is a wiki-inspired format to specify html (and other) documents.
----

.toc
----
== 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:====

* 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:

 * 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:====

# 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:

 # 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:====

* 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

# 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 ===

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

* Definition lists are represented as a paragraph with leading ';'
* a ':' separates the '''defined term''' from its '''definition'''

====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 [references1] 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: #header_example ====

The above (header) text was generated by:

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

The text after # is a header tag, which may be any text which is valid for an
HTML anchor.  As a convenience hack, headers need not be terminated by two 
carriage returns.
----
=== Horizontal Rule ===

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

==== Horizontal Rule Example: ====

The following horizontal rule was generated by:

 ----
----

=== Tables ===

Table row paragraphs are indicated by a leading | character.

Header row paragraphs are indicated by a leading |+ character pair.

==== Table Example: ====

The following example is generated by:

 |+head1|head2|head3|head4
 |A1|A2|A3|A4
 |B1|''B2''|'''B3'''|B4
 ||"text with | "|C3|C4

|+head1|head2|head3|head4
|A1|A2|A3|A4
|B1|''B2''|'''B3'''|B4
||"text with | "|C3|C4

== 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 [image:logo125.gif] tcl logo inline.

This effect was generated by:

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

[right:logo125.gif] [left: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.

----
=== Forms ===

STX provides for embedded forms, using the Wub Form library.

==== Form Example 1: ====

 [form: form_name action moop.html]
 [hidden: hidden moop]
 [fieldset: details]
 [legend: "Details"]
 [text: user legend "User name: "]
 [text: email legend "Email: " moop]
 [checkset: illness legend Illnesses {none 0 +lameness 1 haltness 2 blindness 2}]
 [/fieldset]
 [submit: submit send]
 [/form]

'''Produces:'''

[form: form_name action moop.html]
[hidden: hidden moop]
[fieldset: details]
[legend: "Details"]
[text: user legend "User name: "]
[text: email legend "Email: " moop]
[checkset: illness legend Illnesses {none 0 +lameness 1 haltness 2 blindness 2}]
[/fieldset]
[submit: submit send]
[/form]

==== Form Example 2: ====

 [form: form_name action moop.html]
 [fieldset: search]
 [legend: "Search"]
 Sort: [selectset: sort1 {title author date}]
 Scope: [radioset: scope {site 0 +section 1}]
 [submit: submit search]
 [/fieldset]
 [/form]

'''Produces:'''

[form: form_name action moop.html]
[fieldset: search]
[legend: "Search"]
Sort: [selectset: sort1 {title author date}]
Scope: [radioset: scope {site 0 +section 1}]
[submit: submit search]
[/fieldset]
[/form]

==== Form Example 3: ====

 [form: form_name action moop.html]
 |+ Sort | Scope | Send
 |[selectset: sort1 {title author date}] | [radio: scope site] | [submit: submit search]
 ||[radio: scope section]

 [/form]

'''Produces:'''

[form: form_name action moop.html]
|+ Sort | Scope | Send
|[selectset: sort1 {title author date}] | [radio: scope site] | [submit: submit search]
||[radio: scope section]
[/form]

----
=== Evaluation ===

==== Evaluation Example: ====

 This is the current time \{\{\{[clock format [clock seconds]]\}\}\}

'''Produces:'''

This is the current time {{{[clock format [clock seconds]]}}}

----
=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 [http:stx.css CSS].

This documentation is written in [http:stx.txt 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 === api

''To Be Done'', meanwhile RTFS.

== Source ==

The software should be available [http:stx.tar.gz 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)
;13 Jul 2006: [[CMcC]] hacked headers to terminate them on \n not just \n\n

=== TODO ===

* modify TOC processing to handle documents with a single level-1 header

.message This is a processing message

.comment This is a comment
