docutils-develop Mailing List for Docutils: Documentation Utilities (Page 419)

On Fri, 2002-08-16 at 13:04, David Goodger wrote:
> Thanks for your comments.  How about sharing them with docutils-develop?

Oops!  I meant to do that, but forgot that this list doesn't reply to
list by default.  Here's my earlier response:

> > 1. Is a directive the right way to go for this?
> 
> I think so.  The only other way would be to construct a custom front
> end which knows how to join the subdocuments together, but that's a
> lot of work for the simple case.

OK, cool.

> > 2. Any comments on the following syntax?
> > 
> > .. include:: path/subdocument.rst
> >    :parse: true | false (default: true)
> 
> Looks fine.  What does the "parse" attribute mean?

parse = true
  Treat the included text as reST and parse as part of the document

parse = false
  Treat the included text as literal text (maybe it's already HTML or
whatever) and just insert it.

> Here's my thinking to date, from the to-do list
> (http://docutils.sf.net/spec/notes.html#misc-include):
> 
>     _`misc.include`: ``#include`` one file in another.  But how to
>     parse wrt sections, reference names, conflicts?  Parse it in the
>     current document's context (C-preprocessor semantics), or
>     separately and then merge?

Treat it all as one document unless notified otherwise?  I think that's
reasonable default behaviour.  There could be another flag on the
include directive, as there is in the recursive parse within reST I
believe, telling it whether to process the included text within the same
context or not, but I think the default should be to assume the same
context.

So now the directive would look like:

.. include:: path/subdocument.rst
   :parse: true | false (default: true)
   :same-context: true | false (default: true)


>     Use C-preprocessor semantics for locating include files?  E.g.,
>     ``.. include:: file.txt`` will read another file into the current
>     one, relative to the current file's directory, and ``.. include::
>     <standard>`` will read a standard include file from
>     ``docutils/include/``.  (Should "quotes" be required around
>     non-standard include files?)

Umm.  I don't see a lot of value in using "standard" include locations. 
URI are better: Include off the net, include from a file, include from a
relative path...

--Dethe

Hi,

Richard Jones:
> On Fri, 16 Aug 2002 2:34 am, Dethe Elza wrote:
> > This is great!  I've been half-heartedly working on an External Method
> > so I could use reST through Zope, but this is much better.
> 
> External Methods yecch :)
> 
> 
> > My only issue now is that I use Zope Local File System extensively, for
> > keeping my documentation under CVS.  I tried a naive mapping of ZReST to
> > *.rst files, but that didn't work.  Any ideas how these can be made to
> > work together?
> 
> Sorry, I know nothing about the Local File System stuff.

First of all let me thank you all for the great work.

I believe this is only one of the many places, where **StructuredText**
has been used in Zope.  Another important place is the DTML format
attribute of DTML variables.  For example (looked up from Zope 2.5.1)
there is the module ``lib/python/DocumentTemplate/DT_vars.py``, which 
implements the DTML language construct::

	<dtml-var foobar fmt="structured-text">

This is done using the format dispatcher dictionary ``special_formats``,
which contains a reference to the following small function::

   def structured_text(v, name='(Unknown name)', md={}):
       global StructuredText
       if StructuredText is None: 
	   from StructuredText.StructuredText import HTML

       if isinstance(v,StringType): txt = v

       elif aq_base(v).meta_type in ['DTML Document','DTML Method']:
	   txt = aq_base(v).read_raw()

       else: txt = str(v)
	   
       return HTML(txt,level=3,header=0)

My idea is to add a new entry called ``restructured-text`` or 
simply ``rest`` to this dispatcher dictionary.  Yesterday I played
around with **CMFWiki** and had a very similar situation.  There is
a simple wrapper function using the same class HTML.  So for further
integration of ReST as an alternative replacement for `StructuredText`
I believe it makes sense to come up with a wrapper class, which
implements the API of the class HTML of StructuredText.

