[Structuredtext-develop] Re: wanting to use restructuredtext in a zope product

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

>>>>> DG == "David Goodger" <go...@us...> wrote:

    tav> i ran into restructuredtext a few weeks back, and finding it to be
    tav> way cooler than the zope stx, decided to use it as the main render
    tav> format in the xnet product that i have been hacking.

    DG> Sounds good, but I don't understand "render format".  You don't
    DG> mean you *output* reStructuredText, do you?

my apologies. let me explain.

an xt_object renders itself according to the formats specified in the
xt_render_types list. and i'd like to have 'restx_to_html' (restructuredtext
to html) be the default render type. so, content would be stored as
restructuredtext and be output as html...

    DG> I looked at your CVS but I don't see an overview of what you're
    DG> doing.  Is there one?

ah, there is no overview document ;p

however the xt_object class, where a lot of the action occurs, is fairly
well documented:

http://cvs.espnow.com/xnet/xnet/xt_object/xt_object.py?rev=HEAD&content-type
=text/vnd.viewcvs-markup

specifically, start out from __call__() and work down to render_apply()

    tav> i ran into two main problems in using it "out of the box":

    DG> It is all very experimental at this point, so usage anecdotes
    DG> are welcome, thanks.

glad to help, and thanks in turn for a wonderful product.

    tav> [snip : rant about xhtml compatability]
    tav> ... so i took your html.py writer and did a quick adaptation of it:

    tav>     http://cvs.espnow.com/xnet/xnet/contrib/xhtml.py

    DG> I see that your app is only interested in the tags between
    DG> "<body>" and "</body>", exclusive.  That's a useful
    DG> distinction, when integrating with a wrapper system.

yea, my personal needs are to simply convert content from one format to
another... the presentation is handled by fancy zope page templates.

    DG> XHTML is on my list of things to investigate.  I may modify
    DG> the HTML writer to output XHTML as you have done.

that'd be great, and if self.output could be controlled by a variable as to
whether it included the headers/footers, that'd be even better.

    tav> the second problem was with how you "output". the way
    tav> the publish() system was setup, one could only output to a
    tav> file or stdout.

    DG> The publish function (Publisher class) is a facade, a flat
    DG> front-end to the components of the system, meant to provide
    DG> enough functionality for 80% of clients.  I'm only adding
    DG> functionality to the system as it is required, and yours is the
    DG> first case where a return value is required, instead of writing
    DG> to a file/stream.  It may be a case of a new type of
    DG> "distribution", which I've thought about but haven't
    DG> implemented yet.

a new type of distribution?

    DG> I would like to support such usage in a generic form, but I'm
    DG> not sure how yet.  Please send me your patched files, so I can
    DG> see exactly what you mean.

nothing spectacular. i simply added a couple of returns in core.py and in
writers/__init__.py and finally, in writers/xhtml.py.

here are the diffs:

---------------------------

--- /home/services/zope/misc/stx/dps/dps/core.py        Thu Feb  7 02:02:02
2002
+++ core.py     Fri Mar 22 05:45:09 2002
@@ -53,7 +53,8 @@

     def publish(self, source, destination):
         document = self.reader.read(source, self.parser)
-        self.writer.write(document, destination)
+        # tav : added a return
+        return self.writer.write(document, destination)


 def publish(source=None, destination=None,
@@ -70,4 +71,5 @@
         pub.setparser(parsername)
     if writer is None:
         pub.setwriter(writername)
-    pub.publish(source, destination)
+    # tav : added a return
+    return pub.publish(source, destination)

---------------------------

--- /home/services/zope/misc/stx/dps/dps/writers/__init__.py    Thu Mar  7
04:00:18 2002
+++ __init__.py Fri Mar 22 05:48:27 2002
@@ -18,6 +18,7 @@
 import sys
 from dps import languages
 from dps.transforms import universal
+from types import StringType # tav : see recordfile()


 class Writer:
@@ -53,7 +54,7 @@
         self.destination = destination
         self.transform()
         self.translate()
-        self.record()
+        return self.record() # tav : added a return

     def transform(self):
         """Run all of the transforms defined for this Writer."""
@@ -86,6 +87,9 @@
         if hasattr(self.destination, 'write'):
             destination.write(output)
         elif self.destination:
+            # tav : added a return output for text..
+            if type(self.destination) == StringType:
+                return output
             open(self.destination, 'w').write(output)
         else:
             sys.stdout.write(output)

    tav> i patched some of your functions and methods with
    tav> 'returns' so that the following would work:

    tav>
http://cvs.espnow.com/xnet/xnet/xt_object/render/restx_to_html.py

    DG> What does ``destination='here'`` mean?  Is "here" a
    DG> throwaway file, or is your patch treating the "here" value
    DG> specially?

as you can see above, when `destination` is a string, recordfile() returns
the output instead of writing it to a file or stdout.

    tav> and, now, i have ran into a third problem... i'd like to mix
    tav> html and rstx in my original text.

    DG> That's the purpose of the ".. raw::" directive, not yet
    DG> implemented. But this should be used only sparingly.  I do
    DG> not intend to allow HTML mixed into reStructuredText
    DG> without explicit marking.

aieee!

    DG> What are you trying to do?  Why mix in HTML?  Perhaps
    DG> there's a better way to do it.  Make up a minimal
    DG> example and I'll take a look.

well, there are numerous applications that i'd like to use xt_objects in...
from intranets to wikis to weblogs... and, i'd like to use restx as a
replacement for the rather incomplete and inconsistent stx in zope.

an example usecase would be in a blogging app, where the user might be
comfortable with basic html, e.g.:

------------

    I had a <b>few ideas</b> for new blogs:

    - The Bullshit Blog

     - A community moderated blog rating other blogs ...

    - The Bookmark Blog

     - A sidebar blog (similar to BoingBoing's <a href="foo.com">Guestbar
       blog</a>) ...

------------

in the above example, the user is aware of basic markup such as
<b>bold</bold> and <a>anchor</a> tags, but not much else, such as lists, etc
... which is where restx would come in very handy.

how does stx co-exist with html? can restx not adapt such a practise?

it strikes me that with the exception of the anchor tag, it is actually
pretty easy to get html and restx to co-exist. simply apply a reverse of the
encode() method on the returned output.

(i am sure there are other notable obstacles, but none come to mind right
now). however, the anchor tag is very problematic, as:

    <a href="http://cvs.espnow.com/xnet">xnet cvs</a>

would get parsed and converted to:

     <p><a href="<a
class="referencehref="http://cvs.espnow.com/xnet">http://cvs.espnow.com/xnet
</a>">xnet cvs</a></p>

not pretty.

could states.py be adapted to cater for such a situation?

    DG> BTW, please post to Doc-SIG or the project mailing
    DG> list in future.

doc-sig seems rather inappropriate, so am mailing the restructured-develop
list.

apologies to those on the list if this mail makes little sense. ;p

--
best regards, tav
ta...@es...



