[ZDP] FAQ 0.2 - Structured Text

[Martijn Faassen]

Zope FAQ 0.2 - Structured Text

* What is Structured Text?
    
    Structured Text is plain ASCII text that follows some simple rules
    so that it can easily be translated to more advanced markup
    formats such as HTML. Zope provides facilities to automatically
    render Structured Text to HTML. Writing your documents in
    Structured Text is far less cumbersome than writing HTML directly,
    and has the added advantage of being readable in source form as
    well.

    For more information on StructuredText see::

        http://www.zope.org/Documentation/Reference/StructuredText

    but this link is currently not completely up to date; see the
    comments in 'lib\python\StructuredText\StructuredText.py' for the
    current documentation.

    The FAQ you are reading may be in Structured Text format.

* How do I use Structured Text in Zope?

    The easiest way is to put the Structured Text document inside a
    'text' property (by typing it in directly, or by using copy and
    paste from an external editor). This property may be associated
    with a Folder or with a DTML Document.

    We could for example place the Structured Text version of this FAQ
    in a property called 'faq_stx'. We can then make the following the
    following DTML Method in the same folder (or if you placed the
    'faq.stx' inside a DTML Document this would be it)::
    
        <standard_html_header>
        <!--#var faq_stx fmt="structured-text"-->
        <standard_html_footer>
    
    When this page is viewed, you should see the FAQ rendered to HTML.

    Another way to use Structured Text with Zope is to place it inside
    a DTML Method or Document. An advantage of this is that you can
    then use the 'upload' tab to upload your Structured Text document
    from a file on your machine directly into Zope.

    The following problem occurs however: when including Structured
    Text from a DTML Method into another Document with the
    'fmt="structured-text"' attribute, it will be quoted twice. This
    is because the '__str__' method of the 'DocumentTemplate.HTML'
    class automatically quotes its HTML when called.

    You can work around this by calling the Structured Text document's
    'read_raw()' method to get the unquoted version. For example::
  
        <!--#var "FAQ_Document_stx.read_raw()" fmt="structured-text"-->