Questions
=========

* What to do with the parameters ``level`` and ``header`` within **ReST**?

* Where should we put this class?  
  Would be an extended **ZReST** Zope product the right place?

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

Aahz wrote:
> Dethe wants the opposite of what I want: I'm building a book out of
> multiple chapters, each chapter in a subdirectory.  While the output
> of each chapter should stay in its own subdirectory, I'll want to
> make cross-chapter references.  How should I do that?

Good question.  No concrete answers yet, but the idea has been examined
a bit.  More thinking to date:

From the to-do list (http://docutils.sf.net/spec/notes.html#general):

    Perhaps store a name-to-id mapping file?  This could be stored
    permanently, read by subsequent processing runs, and updated with
    new entries.  ("Persistent ID mapping"?)

http://docutils.sf.net/spec/notes.html#restructuredtext-parser:

    Support generic hyperlink references to targets in other
    documents?  Not in an HTML-centric way, though (it's trivial to
    say ``http://www.example.com/doc#name``, and useless in non-HTML
    contexts).  XLink/XPointer?  ``.. baseref::``?  See Doc-SIG
    2001-08-10.

Or perhaps URLs are general enough for our purposes?

Also see http://docutils.sf.net/spec/notes.html#reference-merging
(transform idea).

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Dethe Elza wrote:
> I'm interested in building reST documents out of smaller documents,
> so I'm looking at adding a directive for recursive inclusion.  I've
> got a couple of questions going in.
> 
> 1. Is a directive the right way to go for this?

I think so.  The only other way would be to construct a custom front
end which knows how to join the subdocuments together, but that's a
lot of work for the simple case.

> 2. Any comments on the following syntax?
> 
> .. include:: path/subdocument.rst
>    :parse: true | false (default: true)

Looks fine.  What does the "parse" attribute mean?

Here's my thinking to date, from the to-do list
(http://docutils.sf.net/spec/notes.html#misc-include):

    _`misc.include`: ``#include`` one file in another.  But how to
    parse wrt sections, reference names, conflicts?  Parse it in the
    current document's context (C-preprocessor semantics), or
    separately and then merge?

    Use C-preprocessor semantics for locating include files?  E.g.,
    ``.. include:: file.txt`` will read another file into the current
    one, relative to the current file's directory, and ``.. include::
    <standard>`` will read a standard include file from
    ``docutils/include/``.  (Should "quotes" be required around
    non-standard include files?)

Many questions to answer.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

I've fixed the reStructuredText parser's handling of enumerated list
items to deal with the following edge cases:

- This text is parsed as a section title::

      1. This is the heading of section 

- This text is parsed as an ordinary paragraph:

      A. Einstein was a really
      smart dude.

  However, ambiguity cannot be avoided if the paragraph consists of
  only one line.  This text is parsed as an enumerated list item::
  
      A. Einstein was a really smart dude.
  
  If a single-line paragraph begins with text identical to an
  enumerator ("A.", "1.", "(b)", "I)", etc.), the first character will
  have to be escaped in order to have the line parsed as an ordinary
  paragraph::
  
      \A. Einstein was a really smart dude.

The code, spec, and test suite have been updated.  The code change
consists of checking the second line of each enumerated list item for
validity, in the parser's new ``Body.is_enumerated_list_item`` method.
Thanks to Jeremy Hylton and Dmitry Jemerov for their bug reports.

In addition, I implemented the "line-block" and "parsed-literal"
directives.  See http://docutils.sf.net/tools/test.html#line-blocks
for an example of the former; docs in
http://docutils.sf.net/spec/rst/directives.html.

The latest snapshot can always be downloaded from:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Fri, 16 Aug 2002 2:34 am, Dethe Elza wrote:
> This is great!  I've been half-heartedly working on an External Method
> so I could use reST through Zope, but this is much better.

External Methods yecch :)


> My only issue now is that I use Zope Local File System extensively, for
> keeping my documentation under CVS.  I tried a naive mapping of ZReST to
> *.rst files, but that didn't work.  Any ideas how these can be made to
> work together?

Sorry, I know nothing about the Local File System stuff.


    Richard

Dethe wants the opposite of what I want: I'm building a book out of
multiple chapters, each chapter in a subdirectory.  While the output of
each chapter should stay in its own subdirectory, I'll want to make
cross-chapter references.  How should I do that?
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Hi All,

I'm interested in building reST documents out of smaller documents, so
I'm looking at adding a directive for recursive inclusion.  I've got a
couple of questions going in.

1. Is a directive the right way to go for this?

2. Any comments on the following syntax?

.. include:: path/subdocument.rst
   :parse: true | false (default: true)

--Dethe

Richard,

This is great!  I've been half-heartedly working on an External Method
so I could use reST through Zope, but this is much better.

My only issue now is that I use Zope Local File System extensively, for
keeping my documentation under CVS.  I tried a naive mapping of ZReST to
*.rst files, but that didn't work.  Any ideas how these can be made to
work together?

--Dethe

On Thu, 15 Aug 2002 7:06 pm, Peter Funk wrote:
> To aid this I would find it very useful, if either the ZReST package or
> docutils could export a wrapper function implementing a very simple API
> similar to this found in Zope/StructuredText/StructuredText:
> 	def html_with_references(text, level=1, header=1)
> 	    """
> 	    Given a string 'text' containing structured text markup
> 	    returns this 'text' rendered as HTML
> 	    """

ReStructuredText takes some time to convert source text into HTML (sometimes 
several seconds for longish documents). I'd advise going for a more 
integrated approach that can compile the source text once.

If you're really keen to actually go with the html_with_references path - 
borrow the code from the ZReST.render() method and you'll have your text to 
HTML conversion.


   Richard

Hi,

Richard Jones wrote:
> I've thrown together a Zope interface to the docutils project's 
> ReStructuredText format. 
[...]

Exciting!  I couldn't refuse the temptation to try this out at once.
And it works:  The add menu of the ZMI displays the new object type
'ReStructuredText Document' and the HTML rendering happens as
expected.

> You'll need to install docutils too :)

Obviously.  I've downloaded a docutils-snapshot.tgz on August 13th.
On my RPM-based Linux system the default Python is 2.2, but Zope 2.5.1 
still recommends Python 2.1.  So I did
	python2.1 setup.py install	
in the directory, where I untarred docutils-snapshot.tgz, which created and
populated the directory /usr/lib/python2.1/site-packages/docutils.  
Works like a charme.

What I would like to do next is integrating ReST with CMFWiki.
This is a wiki clone product for Zope used within the context of
the Zope CMF, the Zope content management framework.  This Product
contains a module called 'CMFWikiPage.py', which currently calls the
html_with_references() function exported by the Zope StructuredText module
to render classic structured text.

The string returned from this function is than further processed to
setup the interwiki links and such.

I will try to come up with a patch to CMFWikiPage which will than use ReST 
as an alternative format (and as the default for new Wiki pages).

To aid this I would find it very useful, if either the ZReST package or
docutils could export a wrapper function implementing a very simple API
similar to this found in Zope/StructuredText/StructuredText:
	def html_with_references(text, level=1, header=1)
	    """
	    Given a string 'text' containing structured text markup 
	    returns this 'text' rendered as HTML
	    """

If such a simple API or something similar is already present either in
ZReST or in the docutils package itself, please apologize my ignorance
and give me a hint where to look for this.

Regards and many thanks, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

On Wed, 14 Aug 2002 20:18:17 -0400 David Goodger
<go...@us...> wrote:

[...]
> > Actually, I just figured out a way to make it work anyway so you can
> > ignore that mail. It's getting a little to late, it seems... :)
> 
> So, how did you do it?  Please do tell!

Uhm, I simply specified where the stylesheet would be in the destination
directory with --stylesheet=../build/aros.css which ofcourse resolved
everything. :)

