Structure text Help

explaining structured text (english)

Structured Text (STX) is an easy to learn but powerful document formatting system that is ideally suited to through-the-web applications. With Structured Text, format-independent writing becomes extremely convenient and natural, once a few rules are learned.

To get a quick idea of what Structured Text does, the following words in Structured Text:

  Sometimes the **best** approach to complexity is simplicty.  A good structured text system is:

  - Convenient

  - Rich

...would be rendered as:


Sometimes the best approach to complexity is simplicty. A good structured text system is:

  • Convenient
  • Rich


In fact, the text of this article is written in Structured Text (with the exception of the horizontal lines that demark example output). In this article, we'll look at the basics of Structured Text, organizing large text into sections, advanced formatting, and metadata issues.


Structured Text Basics

Let's plunge into structured text and look at the basics.

The most basic idea in Structured Text is a paragraph. The following snippet of STX:

  This is the first paragraph. 
  The quick brown fox jumps over the lazy dog. 

  This is the second paragraph. The quick brown fox jumps over the lazy dog. 

...is rendered as:


This is the first paragraph. The quick brown fox jumps over the lazy dog.

This is the second paragraph. The quick brown fox jumps over the lazy dog.


As you can see, whitespace matters in STX. A single carriage return (or line feed) is ignored while double carriage returns denote the end of the paragraph. It is a very intuitive idea that paragraphs are separated by whitespace.

To introduce emphasis, STX uses another text convention: asterisks * , single speech marks ' and underscore _ . Note the following snippet:

  Surrounding words with single asterisks *causes text to be formatted as italic.*

  Double asterisks causes the text to be output as **bold**

  'Single speech marks' have a highlighting effect!

  _Underscores have an underlining effect_

...would appear as:


Surrounding words with single asterisks causes text to be formatted as italic.

Double asterisks causes the text to be output as bold

Single speech marks have a highlighting effect!

Underscores have an underlining effect



Using Indentation

In STX, indentation is very important in conveying semantic meaning. The most basic is the idea of headings.

In the following STX snippet, indentation is used to convey an outline-like structure:

  Top Level
   The preceding section focused on text conventions that convey a semantic meaning.
   This semantic meaning, when processed by Structured Text, produces certain formatted output.

    Another Level
     In STX, indentation is also very important in conveying semantic meaning. 
     The most basic is the idea from HTML of headings.

     As you increase the level of indentation the size/format of the heading changes.

      Yet Another Level

       As you can see - 
       the headings use an increasingly smaller font as the indentation increases.
       It does become difficult to remember what level you are at.

This produces the following:


Top Level

The preceding section focused on text conventions that convey a semantic meaning. This semantic meaning, when processed by Structured Text, produces certain formatted output.

Another Level

In STX, indentation is also very important in conveying semantic meaning. The most basic is the idea from HTML of headings.

As you increase the level of indentation the size/format of the heading changes.

Yet Another Level

As you can see - the headings use an increasingly smaller font as the indentation increases. It does become difficult to remember what level you are at.



Lists and Items

Lists are also supported in STX, including unordered, ordered, and descriptive lists. The convention unordered lists is a common pattern in text-based communication known as a bullet-list. The following STX:

  STX has three kinds of lists:

   - Unordered lists

   - Ordered lists

   - Descriptive lists

...produces the following unordered list:


STX has three kinds of lists:

  • Unordered lists
  • Ordered lists
  • Descriptive lists


Numbered lists are created in a similar manner replacing the - symbol for the sequence number as in this example:

  STX has three kinds of lists:

   1 Unordered lists

   2 Ordered lists

   3 Descriptive lists

...produces the following ordered list:


STX has three kinds of lists:

  1. Unordered lists
  2. Ordered lists
  3. Descriptive lists


Descriptive lists are a little more complicated as the example below shows:

    Unordered Lists -- Generally inclues a series of bullets when
    viewed in a web browser.

    Ordered Lists -- Web browsers convert the list items into a
    numbered series.

    Descriptive Lists -- Usually used for definitional lists such as
    glossaries.


Unordered Lists
Generally inclues a series of bullets when viewed in HTML.
Ordered Lists
Web browsers convert the list items into a numbered series.
Descriptive Lists
Usually used for definitional lists such as glossaries.



Hyperlinks

In the previous sections we focused on ways to get certain presentational semantics in STX by using common text conventions.

But the web is also about linking to other sources of information by hyperlinks. Linking words and phrases to other information and including images are equally important. Fortunately Structured Text supports conventions for hyperlinks and images.

Let's start with a few simple hyperlinks. Consider the following snippet of STX:

  To go to a test page located in the same folder as this document
  click "here":test-document

  Click "here":http://www.surram.org.uk to visit the SAS website

  Send me an "email":mailto:kev@mckeown.2y.net

...would be rendered as:


To go to a test page located in the same folder as this document click here

Click here to visit the SAS website

Send me an email


Images may be incorporated into a structured text document as the following example shows:

  Here is an image -

  "Far Out":img:test-image

  Notice that the text in "quotes" becomes the image label.
  Place the mouse pointer over the image to see the label.

...would produce the following output:


Here is an image -

Far Out

Notice that the text in "quotes" becomes the image label. Place the mouse pointer over the image to see the label.



Conclusion

This article covers the basic features of Structured Text but hopefully enough to cover a users day to day requirements.

Indentation can be a bit tricky to get the hang of and you may see quite unexpected results if you make a mistake. Experimentation is always the best approach!

Other functions such as tables and the construction of relative and absolute paths to items are available, though better achieved using other methods such as HTML and are beyond the scope of this primer.

The bulk of this document has been filched without permission from Paul Everitt's article on zope.org

Kevin McKeown
Surrey Ambulance Service NHS Trust