[Zope] - stx

[Paul Everitt]

Magnus wrote:
> I noticed on some page on the Zope site (I don't remember 
> which) that it
> included a Structured Text document with a fmt="stx" parameter to some
> DTML tag... AFAICS this is not a standard format... How do you do
> something like this? (I am very interested in having document methods
> written in other languages than HTML and then translated 
> automatically...)

First read the docstring in StructuredText.py which provides some good
starting documentation.  It isn't complete, but Amos is working on
documenting some more of the features (e.g. mailto and relative URLs,
footnotes, etc.)

For more examples of stuff written as StructuredText, take a look at the
module docstrings in a lot of the code.  Jim particularly writes his
stuff as StructuredText.  Also, for a *gargantuan* example, take a look
at Amos' all-singing, all-dancing Tutorial.txt file in the Product
sampler from yesterday.

Now, to actually use it...

From the command line:

  python StructuredText.py SomeFile.txt

will read SomeFile.txt and write HTML to stdout.  So:

  python StructuredText.py SomeFile.txt > SomeFile.html

creates an HTML file.  There is also a -t switch that changes the way
the HTML is structured:

  python StructuredText.py -t SomeFile.txt > SomeFile.html

There are other ways to use it, such as getting it to produce MML for
Frame rather than HTML.  To use it in Zope, create a Document, say
SomeDoc.txt and refer to it from the HTML version of the doc.  For
instance:

  <!--#var standard_html_header-->
  <!--#var SomeDoc.txt fmt="structured-text"-->
  <!--#var standard_html_footer-->

For those of you that want to know *why* you might like StructuredText,
here are my reasons:

  o Much, much easier to write than HTML

  o You can author something usable in an email, in a README file in a
distribution, or as HTML

  o Emacs text-mode makes working with it a breeeeze

I write just about everything as StructuredText these days.  There are
caveats though:

  o not surprisingly, we haven't done a good job of documenting it

  o it has some quirks that can make it misfire on the HTML

  o you sometimes finding yourself not wanting to live within its
confines

  o requires you to use the object database (no, just kidding :^)

So, chalk it up as another option at your disposal.  And no, Zope
doesn't require you to write in StructuredText, so don't go saying that
"I'm going back to Bobo cuz I don't wanna to use it." :^)

--Paul

Paul Everitt       Digital Creations
paul@digicool.com  540.371.6909