---
Adam Chodorowski <ad...@ch...>

The way I understand it, the Russians are sort of a combination of evil and
incompetence... sort of like the Post Office with tanks.
    -- Emo Philips

I've thrown together a Zope interface to the docutils project's 
ReStructuredText format. It offers:

- through-the-web editing
- handling of errors (with control over the reporting level)
- FTP editing (with access to the config properties and errors)
- extraction of the document title from the text itself
- configuration of the stylesheet used
- source view

It's in the docutils sandbox CVS:

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/richard/ZReST/

You'll need to install docutils too :)


    Richard

On Thu, 15 Aug 2002 11:37 am, David Goodger wrote:
> Richard Jones wrote:
> > One of the big issues is that I'm not sure what all the options are :)
>
> Have you read http://docutils.sf.net/docs/tools.html yet?  It's up to date.

It has the stuff I need, thanks.


> >>> There's probably some way of faking an options object, but I just
> >>> couldn't get it to fly...
> >>
> >> Why fake it?  Isn't it easy to get a real one?
> >
> > I couldn't find a mechanism to do so - I poked around the code and docs
> > for quite some time, but nothing was immediately obvious.
>
> You seem to have found it though.  ``docutils.core.Publisher.set_options``
> returns an options object with default values.

Yeah, that was the result of my poking around :)


