Here's the raw text for the HOWTO, yucky huh?

---

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", mailto:[email protected]. 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", mailto:[email protected]. 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 '[12]' this technique is quite effective. Is interpreted as '... by Smith <a href="#12">[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: .. '[12]' "Effective Techniques" Smith, Joe ... Is interpreted as '<a name="12">[12]</a> "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes. Notes <> 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":raw_text ) most like *not* what you want.