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

[David G. <go...@us...>]

tav wrote:

[re the output of the HTML writer]
> if self.output could be controlled by a variable as to whether it
> included the headers/footers, that'd be even better.

I think I'll keep the document parts separate to some extent, within
the Writer object, but leave the access up to client subclasses.  In
other words, I'll provide the internals, but leave the interface up to
you (for now, at least).

The "Publisher" class (& "publish()" front-end) are facades, meant to
provide convenient access to typical functionality.  They are not
meant to provide arbitrary functionality.  If you want something
different, subclass components; you can pass instances of your
subclasses to "publish()".

> 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
> DG> the first case where a return value is required, instead of
> DG> writing 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?

"Distributors" are an abstraction I've been mulling over.  They're what
HappyDoc calls "docsets" (I think).  You can distribute the output in
multiple ways:

- As a single, monolithic file.
- As a hierarchy of files & directories.
- As a data structure (monolithic or hierarchical).
- Others.

Each of these types of output would be generated by a different
"Distributor" object.  I'm not yet sure if it will be useful (or
feasible) to keep distributors separate from writers.  I'm not
worrying about it for now; I still have plenty of research of related
projects (HappyDoc etc.) to do first, to see how the problem has been
attacked there.

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

I looked over them, and I think you can simplify life greatly if you
rethink your approach.  Instead of inserting "return" statements all
over the place, take advantage of the interface, which allows for
three types of "destination":

(a) a file-like object, which is written directly;
(b) a path to a file, which is opened and then written; or
(c) `None`, which implies `sys.stdout`.

You can get a return value by passing a file-like object as in (a).
A StringIO object would do the trick.

I may rethink the interface so you don't need StringIO, but not the
way you've outlined:

> --- /home/services/zope/misc/stx/dps/dps/writers/__init__.py
...
> @@ -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)
...
> as you can see above, when `destination` is a string, recordfile()
> returns the output instead of writing it to a file or stdout.

Implemented this way, I wouldn't be able write to a file by passing a
path (which is a string), which defeats the purpose of the interface
as written.

[example of mixed HTML & reSructuredText omitted]
> how does stx co-exist with html?

Classic StructuredText doesn't treat HTML specially, that I recall.
StructuredTextNG does; its rules_ specify:

    - SGML text is ignored and outputed as is.

.. _rules:
   http://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNGRules

There's a comment by Guido on that page:

    The rule that SGML (you mean HTML?) text is passed through
    unchanged is evil, because now we get all sorts of unpredictable
    interactions between ST and HTML.  Plus it's hard to quote
    examples of HTML markup, which occur very frequently when talking
    about Zope...

I concur wholeheartedly.

> can restx not adapt such a practise?

No!  Or at least, not by me!

I'd strongly advise against it, but I can't stop you from trying.

> 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.e
> spnow.com/xnet
> </a>">xnet cvs</a></p>
> 
> not pretty.

All kinds of special-casing would have to be done, and the result
would be a quagmire of ambiguity.  No thanks.

-- 
David Goodger    go...@us...    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net