> >>> The Reporter stuff seemed far too hard-coded for my brain to cope
> >>> with at present :)
> >>
> >> Are you trying to capture the stderr output of Reporter, or the
> >> <system_message> elements it produces?  Why?
> >
> > I'd want to get the actual message elements, so I can display them
> > sensibly as I described above.
>
> The <system_message> elements are inserted into the document tree, adjacent
> to the problems themselves where possible.  Some (those generated
> post-parse) are kept until later, in ``document.messages``, and added as a
> special final section, "Docutils System Messages".
>
> Would you want these messages *not* to be in the document?  Or would a list
> of references be enough?  Docutils could be made to generate hyperlinks to
> all known system_messages and add them to the document.

I'd rather that the messages be both in the document, and available to the 
edit page. There's a screen cap of the edit page in my sandbox, just so you 
know what I'm on about :) The reporter's messages would be displayed above
the edit box, with the really serious stuff in red. When I get around to
implementing an FTP interface, the messages will be prepended to the
downloaded file with some marker, and stripped out on upload.

Screenshot: http://docutils.sf.net/sandbox/richard/ZReST/snapshot4.png


   Richard

Richard Jones wrote:
> One of the big issues is that I'm not sure what all the options are :)

Have you read http://docutils.sf.net/docs/tools.html yet?  It's up to date.

> Stylesheet location and Reporter verbosity are two biggies at the moment.

``options.stylesheet``, ``options.report_level``, and
``options.halt_level``.

> I'd want to capture the Reporter output to display on the Zope edit page,
> rather than it just going to stdout/err ;)

It would be easy to capture the stderr stream::

    sys.stderr = my_stream_object

Reading ahead though, I guess that's not what you're after.

>>> There's probably some way of faking an options object, but I just
>>> couldn't get it to fly...
>> 
>> Why fake it?  Isn't it easy to get a real one?
> 
> I couldn't find a mechanism to do so - I poked around the code and docs for
> quite some time, but nothing was immediately obvious.

You seem to have found it though.  ``docutils.core.Publisher.set_options``
returns an options object with default values.

> The docs don't seem to have much at all regarding the "API".

True.  It's on the list.  But I think most Docutils API docs will remain in
the docstrings for the time being.  The API itself is not mature enough to
fix the API in external docs yet.

It will help once PySource or equivalent is complete and part of Docutils
proper; API docs will be auto-generated from docstrings, mostly.  That is my
intended focus over the next few weeks.

