[Zope3-dev] Status of reST

[Jeffrey P Shell]

On Sunday, April 13, 2003, at 11:57  AM, Stephan Richter wrote:

> On Friday 11 April 2003 19:44, Jeffrey P Shell wrote:
>> I don't think it's over-engineered.  It's still a work in progress,
>> much like Zope 3 is - with more obvious rules (I'm still spinning over
>> the differences between @@foo and @@/foo.  How long until $_?).
>>
>> But it is very flexible, powerful, and adaptable.  And, given its
>> internal complexity, it's a LOT easier to follow than Zope 3 currently
>> is.  :\.
>
> Well, I would hope so, since it id "just" a documentation tool.

Zope is "just" a way of making dynamic web sites.  But SSI is a lot 
less complicated ;).

> Actually, Zope 2 is where I got the current minimal code working. I 
> will look
> into that further...

And that's just based off of Richard Jones' work with ZReST.  The 
little piece that's not easily noticeable is the use of the custom 
'html4zope' writer, which is in the lib/python/docutils/writers 
directory and is completely custom to Zope.

I'm not convinced that the ZReST way is the best way of doing things, 
but it does allow for the custom Warnings object that can be used to 
report errors in a more Zopic way.  It's been a while since I've played 
with that code-path.  I was able to do things with far fewer lines of 
code when working with adding reST support to our Roundup instance.  
I'm going to see what code I can get working by this evening based on 
my experiences, with the intention that most uses of reST in Zope 3 on 
the client end are trivially easy to use.

>> However, there have been some significant improvements to docutils in
>> recent months that are probably not incorporated into the code in the
>> Zope branch, particularly in the "interpreted text roles" department.
>> Some of these improvements could be very advantageous to pick back up.
>
> What are "interpreted text roles"?

Interpreted Text and roles are a way of customizing the reST parser 
with explicit inline markup.  It's text that is "meant to be related, 
indexed, linked, summarized, or otherwise processed" [1].  It's a way 
of doing customized uses based on the environment.  For example, the 
Python Source reader in the works for reST uses interpreted text to 
mark references to methods, attributes, etc::

   Use :method:`Keeper.storedata` to ...

During processing, "Keeper.storedata" could be turned into a reference 
to documentation for the method 'storedata' on the class 'Keeper'.  I'm 
using it in our Roundup instance as a way of referring to various 
objects in the Roundup database - :roundup:`Issue 10`.  I envision that 
we could use it for help documentation for making easy references to 
other API documentation and/or to namespace documentation.  Since we're 
always going to be saying things like "See interface 
zope.app.interfaces.IFoo", we could, for example, use interpreted text 
to turn that into::

     See :interface:`zope.app.interfaces.IFoo`

And have that turn into a reference, or have it generate a floating box 
that pops up, or whatever else strikes our fancy (but I imagine a 
reference will be enough).  We could even make easy links back to the 
Zope 3 Wiki this way.

    For more information, read the original proposal in the wiki
    at :z3wiki:`OriginalProposal`.

I think it's the reST feature that we stand most to benefit from for 
building an online help system, since it's still *relatively* easy to 
read, and writing handlers for it is fairly easy.  One *could* make the 
Inliner system try to recognize certain words followed by something 
that looked like it belonged (ie ``See Wiki Page OriginalProposal``, 
``See interface .interfaces.IFoo``), but down that path lies angry 
crocodiles [2] - I know this from experience ;).

[1] 
http://docutils.sf.net/spec/rst/reStructuredText.html#interpreted-text
[2] Those only deserve to be hit with shoes