Structure text Help
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:
- Unordered lists
- Ordered lists
- 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 -
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