>>> The Reporter stuff seemed far too hard-coded for my brain to cope
>>> with at present :)
>> 
>> Are you trying to capture the stderr output of Reporter, or the
>> <system_message> elements it produces?  Why?
> 
> I'd want to get the actual message elements, so I can display them sensibly as
> I described above.

The <system_message> elements are inserted into the document tree, adjacent
to the problems themselves where possible.  Some (those generated
post-parse) are kept until later, in ``document.messages``, and added as a
special final section, "Docutils System Messages".

Would you want these messages *not* to be in the document?  Or would a list
of references be enough?  Docutils could be made to generate hyperlinks to
all known system_messages and add them to the document.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Thu, 15 Aug 2002 10:54 am, David Goodger wrote:
> Re http://docutils.sf.net/sandbox/richard/ZReST/, Richard Jones wrote:
> > Anyway, it works, mostly. It doesn't:
> >
> > 1. have any control over options
> > 2. have any capturing of Reporter output
> >
> > .. because I spent the better part of an hour trying to figure how I
> > could sanely control both, and gave up ;)
>
> Can you give us specifics, of what you want to do?  Control options
> how?  Capture Reporter output how?

One of the big issues is that I'm not sure what all the options are :)

Stylesheet location and Reporter verbosity are two biggies at the moment. I'd 
want to capture the Reporter output to display on the Zope edit page, rather 
than it just going to stdout/err ;)


> > There's probably some way of faking an options object, but I just
> > couldn't get it to fly...
>
> Why fake it?  Isn't it easy to get a real one?

I couldn't find a mechanism to do so - I poked around the code and docs for 
quite some time, but nothing was immediately obvious. The docs don't seem to 
have much at all regarding the "API".


> > The Reporter stuff seemed far too hard-coded for my brain to cope
> > with at present :)
>
> Are you trying to capture the stderr output of Reporter, or the
> <system_message> elements it produces?  Why?

I'd want to get the actual message elements, so I can display them sensibly as 
I described above.


> Some comments on ZReST.render::
> [snip]
> Instead of these, you can just use::
>
>     self.formatted = pub.publish()

I did that, initially, but then I unpacked it so I could try manipulating the 
options and reporting.

Another improvement that I've just thought of is to extract the title from the 
DOM and set it as the object's "title" attribute (which is used by Zope for 
various things).


> BTW, I like the name.  We all need more Z-rest.  (If you don't get it,
> you're probably American.  "Zee" indeed! ;-)

:)

I'm like, sooo not American :)


    Richard (aka Bruce)

Re http://docutils.sf.net/sandbox/richard/ZReST/, Richard Jones wrote:
> Anyway, it works, mostly. It doesn't:
> 
> 1. have any control over options
> 2. have any capturing of Reporter output
> 
> .. because I spent the better part of an hour trying to figure how I
> could sanely control both, and gave up ;)

Can you give us specifics, of what you want to do?  Control options
how?  Capture Reporter output how?

> There's probably some way of faking an options object, but I just
> couldn't get it to fly...

Why fake it?  Isn't it easy to get a real one?

> The Reporter stuff seemed far too hard-coded for my brain to cope
> with at present :)

Are you trying to capture the stderr output of Reporter, or the
<system_message> elements it produces?  Why?

Anyhow, I appreciate the effort.  You're exercising Docutils in a way
it hasn't been exercised before, which brings out deficiencies.  Like
when you try to use muscles you don't ordinarily use, they hurt the
next day.  I see some places where the code is biased towards files
and paths, which should be fixed.  It should be easier to say, "Here's
a reStructuredText string; give me HTML."

Some comments on ZReST.render::

    def render(self):
        ''' Render the source to HTML
        '''
        # format with strings
        pub = core.Publisher()
        pub.set_reader('standalone', None, 'restructuredtext')
        pub.set_writer('html')

        # go with the defaults
        pub.set_options()

        # this is needed, but doesn't seem to do anything
        pub.options._destination = ''

