Help on Structured Text
Created by .
Last modified on 2003/08/05.
Introduction
Structured Text, being a highly Cool Thing,
is a tool that Should Be Known To All.
It is excellent for quickly prototyping Web pages
for our favorite playground: Zope.
However I find myself unable to always remember
all of the functionality of the structured text
document, ergo the raison d'etre for this HOWTO.
This is almost just a copy and paste of
documentation I found in the source code. When
I first put this document together I was unaware
that I didn't know how to actually include
structured text into my DTML methods and
documents. For those of you facing similar
quandries I have included a short example at the
end of this document on how to include structured
text in DTML documents. Don't worry- it is really
quite simple once you know the magical
incantantions. Enjoy!
Suggestions of any sort are always
appreciated.
Structured Text Manipulation
Parse a structured text string into a form that can be used with
structured formats, like html.
Structured text is text that uses indentation and simple
symbology to indicate the structure of a document.
A structured string consists of a sequence of paragraphs separated by
one or more blank lines. Each paragraph has a level which is defined
as the minimum indentation of the paragraph. A paragraph is a
sub-paragraph of another paragraph if the other paragraph is the last
preceding paragraph that has a lower level.
Special symbology is used to indicate special constructs:
- A single-line paragraph whose immediately succeeding paragraphs are lower
level is treated as a header.
- A paragraph that begins with a '-',
*, or o is treated as an
unordered list (bullet) element.
- A paragraph that begins with a sequence of digits followed by a
white-space character is treated as an ordered list element.
- A paragraph that begins with a sequence of sequences, where each
sequence is a sequence of digits or a sequence of letters followed
by a period, is treated as an ordered list element.
- A paragraph with a first line that contains some text, followed by
some white-space and
-- is treated as
a descriptive list element. The leading text is treated as the
element title.
- Sub-paragraphs of a paragraph that ends in the word
example or the
word examples, or :: is treated as example code and is output as is.
- Text enclosed single quotes (with white-space to the left of the
first quote and whitespace or puctuation to the right of the second quote)
is treated as example code.
- Text surrounded by
* characters (with white-space to the left of the
first * and whitespace or puctuation to the right of the second *)
is emphasized.
- Text surrounded by
** characters (with white-space to the left of the
first ** and whitespace or puctuation to the right of the second **)
is made strong.
- Text surrounded by
_ underscore characters (with whitespace to the left
and whitespace or punctuation to the right) is made underlined.
- Text enclosed by double quotes followed by a colon, a URL, and concluded
by punctuation plus white space, or just white space, is treated as a
hyper link. For example:
"Zope":http://www.zope.org/ is ...
Is interpreted as <a href="http://www.zope.org/">Zope</a> is ....
Note: This works for relative as well as absolute URLs.
- Text enclosed by double quotes followed by a comma, one or more spaces,
an absolute URL and concluded by punctuation plus white space, or just
white space, is treated as a hyper link. For example:
mail me.
Is interpreted as "<a href="mailto:[email protected]">mail me</a>."
- Text enclosed in brackets which consists only of letters, digits,
underscores and dashes is treated as hyper links within the document.
For example:
As demonstrated by Smith [a12] this technique is quite effective. [r1]
Is interpreted as ... by Smith <a href="#a12">[12]</a> this .... Together
with the next rule this allows easy coding of references or end notes.
- Text enclosed in brackets which is preceded by the start of a line, two
periods and a space is treated as a named link. For example:
.. [a12] "Effective Techniques" Smith, Joe
Is interpreted as <a name="a12">[12]</a> "Effective Techniques" .... [r2]
Together with the previous rule this allows easy coding of references or
end notes.
[r1] According to the HTML 4.0
specification
identifiers must start with a letter so using
references like [12] is a bit of a no-no, though it does work (at
least in all the browsers I've tried). The
StructuredText Python module should probably be
updated to do something nice like prepend ref
whenver it sees only numbers in a link.
[r2] The use of name here is deprecated, id
should be used instead. Not there is much you
as the document author can do about this since
it's StructuredText that is generating the HTML
(and it probably should be modified to do the
right thing) but at least when somebody comes to
nitpick you can say "Yes, I know. Everybody knows
about this, now go away and let me get some work
done before I have to show just how strong my
Kung Fu really is."
Including Structured Text in DTML
I had the hardest time actually getting my
structured text to render into HTML until I learned
the following incantation:
<dtml-var stx_doc_name fmt=structured-text>
Without the fmt=structured-text part you will
just get the raw text, (something like this )
most likely not what you want.
Other Resources
It is well worth your time to check out Tres Seaver's
Structured Text Document
product. Conveniently provided is a ZClass one
can use to wrap one's STX content. Get it, use it,
and be happy.
There are a
few minor caveats to its use that should have absolutely
no bearing on 99% of what one would want to use this
product for. Nonetheless, do check the release notes for those
details before you use the product
(but you were going to do that regardless of what
I said, right?).
Log in
Forgot your password?