Structured Text: A Quick Intro

Structured text is essentially a What You Type Is What You Get way of formatting documents. It can be (and has been) used to format entire books, but in Plone (and, by inheritance, in the Division CMS) it can be used to format the content in your web pages. Structured text is not the only way to input content in to the Division CMS. You can also use:

• Plain text
• HTML code
• a built-in What You See Is What You Get (WSYIWYG) editor
• an external editor of your preference, the product of which can be then uploaded into the CMS

Ok, on to structured text. If I didn't use any HTML when writing this document, how am I getting bulleted lists (like the one above) and links? Here is what the code for a link looks like:

        "AMNH Research":http://research.amnh.org

That's it. Just take the text you want to be the hyper-text link, put it in double quotes, then put the address after the text and separate the two with a colon. For internal addresses, such as links to other documents in your department's pages, the "http://" is not required as part of the address; for external pages, the "http://" is required.

Bulleted lists are created by putting your items on separate lines with asterixes in front of each item:

        * Item 1

        * Item 2

Instead of asterixes you can use "-" (dash) or "o" (lower-case O) but they are interpreted the same way as the asterix.

Indentation

There is one unfortunate thing about structured text: much of the formatting is done by relative indentation. This means that headings (such as the ''Structured Text'' heading above) are only headings because the lines which follow are indented relative to them. This is unfortunate because it means that if you don't indent something properly, your document will not be formatted correctly. If you see strange formatting errors in your document, chances are it is because you've indented something incorrectly. For example, here is the structured text for the preceding paragraphs:

           Bulleted lists are created by putting your items on separate lines with asterixes in front of each item::

             * Item 1

             * Item 2

           Instead of asterixes you can use "-" (dash) or "o" (lower-case O) but they are interpreted the same way as the asterix.

           Indentation

              There is one unforunate thing about structured text: much of the formatting is 
done by *relative* indentation.  This means that...

The line with ''Indentation'' on it is only made into a heading because the first line of the paragraph following it has been indented.

Despite this somewhat annoying detail structured text is easier to use than HTML.

Text formatting

You can format text as underlined, bold, italicized, etc., using structured text.

Italics:

          *Italics*

Bold:

          **Bold**

Underlined :

          _Underlined_

Block quote :

          'Block quote'

Images

You can import images using structured text, too:

               "Image of Alex - this text is only visible if the image doesn't load":img:photos/roomtogrow1

As you can probably guess, the :img: indicates that the bit that follows describes where to find the image: I have folder called ''photos'' in my folder in which I put an image of my son, Alex. You'll notice that the image name does not have an extension: it is actually a JPEG image but, when I uploaded the image (by creating an IMAGE in my photos folder) I didn't bother putting the extension in: the CMS doesn't care.

Tables

Tables are easy, too:

          |----------------------------------|
          | Heading 1 | Heading 2 | Heading 3|
          |==================================|
          | Cell 1    |   Cell 2  |          |
          |----------------------------------|
          | Cell 3    |       Cell 4         |
          |----------------------------------|

Results in:

Note that spacing, including alignment of the vertical bars, is important.

Lists

I've already demonstrated how bulleted lists are formatted, but there are three types of lists you can create:

• Unordered, bulleted lists
• Ordered, numbered lists
• Definitions

Unordered, bulleted lists are like the one above, created with the following formatting:

          I've already demonstrated how bulleted lists are formatted, but there are three types of lists you can create:

          * Unordered, bulleted lists

          * Ordered, numbered lists

          * Definitions

Pay close note to the indentation of the first line ("I've already...") and the stars ("*") which are the bullets for the list: they are at the same indentation level. If the bullets had been indented relative to the first line, the first line would have been turned into a heading: indentation of preceding and succeeding lines is important in structured text! Let me show you what the result of indenting the bulleted list by one space, relative to the leading line, would be:

------------------

I've already demonstrated how bulleted lists are formatted, but there are three types of lists you can create:

• Unordered, bulleted lists
• Ordered, numbered lists
• Definitions

------------------

If you see this effect in one of your documents, you know you've got an extra indentation space somewhere.

Ordered, numbered lists are created in much the same way as bulleted lists:

         1. Oranges

         2. Apples

         3. Papayas

Results in:

1. Oranges
2. Apples
3. Papayas

Definition lists are useful for introducing terms:

          Rock -- grey lumpy thing that gets in the way when you're digging a hole.

          Boulder -- bigger version of a rock, often found in larger holes.

The above results in:

Rock

grey lumpy thing that gets in the way when you're digging a hole.

Boulder

bigger version of a rock, often found in larger holes.

You can also nest lists:

          * Item 1

            * Item 1a

          * Item 2

            * Item 2a

          1. Item 1

             1a. Item 1a

          2. Item 2

             2a. Item 2a

• Item 1
  • Item 1a
• Item 2
  • Item 2a

1. Item 1

   1a. Item 1a

2. Item 2

   2a. Item 2a

Mixing Structured Text and HTML

As it turns out, if you choose Structured Text as the default Format for your document, you can mix HTML with your structured text. For example, there is no way to put a simple horizontal line across the page in structured text: in HTML, you would do this with an <HR> tag. You could put a line of dashes (''-'') across the page in structured text, but this is rather clunky and doesn't always format well. However, if you put an HTML <HR> tag on a line by itself:

         <HR>

You get:

Also, you might decide that getting all of the spacing correct for a table might be a bit of a nuisance, especially if you have to repeatedly edit the items in a table. It is much easier to use HTML:

         <table border="1" >
          <tr>
           <th> Heading 1 
           </th>
           <th>  Heading 2 
           </th>
           <th>  Heading 3
           </th>
          </tr>
          <tr>
           <td> Cell 1   
           </td>
           <td align="center">    Cell 2  
           </td>
           <td></td>
          </tr>
          <tr>
           <td> Cell 3 
           </td>
           <td  colspan="2" align="center">        Cell 4               
           </td>
           </tr>
          </table>

Results in:

This mixing of HTML and structured text works because, when the indentation and formatting of the structured text is converted into HTML, the HTML tags are left alone (more or less).

Indentation, again

Indentation, especially indentation relative to other text like headings and leading paragraphs, is critical in structured text. If you use structured text to format a document and the resulting document looks completely messed-up, it is probably due to an extra space or two in front of one of your lines of text. If in doubt, go back and double check the spaces you put in front of the lines preceding the lines which aren't being formatted correctly.

Seriously - count the number of leading spaces for the types of headings you want and stick to it. For example, zero leading spaces for section headings, two leading spaces for sub-headings, and four spaces for paragraphs and bulleted lists.

Other resources

If you need more information about structured text, look at the following links:

• Zope.org - An introduction to Structured Text
• Plone book - Chapter 10
• Help on Structured Text by millejoh (a contributor to the Zope site).