It's currently needed to calculate relative paths for the stylesheet
link.  But you shouldn't have to deal with it.  It's one of the
file-biased things I mentioned that needs fixing.

        # input
        pub.source = io.StringInput(pub.options)
        pub.source.source = self.source

        # output - not that it's needed
        pub.destination = io.StringOutput(pub.options)

If it's not needed, use ``io.NullOutput``.  You can access the data
from ``pub.writer.astext()`` (produces Unicode).  But further down, I
see that you *do* need the ``StringOutput`` object; it does the output
encoding (default UTF-8).

        # parse!
        document = pub.reader.read(pub.source, pub.parser, pub.options)

        # do the format
        self.formatted = pub.writer.write(document, pub.destination)

Instead of these, you can just use::

    self.formatted = pub.publish()

BTW, I like the name.  We all need more Z-rest.  (If you don't get it,
you're probably American.  "Zee" indeed! ;-)

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Adam Chodorowski wrote:
> I'm experiencing some strange handling of the --stylesheet option of the HTML
> writer, which I use like the following::
> 
>    stylesheet=aros.css
> 
> But the generated HTML contains::
> 
>    <link rel="stylesheet" href="../../docs/aros.css" type="text/css" />
> 
> And that is not at all what I specified! It should be noted that the source
> file is in a different directory from the destination file, and that the
> current directory is the source one. I think this is the problem: for some
> reason the --stylesheet option is not taken verbatim, but is looked up
> relative to the current directory and "corrected".

Yes, this is intentional.  All references to files (stylesheet, source file
[in footer], PEP template) are interpreted relative to the current working
directory, and adjusted relative to the destination directory.  For
example::

    cd /work
    html.py -s --stylesheet=default.css /src/test.txt /dst/text.html

This will interpret the stylesheet as "work/default.css", so the stylesheet
link in the HTML (which is in the /dst dir) will read "../work/default.css",
and the source link (-s option) will read "../src/test.txt".

> This is totally useless for me, as I have separate build and source
> directories. If this is a intended feature (I do see the usefullness of it
> when building in a single directory), perhaps another option would be
> apropriate. Something like --absolute-stylesheet perhaps?

Understood.  Perhaps the current behavior should be optional
("--relative-paths" or something).  The default should probably be not to
process paths at all, just use them verbatim.  This will help with Richard's
troubles as well.

> Actually, I just figured out a way to make it work anyway so you can ignore
> that mail. It's getting a little to late, it seems... :)

So, how did you do it?  Please do tell!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Thu, 15 Aug 2002 00:21:13 +0200 Adam Chodorowski <ad...@ch...>
wrote:

[..]
> This is totally useless for me, as I have separate build and source
> directories. If this is a intended feature (I do see the usefullness of it
> when building in a single directory), perhaps another option would be
> apropriate. Something like --absolute-stylesheet perhaps?

Actually, I just figured out a way to make it work anyway so you can ignore
that mail. It's getting a little to late, it seems... :)

---
Adam Chodorowski <ad...@ch...>

Ludwig Boltzmann, who spent much of his life studying statistical mechanics, 
died in 1906, by his own hand. Paul Ehrenfest, carrying on the work, died 
similarly in 1933. Now it is our turn to study statistical mechanics.
    -- David L. Goodstein "States of Matter"

Hi.

I'm experiencing some strange handling of the --stylesheet option of the HTML
writer, which I use like the following::
	
	stylesheet=aros.css

But the generated HTML contains::

	<link rel="stylesheet" href="../../docs/aros.css" type="text/css" />

And that is not at all what I specified! It should be noted that the source
file is in a different directory from the destination file, and that the
current directory is the source one. I think this is the problem: for some
reason the --stylesheet option is not taken verbatim, but is looked up
relative to the current directory and "corrected". 

This is totally useless for me, as I have separate build and source
directories. If this is a intended feature (I do see the usefullness of it
when building in a single directory), perhaps another option would be
apropriate. Something like --absolute-stylesheet perhaps?

---
Adam Chodorowski <ad...@ch...>

If studies were interesting, the world would come to a halt and nothing 
would ever get done :) 
    -- James Kehl

