Structured Text Basics
— filed under: Documentation
When you edit a document on the English Department website, it can be in 'plain text', 'HTML', or 'Structured Text' format. This document describes what Structured Text is and how to use it.
When you edit a document on the English Department website, it can be created in one of three formats: 'plain text', 'HTML', or 'Structured Text' format:
Plain text permits no formatting at all: no boldface, italics, graphics or hypertext links. If you choose "HTML," you need to encode your document using XHTML 1.0, which requires a fair amount of expertise to generate. So this document describes the Structured Text alternative, and how to use it.
Structured Text permits us to employ all the common forms of document formatting, with a minimal number of skills to learn. Structured text reads implicit formatting common in traditional documents to generate standards-compliant XHTML 1.0.
The most basic idea in Structured Text is the paragraph. You can create paragraph formatting in Structured Text by hitting RETURN twice, to separate paragraphs in much the way that e-mail does. The following snippet of text:
This is the first paragraph. This is the second paragraph.
is automatically converted by the English Department website to display as separate paragraphs--the following in XHTML:
<p>This is the first paragraph.</p> <p>This is the second paragraph.</p>
This creates a web page with traditional paragraphing.
To introduce emphasis, Structured Text uses another text convention--asterisks. Place one asterisk before or after a word or phrase to place it in italics:
This is an *important* factor.
This snippet generates italics (using the XHTML <em> tag), which displays like this:
This is an important factor.
Place two asterisks before and after a word or phrase to place it in boldface. Note the following snippet:
This is a **vital** factor.
This snippet generates boldface (using the <strong> tag), which displays like this:
This is a vital factor.
UnderlinePlace an underline mark before and after a word or phrase to have it underlined. Note the following snippet:
This is a _crucial_ factor.
This snippet generates underlined text (using the <u> tag), which displays like this:
This is a crucial factor.
The preceding section focused on text conventions that convey a semantic meaning. This semantic meaning, when processed by Structured Text, produces certain HTML tags.
In Structured Text, indentation is also very important in conveying semantic meaning. The most basic is the idea from HTML of headings.
In the following snippet, indentation is used to convey an outline-like structure:
Using Indentation The preceding section focused on text conventions that convey a semantic meaning. This semantic meaning, when processed by Structured Text, produces certain HTML tags.
This produces the following HTML:
That is, the indentation conveyed a semantic meaning. The paragraph was subordinate to the heading, and the relationship is thus expressed in HTML. In fact, outline relationship can be continued:
Using Indentation The preceding section focused on text conventions that convey a semantic meaning. This semantic meaning, when processed by Structured Text, produces certain HTML tags. Basics of Indentation In this section we will investigate the basics of indentation... Hyperlinks
This produces the following HTML:
Lists and Items
Lists are also supported in Structured Text, including unordered, ordered, and descriptive lists. The convention unordered lists is a common pattern in text-based communication:
HTML has three kinds of lists:
Structured Text allows you to use the symbols '*', 'o', and '-' to connote unordered list items. If you make a list of items that begin with any of these three elements:
- Unordered lists - Ordered lists - Descriptive lists
The English Department website will format the list like this:
The Structured Text conventions for ordered lists is shown below:
HTML has three kinds of lists: 1. Unordered lists 2. Ordered lists 3. Descriptive lists
This produces an autonumbered list; the numbers will increment automatically, and won't automatically match the numbers from the source document (this permits you to add items later without manually renumbering everything):
Descriptive lists are also easily accommodated using double dashes:
Unordered Lists -- Generally inclues a series of bullets when viewed in HTML. Ordered Lists -- HTML viewers convert the list items into a numbered series. Descriptive Lists -- Usually used for definitional lists such as glossaries.
This becomes the following HTML:
The web isn't just HTML. Linking words and phrases to other information and including images are equally important. Fortunately Structured Text supports conventions for hyperlinks and image tags.
Let's start with a simple hyperlink. If we have a Structured Text paragraph discussing Python:
Please visit the "Python website":http://www.python.org/.
Please visit the Python website.
The English Department website will place hypertext links in blue, which become red when the mouse pointer hovers over them. Links to URL addresses outside of the "engl.iastate.edu" are displayed with a small icon of the Earth to the left of the link, to indicate it is an external link.
To add hypertext links to e-mail addresses, enter this:
to get this:
E-mail links will be preceded by a small icon of an envelope. When readers click these links, their browser will open the preferred e-mail application on that computer.
In brief, the convention for all Structured Text hypertext links is fairly simple:
To create a hypertext footnote reference in a Structured Text document, enter this:
I am going to refer to a footnote here . Later in the text I will have a footnotes section. ..  My footnote. The initial whitespace controls indentation, then the two periods followed by the space and the bracketed text create the anchor.
to get this (a footnote reference in the text which visitors can click in order to scroll directly down to the footnote):
I am going to refer to a footnote here . Later in the text I will have a footnotes section.  My footnote. The initial whitespace controls indentation, then the two periods followed by the space and the bracketed text create the anchor.
"Text shown when the browser does not load the image":img:logo.jpg
to load an image titled "logo.jpg" in the same folder on the server as the document:
You can also use an arbitrary URL from any Internet URL for the image, e.g.: