Document Types

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

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.

Emphasis

Italics

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.

Boldface

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.

Underline

      This is a _crucial_ factor.

This snippet generates underlined text (using the <u> tag), which displays like this:

      This is a crucial factor.

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.

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:

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.

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:

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

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:

• Unordered lists
• Ordered lists
• Descriptive 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:

      
Unordered lists
Ordered lists
Descriptive lists

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

      
Unordered lists
Ordered lists
Descriptive lists

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:

      
Unordered Lists
Generally includes 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.

Hyperlinks

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/.

This becomes:

      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:

         "address@example.com":mailto:address@example.com

to get this:

         address@example.com

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:

• The text of the link reference is enclosed in quotes.
• The second quotation mark is followed by a colon and a URL.
• The URL can be followed by punctuation.

References

To create a hypertext footnote reference in a Structured Text document, enter this:

         I am going to refer to a footnote here [1].

         Later in the text I will have a footnotes
         section.

         .. [1] 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 [1].

      Later in the text I will have a footnotes
      section.

      [1] My footnote.  The initial whitespace
      controls indentation, then the two periods
      followed by the space and the bracketed text
      create the anchor.

Images

Enter this:

         "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.:

         "Plone logo":img:http://www.plone.org/logo.jpg