On Wed, 14 Aug 2002 3:18 pm, Richard Jones wrote:
> On Tue, 13 Aug 2002 6:26 pm, Peter Funk wrote:
> > I would like to put docutils into my Zope.
> > Has anybody already done this?
> > Or can someone give me some hints and pointers, where to start?
>
> Sure, start with the stuff I just threw into the sandbox. Needed something
> to break the monotony of the day job ;)
>
> Anyway, it works, mostly. It doesn't:
>
> 1. have any control over options
> 2. have any capturing of Reporter output
>
> .. because I spent the better part of an hour trying to figure how I could
> sanely control both, and gave up ;)

Oh, if anyone wants to play with it:

1. I've already hooked in PropertyManager to prepare for the options, and
2. The "here" code at the top of the __init__.py will figure the product's
   installed directory, so you can find a config file. I don't believe it's
   necessary any more.

There's probably some way of faking an options object, but I just couldn't get 
it to fly...

The Reporter stuff seemed far too hard-coded for my brain to cope with at 
present :)  [I delved down into the readers code, and tried hacking together 
my own publisher, but I need to do some paying work :)]


    Richard

On Tue, 13 Aug 2002 6:26 pm, Peter Funk wrote:
> I would like to put docutils into my Zope.
> Has anybody already done this?
> Or can someone give me some hints and pointers, where to start?

Sure, start with the stuff I just threw into the sandbox. Needed something to 
break the monotony of the day job ;)

Anyway, it works, mostly. It doesn't:

1. have any control over options
2. have any capturing of Reporter output

.. because I spent the better part of an hour trying to figure how I could 
sanely control both, and gave up ;)


    Richard

Peter Funk wrote:
> I would like to put docutils into my Zope.
> Has anybody already done this?

Looks like nobody else has answered yet, so I'll give the obvious
answer: not that I know of.

> Or can someone give me some hints and pointers, where to start?

I'll be happy to help, but I know nothing about Zope.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Hi,

I would like to put docutils into my Zope.  
Has anybody already done this?
Or can someone give me some hints and pointers, where to start?

Especially I would like to use ReStructuredText together with CMF and CMFWiki.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

Aahz wrote:
> After a quick skim of images.py: So, in other words, in order to add a
> new directive, I'm going to have to understand how the state machine
> works?

I wouldn't go that far.  You'll need some knowledge of the inner workings,
yes; there's no free lunch.  The directive API is summarized in
docutils/parsers/rst/directives/__init__.py, except for details about the
return value, which I've just added:

    Directive functions return a tuple of two values:
    
    - a list of nodes which will be inserted into the document tree at
      the point where the directive was encountered (can be an empty
      list), and
    - a boolean, true iff the directive block finished on a blank line.

You'll need some services from the state machine, to get the line(s)
following the directive, usually an indented block, and to determine the
"blank_finish" state.  The "image" directive does everything you'd need
yours to do, I think, so it should be possible to hack something up.

To use the directive, it has to be registered in the directives/__init__.py
module.  You'll also need a new node class to instantiate, perhaps
"index_target" or "index_term".  Node classes usually live in
docutils/nodes.py, but directives can make their own if they're specialized;
see directives/html.py, class "meta" (inside class "MetaBody").

> Note that currently I don't care about reST generating the actual index;
> I'm only interested in emitting index tags for OpenOffice.

Understood.  I was just giving an example to illustrate semantics.

> (Yes, I'm ignoring your questions about requirements for now; I'm more
> interested in hacking up something which gives minimal results.)

If you get stuck, let us know what you need, and you may get some help.
Until then, happy hacking!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/