Skip to content. | Skip to navigation

Personal tools
Sections
You are here: Home wiki StructuredText

StructuredText

This material is adapted from http://www.zope.org/Documentation/Articles/STX

Structured text is good if you become proficient at it because you format while you type, however it can be tedious if you start worrying about the presentation rather than content. STOP if you find yourself doing extensive "tweaking" of your material to get the "format or style" right.

Another thing, from conversation with people following the tips from this and other pages, we conclude that using structured text is one of those learning through doing things. By reading this page on structured text in isolation you can only obtain know about information, you have not learnt structured text. Knowledge of the syntax of structured text the know how, arises only if your learning is embedded in creating some structured text. By focusing your attention on actively constructing a structured text artefact you learn and become knowledgable about structured text.

Warning, structured text gives only some VERY limited typographic or stylistic control over Wiki pages and other pages in Plone.

The following examples use structured text to describe structured text. It's a little (lot?) recursive and can be confusing. The style adopted below is to describe the feature, provide a code example (in the blue box) followed by the same example displayed as it would appear in a document. So, what is structured text? Let's look at the basics.

Quick and Dirty

copy and paste the example below to get started with your own structured text document.

A Nice Simple Structure:

  Heading 3

    Carmine divinas artes et conscia fati sidera.

    Diversos hominum variantia casus, caelestis rationis opus.

    Deducere mundo aggredior primusque novis Helicona.

    Heading 4

      Movere cantibus et viridi nutantis vertice silvas.

      Hospita sacra ferens nulli memorata priorum.

    And 'highlight' things using '

You can copy and paste the stuff in the box above into your own document.

The nice simple structure displays as...

Heading 3

Carmine divinas artes et conscia fati sidera.

Diversos hominum variantia casus, caelestis rationis opus.

Deducere mundo aggredior primusque novis Helicona.

Heading 4

Movere cantibus et viridi nutantis vertice silvas.

Hospita sacra ferens nulli memorata priorum.

And highlight things using '

Aside: Converting from the rendered HTML page into Word; copy & paste into Word; select text with similar formatting and format H2 as H1, H3 as H2, H4 as H3, H5 as H4; Create TOC; save.

Special Characters in Structured Text

Structured Text supports conventions that convey rendering rules. For example in the following snippet emphasis is conveyed using asterisks:

    This is *an italicised* phrase.  

    This is a **couple of bold** words.  

    This is an _underlined group_ of words.

is rendered as...

This is an italicised phrase.

This is a couple of bold words.

This is an underlined group of words.

The text above is rendered using the HTML em (emphasis) tag, the u tag and the strong tag. This is a common pattern in email. Some wiki and structured text displays will also parse the HTML tags directly if you choose to use them instead of these conventions. Other conventions are supported, such as referring to a piece of jargon using apostrophes::

When you see something between a pair of apostrophies like this, you know this is shorthand for jargon and displays in a fixed type font.

When you see something between a pair of apostrophies like this, you know this is shorthand for jargon and displays in a fixed type font.

Using Space in Structured Text

"White" space matters in Structured Text. This is a very powerful (and sometimes messy tool). White space is used to build rendering rules which, when processed by a structured text engine, displays the text using conventional HTML mark up.

For example headings can be built up using the following code snippet:

  My Heading (n.b. no spaces before 'My Heading')

    And this is my plain text paragraph which is indented by 2 or more spaces).

is rendered as...

My Heading (n.b. no spaces before My Heading)

And this is my plain text paragraph which is indented by 2 or more spaces).

In Structured Text, the number of spaces you use for indentation is very important in conveying information to the rendering engine. You can build up nice nested HTML like sub-headings (H1, H2, H3, paragraph) by increasing and decreasing the number of spaces you use at the begining of each paragraph. The inner most indented text (the text most in) is treated as paragraph text rather than a heading or sub-heading. I recommend you stick to a convention like 2 spaces, 4 spaces, 6 spaces, 8 spaces, etc. See the following example:

  For A Structured Text Heading

    Or sub-heading

      the number of spaces you use for indentation determines 

      what is treated as a heading/sub-heading or as body text. 

    You build up HTML like sub-headings 

      By increasing and decreasing the number of spaces you use. 

        I recommend you stick to a convention like;

    Four spaces,

      Six spaces, etc.  This paragraph renders as normal body text.

this example is rendered as

For A Structured Text Heading

Or sub-heading

the number of spaces you use for indentation determines

what is treated as a heading/sub-heading or as body text.

You build up HTML like sub-headings

By increasing and decreasing the number of spaces you use.

I recommend you stick to a convention like;

Four spaces,

Six spaces, etc. This paragraph renders as normal body text.

Bullet points and numbered lists are built up similarly using * or 1 on each line, for example:

    * A bullet point like the <ul> <li> tags in html

    * Another bullet point

    1. A numbered list like the <ol> <li> tags in html

    1. Another numbered line on the list

. becomes

  • A bullet point like the <ul> <li> tags in html
  • Another bullet point
  1. A numbered list like the <ol> <li> tags in html
  2. Another numbered line on the list

But remember, as with html, don't expect too much, it's basic functionality not a fully featured DTP package or word processor.

Tables

Tables can be built up simply in Structure Text if you're prepared to spend a bit of time typing underscores and bars. The concept is very simple, make the plain text "look" like a table, and it will display like a table if rendered using Structured Text. For example:

    |------------------------------------------------------------------------------|
    | Staff Name                 | Role           | Home page                      | 
    |==============================================================================|
    | Allen Higgins              | Lecturer       | "home page":/Members/ahiggins" |
    |------------------------------------------------------------------------------|

becomes...

Staff Name

Role

Home page

Allen Higgins

Lecturer

home page"

...clunky but effective.

Hyperlinks

Hyperlinks are relively easy, for example:

    "Click on this link":http://lists.freebsd.org/pipermail/freebsd-ports-bugs/ 

becomes Click on this link

(n.b. on Wiki you can get away with just entering a URL, the hyperlink with display nicely but you should probably use the style above for consistency - and it gets ride of long ugly !URLs spoiling the flow of your text too) so:

    http://slashdot.org

becomes http://slashdot.org

Footnotes

The Zope Book is an example of a Project that uses Structured Text outside of Zope. The book was written in Structured Text with some modifications to support figure handling, and the publisher's in-house markup format. Python scripts parse the input and create output in HTML and PDF.

Structured Text use is also used in Python doc strings. A number of Python documentation extraction tools support Structured Text. Currently work is under way on the Python doc-sig to develop docstring conventions, and a docstring processing system.

Conclusions

Structured Text gives you an easy way to express yourself in plain text.

From riemer Wed Aug 4 12:27:32 +0100 2004 From: riemer Date: Wed, 04 Aug 2004 12:27:32 +0100 Subject: good page, but...` Message-ID: <20040804122732+0100@mis.ucd.ie>

From ahiggins Thu Sep 16 15:05:09 +0100 2004 From: ahiggins Date: Thu, 16 Sep 2004 15:05:09 +0100 Subject: but what? Message-ID: <20040916150509+0100@mis.ucd.ie>