[Zope-dev] Making documentation easier

[Chuck Burdick (TT)]

I'm working on some documentation for ZFormulator, and I'm running into
various issues trying to cleanly present DTML examples.  The problem is that
it seems that Zope ALWAYS interprets dtml tags unless you use HTML entities
(like &lt; and &gt; instead of <, >) to surround your tags.  This happens in
<pre>...</pre> HTML tags or as example code in structured-text.

However, using HTML like this defeats much of the convenience of documenting
in structured-text.

Is there a way to stop Zope from interpreting the tags?  Alternatively, how
difficult would it be to create a <dtml-suppress>...</dtml-suppress> tag to
suppress tag interpretation?

Imagine the following as structured-text:

====BEGIN====

Example1 - Won't work because Zope interprets tags::

 <dtml-in myexample>
    <dtml-var title>
 </dtml-in>

Example2 - Hacked to make code appear as code:

 <pre>
 &lt;dtml-in myexample&gt;
    &lt;dtml-var title&gt;
 &lt;/dtml-in&gt;
 </pre>

====END====

Notice that example1 tries to use the example code symbology of
structured-text and that example2 "cheats" by embedding HTML into the
structured-text.


Thanks in advance for any suggestions,
Chuck Burdick
Web Administrator / Developer
Trading Technologies, Inc.

chuck.burdick@tradingtechnologies.com
(847) 424-8844