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

> As I think about it, I'm leaning toward new punctuation.  
> Where should I look for this?

Please, don't do the punctuation. Stick with the trailing ``_``. Trust
me on this one. :) 

Regards,
Garth. 

On Mon, 2002-10-28 at 21:40, David Goodger wrote:
> > To serve as an instructional sample I'm making a very simply Wiki --
> > I'd like to use reST as the markup, since it's not an example in
> > parsing (and I like the reST markup more than most Wiki markups to
> > boot).
> 
> Great!  Please share the results if you can.  I know that some
> intregration with MoinMoin has been done, although incomplete I
> believe.  See
> http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample

I will, though I'm not really making a full Wiki -- I just thought it
was a good example web application that's neat, yet potentially very
simple (especially when you don't make your own parser).

> Perhaps the tools/pep2html.py module is a better example, function
> "fix_rst_pep".  Docutils is called in one (logical) line of code::
> 
>     output = core.publish_string(
>         source=''.join(input_lines),
>         source_path=inpath,
>         destination_path=outfile.name,
>         reader_name='pep',
>         parser_name='restructuredtext',
>         writer_name='pep_html',
>         settings=docutils_settings)

Thanks, that's just what I wanted.

> > Also -- is there a good hook in reST that I can use for Wiki links?
> > The linking mechanism reST has is fine for internal and external
> > links, but doesn't fit right for Wiki links (which fall somewhere in
> > between).  If I could capture failed internal links and turn them
> > into inter-wiki-page links, that would be perfect.  Failing that, if
> > there was some way I could introduce another markup easily that
> > would be great.
> 
> There's mention of Wikis as an example potential Reader component in
> PEP 258 (http://docutils.sf.net/spec/pep-0258.html#readers).  A Wiki
> Reader could subclass the standard parser, or we could build in hooks
> if they prove general enough.  The PEP Reader
> (docutils/readers/pep.py) first subclassed the parser (still does,
> minimally: the "Inliner" class), but most of the code was moved into
> the parser proper for other client code to use.
> 
> I would suggest that Wiki links retain the trailing "_" of regular
> reStructuredText links, and a mechanism be added to do some kind of
> lookup from a Wiki target database.  The extra syntax (trailing "_")
> removes ambiguity inherent in CamelCase WikiLinks (such as anything
> written by Angus MacDuff).

That's definitely what I'd like to do -- I have never like WikiNames
anyway -- false positives and mangled case limit the medium, IMHO. 
There isn't any database of Wiki targets -- it's important that you be
able to make a link to a page that does not yet exist.  I think it would
be fine if Wiki links were made if no internal link could be found
(though with all the automatically-generated targets, there could be
some clashes).  Otherwise I'd need some other punctuation -- like `wiki
link`^ or somesuch.  There's a fair amount of seldom-used punctuation
that could be used.

In the case of Wiki links being a failback when no internal link was
found, it seems like the easiest way to handle it would be some sort of
error handler... maybe you already have something like this.  As to
adding new punctuation-based markup, I have no idea what interface would
make sense, except to somehow subclass the parser.  If the parser made
it easy to add certain styles of markup (either trailing punctuation, or
enclosing punctuation), then subclassing doesn't seem like a big burden.

As I think about it, I'm leaning toward new punctuation.  Where should I
look for this?

  Ian

These questions are more suitable for the docutils-develop list;
cross-posting.

Ian Bicking wrote:
> To serve as an instructional sample I'm making a very simply Wiki --
> I'd like to use reST as the markup, since it's not an example in
> parsing (and I like the reST markup more than most Wiki markups to
> boot).

Great!  Please share the results if you can.  I know that some
intregration with MoinMoin has been done, although incomplete I
believe.  See
http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample

> So, to do this I need to convert reST to HTML.  I looked around in
> buildhtml.py to get an idea, but I found it surprisingly difficult
> to figure out just what I would need to do.

buildhtml.py is a complicated beast, trying to be a kind of "make",
recursively building HTML for regular and PEP files with integrated
local config file support.  It's not a good example to begin with.

> Could someone perhaps tell me what the easiest way to do this is?

First, make sure you're using the latest code from CVS or from the
snapshot: <." rel="nofollow">http://docutils.sf.net/docutils-snapshot.tgz>.  Look in the
docutils/core.py file at the "publish_string" convenience function.
It is probably what you want.

Beyond the docstrings, there is no related developer documentation
yet.  Contributions are, of course, most welcome!

Perhaps the tools/pep2html.py module is a better example, function
"fix_rst_pep".  Docutils is called in one (logical) line of code::

    output = core.publish_string(
        source=''.join(input_lines),
        source_path=inpath,
        destination_path=outfile.name,
        reader_name='pep',
        parser_name='restructuredtext',
        writer_name='pep_html',
        settings=docutils_settings)

> I'm not sure of the relevance of the options, the importance of
> FileIO, or some of the other abstractions involved in this
> operation.

I've since renamed "options" to "settings": they're runtime
configuration settings (see
http://docutils.sf.net/docs/tools.html#configuration-file-entries).
For now, just use a convenience function with no explicit settings;
the defaults should be fine.
 
FileIO is an implementation detail; use strings with "publish_string"
or file-like objects with "publish_file".  Be sure to read the
docstrings.

> Also -- is there a good hook in reST that I can use for Wiki links?
> The linking mechanism reST has is fine for internal and external
> links, but doesn't fit right for Wiki links (which fall somewhere in
> between).  If I could capture failed internal links and turn them
> into inter-wiki-page links, that would be perfect.  Failing that, if
> there was some way I could introduce another markup easily that
> would be great.

There's mention of Wikis as an example potential Reader component in
PEP 258 (http://docutils.sf.net/spec/pep-0258.html#readers).  A Wiki
Reader could subclass the standard parser, or we could build in hooks
if they prove general enough.  The PEP Reader
(docutils/readers/pep.py) first subclassed the parser (still does,
minimally: the "Inliner" class), but most of the code was moved into
the parser proper for other client code to use.

I would suggest that Wiki links retain the trailing "_" of regular
reStructuredText links, and a mechanism be added to do some kind of
lookup from a Wiki target database.  The extra syntax (trailing "_")
removes ambiguity inherent in CamelCase WikiLinks (such as anything
written by Angus MacDuff).

> If there isn't an easy way, I'll probably just look for WikiNames in
> the generated HTML, and do the substitution then.  I'll have to do
> some dynamic fixup anyway, to distinguish between existent Wiki
> pages and to-be-created links.

A proper integrated approach would be best IMO, and welcome.  Please
subscribe to docutils-develop
(http://lists.sf.net/lists/listinfo/docutils-develop) and discuss it
there.  I'll be happy to help.

-- 
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 Oct 24, 2002, at 17:55, David Goodger  was heard saying:

> Julien T. Letessier wrote:
> > Another application is (as far as I'm concerned) including
> > docutils-generated HTML into page templates (e.g. in a PHP
> > website). For now I'm manually extracting HTML bodies and including
> > them into my page templates (on solarpack.sf.net)
>
> So your preferred output is the same as .ht files, but without the RFC
> 822 headers?  Should it include <body> & </body> tags, or just their
> contents?  Any other requirements?

Well, ideally, yes: a plain HTML body, without header and without <body> tags.
But this could be made optionnal, hmm :)

Anyways, even with headers, my processing chain could easily become automatic:

reST source ----> .ht file
.ht file ----> HTML content
header + HTML content + footer ----> final HTML document
(for instance)

Cheers,
-- 
Julien T. Letessier                   aim: JLetessier
Post-graduate ENSIMAG Student         web: http://www.mezis.net
IMAG IVR Master Student               email: co...@me...
---------------------------------------------------------------
SourceForge projects:
Solarpack: Distributing free software for Solaris
Docutils:  Python documentation framework
DocbookX:  software suite for MacOS X Docbook XML processing
---------------------------------------------------------------

On Fri, 25 Oct 2002 8:13 am, David Goodger wrote:
> I think this effort (and I, personally!) could benefit greatly from a
> short README or quick-start guide, giving straightforward instructions
> how to set up HT2HTML and how to use the HT2HTML and Docutils tools to
> build a web page or site.  HT2HTML comes with a bunch of "generators";
> which one to use at first?  Or do we have to customize our own?  A
> quick-start guide answering these questions could also be fed back to
> the HT2HTML project.

I haven't looked into it, but apparently ht2html is flexible WRT the HTML it 
stuffs _around_ the page. I'd like to see a more CSS'ified apparoach than the 
default tables-and-color-attributes approach, for example :)



     Richard

----- Original Message ----- 
From: "David Goodger" <go...@us...>
To: "Oliver Rutherfurd" <ol...@ru...>
Cc: <doc...@li...>
Sent: Thursday, October 24, 2002 5:13 PM
Subject: Re: [Docutils-develop] Re: Writer for .ht (HTML Template?) files

> David Goodger wrote:
> I think this effort (and I, personally!) could benefit greatly from a
> short README or quick-start guide, giving straightforward instructions
> how to set up HT2HTML and how to use the HT2HTML and Docutils tools to
> build a web page or site.  HT2HTML comes with a bunch of "generators";
> which one to use at first?  Or do we have to customize our own?  A
> quick-start guide answering these questions could also be fed back to
> the HT2HTML project.
> 
> Could someone write one?

I've just started playing around with it this past week, so I'll try to put
a little something together over the next couple of days as I check it
out a little more. I'm going to be travelling, but I should have some time.

> David Goodger wrote:
> Having taken a look at the code, I noticed that the ``settings_spec``
> attribute is being partially duplicated.  With the addition of
> stylesheet handling, the duplication is complete (or close).  Perhaps
> it would be best to make the generation of .ht files (and
> body-contents-only files, as Julien proposed) part of the html4css1.py
> writer.  Something like "--form=ht" or "--partial-ht" (can't think of
> anything good today; brain's a bit fuzzy).  The "HTTranslator" class
> could live in the same module as "HTMLTranslator", and the option
> would trigger its use (the visitor/translator class is already
> parameterized in the "Writer" class).
> 
> Or should they be separate writers, but inherit most or all settings?
> See writers/pep_html.py for an example.

I duplicated all the settings because I didn't think the 'embed stylesheet'
option would work for the writer. From what I can see, if you want to
embed styles in your generated html, you must put it in the Python
generator class. This is one hangup that I see about making '.ht' output
an option for the html4.css1 writer. Maybe it's just me, but it might
start getting a little confusing if some options work or don't work depding
on the "form" of the output from the same writer -- though maybe I'm 
making a bigger deal about that than it really is.

How would people suggest dealing with these types of differences?

-Ollie
ol...@ru...

Aahz wrote:
> On Thu, Oct 24, 2002, David Goodger wrote:
>> 
>> Don't know where scripts get installed on MacOS X, but since it's
>> FreeBSD-based, it's probably the same as GNU/Linux.
> 
> Nitpick: no, it isn't.  Yes, there's BSD-ish roots in there, but overall
> the code is a lineal descendent of MACH/NextStep.

I can pick nits too.  From Apple's Darwin page
(http://developer.apple.com/darwin/):

    Beneath the appealing, easy-to-use interface of Mac OS X is a
    rock-solid foundation ... This foundation is a core operating
    system commonly known as Darwin. Darwin integrates a number of
    technologies, most importantly Mach 3.0, operating-system
    services based on 4.4BSD ...

To put it bluntly: whatever.

-- 
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, Oct 24, 2002, David Goodger wrote:
>
>   Don't know where scripts get installed on MacOS X, but since it's
>   FreeBSD-based, it's probably the same as GNU/Linux.

Nitpick: no, it isn't.  Yes, there's BSD-ish roots in there, but overall
the code is a lineal descendent of MACH/NextStep.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

I think this effort (and I, personally!) could benefit greatly from a
short README or quick-start guide, giving straightforward instructions
how to set up HT2HTML and how to use the HT2HTML and Docutils tools to
build a web page or site.  HT2HTML comes with a bunch of "generators";
which one to use at first?  Or do we have to customize our own?  A
quick-start guide answering these questions could also be fed back to
the HT2HTML project.

Could someone write one?

Oliver Rutherford wrote:
> As far as the bulletproof part goes, I might have sent a broken
> version :-(.  When I tried it this morning I got an error.

It happens.  No biggie.

> I've fixed the break and added stylesheet handling and will upload
> an updated version into the sandbox

Having taken a look at the code, I noticed that the ``settings_spec``
attribute is being partially duplicated.  With the addition of
stylesheet handling, the duplication is complete (or close).  Perhaps
it would be best to make the generation of .ht files (and
body-contents-only files, as Julien proposed) part of the html4css1.py
writer.  Something like "--form=ht" or "--partial-ht" (can't think of
anything good today; brain's a bit fuzzy).  The "HTTranslator" class
could live in the same module as "HTMLTranslator", and the option
would trigger its use (the visitor/translator class is already
parameterized in the "Writer" class).

Or should they be separate writers, but inherit most or all settings?
See writers/pep_html.py for an example.

>>> On an unrelated note, what do you think of adding the front end
>>> scripts in "tools" as scripts in docutils setup.py file?
>>
>> Good idea.  But how would that work?  Does Distutils put scripts on
>> the shell's path?  Is it cross-platform?  (Where does it put
>> scripts on my ancient Mac?)
> 
> Good question, so after suggesting it I'm embarrased to say that it
> might not.  I could have sworn that 'Scripts' was in my PATH, but I
> just checked and it's not.

That's not really *our* problem though.  We can ask users to add to
their PATH, and petition PythonLabs to fix their installer (if it's a
bug).  Any user competent enough to use the command line ought to be
able to set their PATH.  For those not competent to use the command
line, there's DocFactory, a Docutils GUI front end using wxPython
(http://docutils.sf.net/sandbox/gschwant/docfactory/README.html;
anybody interested, *please* help out with this -- could be great).

I experimented on different OSes:

* On Win2K, scripts are installed into the "Scripts" subdirectory of
  the Python install directory (``sys.prefix``).

* On GNU/Linux (I agree with RMS's views on naming :-), scripts are
  installed into the "bin" subdirectory of the installation prefix
  (``sys.prefix``), typically /usr/bin or /usr/local/bin.  These
  should be on every user's PATH.

* On MacOS 8.6 (my home machine; hardware contributions welcome! :-)
  it's the same as Windows: scripts are installed into the "Scripts"
  subdirectory of the Python install directory (``sys.prefix``).  On
  my machine, that subdirectory didn't exist -- Distutils created it.
  There is no PATH on MacOS (pre-X), only Python's ``sys.path``.  But
  there's also no command line, so any Docutils use would have to be
  programmatic or have a GUI.

  Don't know where scripts get installed on MacOS X, but since it's
  FreeBSD-based, it's probably the same as GNU/Linux.

Distutils (setup.py) has an option for the scripts install directory:
"--install-scripts".  See all the options with::

    python setup.py install --help

-- 
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/

Julien T. Letessier wrote:
> Another application is (as far as I'm concerned) including
> docutils-generated HTML into page templates (e.g. in a PHP
> website). For now I'm manually extracting HTML bodies and including
> them into my page templates (on solarpack.sf.net)

So your preferred output is the same as .ht files, but without the RFC
822 headers?  Should it include <body> & </body> tags, or just their
contents?  Any other requirements?

-- 
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/

----- Original Message -----
From: "David Goodger" <go...@us...>
To: "Oliver Rutherfurd" <ol...@ru...>
Cc: <doc...@li...>
Sent: Thursday, October 24, 2002 12:30 AM
Subject: [Docutils-develop] Re: Writer for .ht (HTML Template?) files

> Oliver Rutherfurd wrote:
> > I've written a Writer for .ht (HTML Template?) files used by ht2html_.
>
> Cool!  I've been thinking of doing something like that for a while.  One
> reason being that the Docutils home page is too long and boring, and could
> use some sprucing up.
>
> > As this is kind of a specialized writer, I didn't know whether you or
anyone
> > would have any interest in it for Docutils, so I figured I'd check and
see.
> > If you don't want it for Docutils proper, I can just plunk it into the
> > sandbox.
>
> I am definitely interested.

Ok, great.

> We'll have to think about where the best place should be (opinions?).
> If we can get the code really bulletproof (could be already; I haven't
> looked at it yet and may not get a chance for a couple of days), I don't
> see why it can't live in the docutils package.  I would love to see a slew
> of specialized writers in there, tempting users.

As far as the bulletproof part goes, I might have sent a broken version :-(.
When I tried it this morning I got an error.  I've fixed the break and added
stylesheet handling and will upload an updated version into the sandbox as
soon as my sf key lets me (just uploaded a key since I seem to need that
on windows).

> > On an unrelated note, what do you think of adding the front end scripts
in
> > "tools" as scripts in docutils setup.py file?
>
> Good idea.  But how would that work?  Does Distutils put scripts on the
> shell's path?  Is it cross-platform?  (Where does it put scripts on my
> ancient Mac?)

Good question, so after suggesting it I'm embarrased to say that it might
not.
I could have sworn that 'Scripts' was in my PATH, but I just checked and
it's
not. Maybe ActivePython's version does that, but Python.org's installer
doesn't?
I updated from ActivePython 2.2.1 to Python 2.2.2 and it's not in my PATH
now.

> > However, if they were installed by default, it might be more intuitive
if
> > they were named something like rest2html, rest2xml, etc...
>
> Perhaps, although I'd prefer "rst" to "rest".  Opinions?

"rst" sounds good.

-Ollie
ol...@ru...

On Oct 24, 2002, at 01:30, David Goodger  was heard saying:

> Oliver Rutherfurd wrote:

> Cool!  I've been thinking of doing something like that for a while.  One
> reason being that the Docutils home page is too long and boring, and could
> use some sprucing up.

Another application is (as far as I'm concerned) including docutils-generated
HTML into page templates (e.g. in a PHP website). For now I'm manually
extracting HTML bodies and including them into my page templates (on
solarpack.sf.net)

> Perhaps, although I'd prefer "rst" to "rest".  Opinions?

I vote 'rst' (I already use rst2latex :) )

Cheers,
-- 
Julien T. Letessier                   aim: JLetessier
Post-graduate ENSIMAG Student         web: http://www.mezis.net
IMAG IVR Master Student               email: co...@me...
---------------------------------------------------------------
SourceForge projects:
Solarpack: Distributing free software for Solaris
Docutils:  Python documentation framework
DocbookX:  software suite for MacOS X Docbook XML processing
---------------------------------------------------------------

Tools is good...

Oliver Rutherford wrote:
> > However, if they were installed by default, it might
> > be more intuitive if they were named something like
> > rest2html, rest2xml, etc...

David Goodger replied:
> Perhaps, although I'd prefer "rst" to "rest".  Opinions?

On the grounds that shorter prefixes are generally better than longer,
I'd vote for "rst" (anyway, if I type "rest" I actually want to
capitalise it as "reST", which makes no sense for command line tool
names...)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

Oliver Rutherfurd wrote:
> I've written a Writer for .ht (HTML Template?) files used by ht2html_.

Cool!  I've been thinking of doing something like that for a while.  One
reason being that the Docutils home page is too long and boring, and could
use some sprucing up.

> As this is kind of a specialized writer, I didn't know whether you or anyone
> would have any interest in it for Docutils, so I figured I'd check and see.
> If you don't want it for Docutils proper, I can just plunk it into the
> sandbox.

I am definitely interested.  We'll have to think about where the best place
should be (opinions?).  If we can get the code really bulletproof (could be
already; I haven't looked at it yet and may not get a chance for a couple of
days), I don't see why it can't live in the docutils package.  I would love
to see a slew of specialized writers in there, tempting users.

> On an unrelated note, what do you think of adding the front end scripts in
> "tools" as scripts in docutils setup.py file?

Good idea.  But how would that work?  Does Distutils put scripts on the
shell's path?  Is it cross-platform?  (Where does it put scripts on my
ancient Mac?)

> However, if they were installed by default, it might be more intuitive if
> they were named something like rest2html, rest2xml, etc...

Perhaps, although I'd prefer "rst" to "rest".  Opinions?

> Lastly, I'm hoping the get the DocBook writer a little more polished before
> long.

More good news!  I'll sleep well tonight.  And with that: good night.

-- 
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 David,

I've written a Writer for .ht (HTML Template?) files used by ht2html_.

.. _ht2html: http://ht2html.sourceforge.net/

Basically it writes the body of an HTML page with some optional RFC-2822
headers at the top. The writer, as you can see, is a very thin wrapper of
html4css1.

As this is kind of a specialized writer, I didn't know whether you or anyone
would have any interest in it for Docutils, so I figured I'd check and see.
If you don't want it for Docutils proper, I can just plunk it into the
sandbox.

On an unrelated note, what do you think of adding the front end scripts in
"tools" as scripts in docutils setup.py file?  That way when someone
installed docutils they had scripts to do conversions ready to go. However,
if they were installed by default, it might be more intuitive if they were
named something like rest2html, rest2xml, etc... I've done that with the
attached front end script, so I didn't have 2 files with the same name
attached.

Lastly, I'm hoping the get the DocBook writer a little more polished before
long. I got caught up with a move, new job, etc... and haven't gotten around
to getting the last few bits going and remaining kinks worked out.

Regards,
-Ollie

Ollie Rutherfurd
ol...@ru...

I just checked in a major change to the Docutils tranform handling
mechanism.  There's a new component, called "Transformer", which
centralizes and simplifies the transform handling that used to be
distributed between Reader and Writer objects.  I brought PEP 258 up
to date with this change and other recent changes.  Transformer
details can be found here:

    http://docutils.sf.net/spec/pep-0258.html#transformer
    http://docutils.sf.net/spec/transforms.html

The change simplifies the project model considerably::

                     +---------------------------+
                     |        Docutils:          |
                     | docutils.core.Publisher,  |
                     | docutils.core.publish_*() |
                     +---------------------------+
                      /            |            \
                     /             |             \
            1,3,5   /        6     |              \ 7
           +--------+       +-------------+       +--------+
           | READER | ----> | TRANSFORMER | ====> | WRITER |
           +--------+       +-------------+       +--------+
            /     \\                                  |
           /       \\                                 |
     2    /      4  \\                             8  |
    +-------+   +--------+                        +--------+
    | INPUT |   | PARSER |                        | OUTPUT |
    +-------+   +--------+                        +--------+

This change is internal and shouldn't have an impact on front ends or
client code.  If it breaks any code, please let me know.

The latest snapshot is always available 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/

<html>
<head>
</head>
<body>
<p align="center"><font style="font-size: 11pt" face="Courier">Did you miss out on NNCO, UP 233% IN JUST 2 DAYS?</font></p>
<p align="center"><font style="font-size: 11pt" face="Courier">If so, Here's another pick - Another Short Play</font></p>
<p align="center"><b><a href="CLICK" rel="nofollow">http://www.globalwebcollective.net/Wall_Street_Bulletin.htm">CLICK HERE</a></b></p>
<p align="center"><img border="0" src="
" rel="nofollow">http://www.globalwebcollective.net/Short%20Play.jpg"></p>
<p align="left">&nbsp;</p>
<p align="left">&nbsp;</p>
<p align="center"><font size="2">I no longer wish to receive your newsletter <a href="mailto:not...@th...?subject=takeoff"><b>click here</b></a></font></p>
</body>
</html>

pebhbbitdcsbwkdwupypicsrswbycuwyia

On 22 October 2002, David Goodger said:
> The sources on the web site still say "Docutils 0.2.4".  The current
> version is 0.2.7.  Not pushed out yet?

Correct -- I'm just playing on my development web server.

> You can set the <tt> style back to its initial value::
> 
>     tt { background-color: transparent }

Yup, that works.

> In fact, I think I'll remove the "a.target" style from the project's
> default.css.  It was useful for diagnostics, but implies meaning where
> there really is none.  And it's distracting.  ... Gone now.

OK, I'll cvs up and stop worrying about the "a" styles then.

Thanks!

        Greg        
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org

[David]
>> I don't think you should transform the tree at this point, since
>> you're traversing the tree.  It's like modifying a list while looping
>> over it: dangerous.

[Aahz]
> Yup.  This would be a separate transform step, just like
> ``docutils.transforms.references.Footnotes``.  Do you still think
> calling a nested walkabout is better?

If a writer-specific transform seems more natural, then that would be OK
too.  Except that the transform should not violate the doctree structure as
expressed in spec/docutils.dtd.  In other words: no footnotes inside
paragraphs.  The writer has to receive a standard doctree, and the other
transforms (that are not writer-specific) depend on the doctree being
standard.  Having said that, if the writer were to apply its own transforms
just before the final "translation" (which is merely an extreme transform),
then no problem, anything goes.  The doctree belongs to the writer at that
point.

In fact, the entire Writer framework could be changed.  The Visitor pattern
and Translator classes were just the way that worked for me with the HTML
writer.  I make no claims that it's an ideal solution.

I'm almost finished ripping the guts out of the old transform system and
replacing it with something better.  The code is almost stable, and I'll
probably be checking it in by the weekend.

> PS: Regarding your comments on the coding style, I need to repeat that
> despite my publishing the code for the convenience of everyone on this
> project, this is very definitely hack code thrown together -- I keep
> trying things and editing the code, and I've been doing little cleanup
> when I discover something that works.  So there are often non-ideal
> artifacts of earlier code.

Understood; that's why it's in the sandbox.  I didn't realize I *was*
commenting on the coding *style*, actually.  Just commenting on and asking
questions about the logic, in a sincere attempt to understand the code and
assist you in reaching your goal.  No need to take any of it personally.  I
hope and trust you're interested in *improving* the code?

> Side note: eventually OOwriter will split into two classes, because I've
> got stuff in there (like the ``include-output`` directive) specific to
> my book that belongs in a subclass rather than the main OpenOffice.org
> writer.

Not sure exactly what you mean here.  If you mean that the "include-output"
directive should be independent of the writer, I agree completely.  If it's
general-purpose, it should become a part of the parser.

-- 
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'll get back to the rest later, but I wanted to make a quick comment.

On Tue, Oct 22, 2002, David Goodger wrote:
> [Aahz]
>>
>> Well, I suppose what I *really* ought to do is transform the doctree
>> to replace the footnote_reference with the actual footnote node.
>> Then everything would work magically (modulo the issue of the
>> <text:footnote-body> tag).
> 
> I don't think you should transform the tree at this point, since
> you're traversing the tree.  It's like modifying a list while looping
> over it: dangerous.  

Yup.  This would be a separate transform step, just like
``docutils.transforms.references.Footnotes``.  Do you still think
calling a nested walkabout is better?

PS: Regarding your comments on the coding style, I need to repeat that
despite my publishing the code for the convenience of everyone on this
project, this is very definitely hack code thrown together -- I keep
trying things and editing the code, and I've been doing little cleanup
when I discover something that works.  So there are often non-ideal
artifacts of earlier code.

I do appreciate the additional info about how reST works.

Side note: eventually OOwriter will split into two classes, because I've
got stuff in there (like the ``include-output`` directive) specific to
my book that belongs in a subclass rather than the main OpenOffice.org
writer.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

gr...@us... wrote:
> you are talking from the internal represantation i am talking of the
> output structure.

We started out talking about internationalization, doing lookups in
language modules.  That smells like internal representation to me.

The point is, when you have a document which begins with this::

    :Author: John Doe
    :Web Site: http://www.example.com/

The internal document (fragment) tree looks like this::

    <docinfo>
        <author>
            John Doe
        <field>
            <field_name>
                Web Site
            <field_body>
                <paragraph>
                    <reference refuri="" rel="nofollow">http://www.example.com/">
                        http://www.example.com/

The structures for the "Author" field (specific) and the "Web Site"
field (generic) are completely different, and therefore require
different processing.  You can't ignore that.

> "Web site" and "Author" both end up in the documents docinfo.
> this means: if i donot want to put formatting information
> into two places one needs a function for it.

Fine, separate the formatting into a separate method.  Just don't do
language lookups for fields that don't need them.  Do the language
lookup, and send the *result* to the formatting method.

>>> the pre (literal) environment in latex is verbatim.  how does one
>>> get the input with parsing: astext() removes the reST markup ?
>>
>> I don't understand the question.  Examples, please.
> 
> ::
>    This is *some* thing
> 
> this.astext() gives the text without stars.

Untrue.  Perhaps the lack of a blank line after "::" is causing
trouble?  Literal blocks do not touch the characters inside::

    $ quicktest.py << EOF
    > ::
    > 
    >     This is *some* thing
    > EOF
    <document source="<stdin>">
        <literal_block xml:space="preserve">
            This is *some* thing

The astext() method doesn't touch the characters either.  However,
astext() should only be used sparingly and carefully.  If there is any
structure in the node, ``node.astext()`` will ignore it.

Why are you using astext() anyway?  Just let the tree traversal do the
work.  From latex2e.py's LaTeXTranslator class::

    def visit_literal_block(self, node):
        self.use_verbatim_for_literal = 1
        if (self.use_verbatim_for_literal):
            self.body.append('\\begin{verbatim}\n')
            self.body.append(node.astext())
            self.body.append('\n\\end{verbatim}\n')
            raise nodes.SkipNode
        else:
            self.body.append('{\\obeylines\\obeyspaces\\ttfamily\n')

I don't see why you need to short-circuit the traversal.  The "if"
statement is not really conditional: it will always evaluate to true.
That should be cleaned up.  Shouldn't
``self.body.append(node.astext())`` also call ``self.encode()``?  That
may be the source of the problem.

This is exactly the kind of bug that arises when the tree traversal
isn't allowed to complete properly.  Look at the html4css1.py writer;
``raise nodes.SkipNode`` is only used 5 times, and each time there is
a good reason.  I've added some comments where it may have been
unclear.  Could you add comments wherever you ``raise nodes.SkipNode``
in latex2e.py, justifying the exceptions?

-- 
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/

[David]
>> The docs look good.  Please note that if you regenerate the docs with
>> the latest Docutils (which I recommend you do, to take advantage of
>> the improvements to the HTML produced)

[Greg]
> OK, done.

The sources on the web site still say "Docutils 0.2.4".  The current
version is 0.2.7.  Not pushed out yet?

>> you should also replace the stylesheet. ... I recommend extracting
>> your modifications into a separate .css file and using the
>> "@import" statement to cascade the stylesheets.  See
>> http://docutils.sf.net/docs/tools.html#stylesheets for details.
> 
> OK, tried that.  Problem: the main modification I made was to
> completely *remove* your styles for the 'a' and 'tt' tags.  (I think
> link colouring should be up to the browser, and I don't like a
> background on inline literals.)
>
> So how do I override your stylesheet with removal information?

You can set the <tt> style back to its initial value::

    tt { background-color: transparent }

As for the <a> tags, these are the styles specified::

    a.target {
      color: blue }

    a.toc-backref {
      text-decoration: none ;
      color: black }

The first is easily undone::

    a.target {
      color: inherit }

In fact, I think I'll remove the "a.target" style from the project's
default.css.  It was useful for diagnostics, but implies meaning where
there really is none.  And it's distracting.  ... Gone now.

I don't know of any way to undo the second set of styles
("a.toc-backref").  But they're only applied to back-links from
section headers to a table of contents.  If you have no table of
contents, or specify "--no-toc-backlinks" (or "toc_backlinks: none" in
the config file), that style will have no effect.  These styles remove
the typical hyperlink formatting (color + underline), to make the
back-linked section headers look like regular section headers.  An
approximation to undoing the style would be::

    a.toc-backref {
      text-decoration: underline ;
      color: blue }

However, the browser itself or user settings may specify a different
initial color and/or decoration, and the color should change once the
hyperlink is visited.  These can also be specified (using the ":link"
and ":visited" pseudo-classes), but that just makes the whole thing
even more complicated.

Is there any way to *disable* styles that don't inherit?  Any way to
say "use or restore the *initial* value for this style, ignoring any
later explicit styles"?  I can't find any.

-- 
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/

Looking at your examples and the OpenOffice.org XML DTD and
specification docs [*]_, I see that OpenOffice XML requires footnotes
themselves to be embedded inside the paragraph at the point of
reference, as does DocBook and, I believe, TeX.  This makes sense for
processing (easier), but not for reading since the whole point of a
footnote is to remove the extra text from the main flow.

.. [*] Available from http://xml.openoffice.org/.  DTD files are at
   http://xml.openoffice.org/source/browse/xml/xmloff/dtd/ (text.mod
   has the most significance here) and the specification is
   http://xml.openoffice.org/xml-specification.pdf.

[Aahz]
>>> What I really ought to do is call for a walkabout on the footnote
>>> node, but I can't quite figure out how to do that.

[David]
>> I assume you're already *doing* a walkabout.  Just let it continue.
>> You're short-circuiting the process artificially.  The internal
>> document tree is well-formed: an end-tag (depart_tag) for every
>> start-tag (visit_tag), and all elements arranged as the DTD
>> describes.  (If they're not, it's a bug.)  Trust in the docree.

[Aahz]
> Well, I suppose what I *really* ought to do is transform the doctree
> to replace the footnote_reference with the actual footnote node.
> Then everything would work magically (modulo the issue of the
> <text:footnote-body> tag).

I don't think you should transform the tree at this point, since
you're traversing the tree.  It's like modifying a list while looping
over it: dangerous.  Having seen the context, I now think your first
idea was correct, to force a traversal of the footnote when you reach
the first footnote reference.  However, note that there may be
multiple references to the same footnote, so only the *first*
reference should have its footnote traversed; others should use the
<text:footnote-ref> element I believe.

In general, doing a traversal on a subtree is simple.  Say we want to
do a traversal starting at the "footnote" node::

    # Use our own class to get a clone of ourselves:
    visitor = self.__class__(self.document)
    # Traverse the subtree rooted at "footnote":
    footnote.walkabout(visitor)
    # Collect the results (assumes uniform treatment of output):
    self.body.extend(visitor.body)

But there's a tricky issue in the OpenOfficeTranslator class::

    def visit_footnote(self, node):
        raise nodes.SkipNode

This is fine for the outer traversal, but it clobbers the inner
traversal.  Perhaps change this to::

    def visit_footnote(self, node):
        if self.handle_footnotes:
            ... handle footnotes
        else:
            raise nodes.SkipNode

How to set ``self.handle_footnotes``?

* It could be a parameter to the __init__ method, but we'd still have
  to watch for nested footnotes (a footnote reference within a
  footnote body).

* Start out with ``self.handle_footnotes`` true, and set it false in
  ``visit_document``?  If nested traversals need to be done for any
  other elements, this could backfire.

* Check for an empty ``self.body``?  That might be the simplest and
  best way::

    def visit_footnote(self, node):
        if self.body:
            raise nodes.SkipNode
        else:
            ... handle footnotes

Update: the DTD says "text:footnote and text:endnote elements may not
contain other text:footnote or text:endnote elements".  Docutils
documents *can* have nested footnotes though, which complicates
matters.  Either a workaround has to be devised, or we place a
*documented* restriction on Docutils wrt the OpenOffice writer.  The
latter would be acceptable for now.

Let's take a look at the ``visit_footnote_reference`` method::

    def visit_footnote_reference(self, node):
        name = node['refid']

Why are you calling this the "name"?  I find it misleading, since
there are "name" attributes on many elements.  I'd use "refid" or
"footnote_id" instead.

Continuing::

        id = node['id']
        number = node['auto']
        for footnote in self.document.autofootnotes:
            if name == footnote['name']:
                break

The ``if name == footnote['name']:`` test relies on an accident and
may not always work.  IDs are derived from names, and simple names are
equal to their IDs, but more complicated names are not.  For example,
the name "a name" turns into the ID "a-name".  ID's can't have spaces
or anything apart from alphanumerics and "-" (see
docutils.nodes.make_id; 32 lines of docstring for a 3-line function!).

In any case, there's a much easier way to get the footnote node::

    footnote = self.document.ids[name]

(Although it shouldn't be "name" but "refid".)

Since a footnote should only be rendered once, you should check if
it's already happened here.  Something like::

    if hasattr(footnote, 'rendered'):
        self.body.append('<text:footnote-ref text:ref-name="%s"'
                         ' text:reference-format="text">'
                         % ???)
        ...
    else:   # proceed as before
        ...
        footnote.rendered = 1

I don't know what should replace the "???" above.  The OpenOffice XML
spec says that "Footnotes, endnotes, and sequences are assigned names
by the application used to create the OpenOffice.org XML file format
when the document is exported."  However, I can't find a "name"
attribute on <text:footnote> elements or subelements in the DTD.  Does
it mean the "id" attribute?  You should verify with some actual
OpenOffice output.

The text of the footnote reference can be traversed normally, then the
end-tag inserted by ``depart_footnote_reference``.  But since there's
a conditional here, there are two ways to proceed:

1. Store the end-tag on an internal stack (like the "context" stack of
   the HTML writer's HTMLTranslator class), and pop it off in
   ``depart_footnote_reference``.  This approach is recommended.

2. Process the entire <text:footnote-ref> tag in the ``visit_...``
   method, using ``self.astext()`` to get the label text.  Insert the
   end-tag, and finish with a ``raise nodes.SkipNode``.  I don't
   recommend this, because it complicates processing (makes the flow
   hard to understand with a special case; uniform is better) and it
   will break if the contents of a footnote_reference element ever
   gets more complicated.  This technique *cannot* be used on any
   element with a content model more complicated than "(#PCDATA)", so
   it's best not to use it at all.

Continuing with ``visit_footnote_reference``::

        self.body.append('<text:footnote text:id="%s">\n' % id)
        self.body.append('<text:footnote-citation text:string-value='
                         '"%s"/>\n' % number)

I don't see a "string-value" attribute in the DTD.  I do see a "label"
attribute though.  Either the DTD is wrong or out of date, or you have
the wrong attribute name.  Also, I don't understand how you're using
the Docutils <footnote-reference> "auto" attribute here (in variable
"number").

Continuing::

        self.body.append('<text:footnote-body>\n')
        self.body.append(self.start_para % '.body')
        for child in footnote.children:
            if isinstance(child, nodes.paragraph):
                self.body.append(child.astext())
        self.body.append(self.end_para)

I'd replace most of the above with a nested tree traversal.  Finally::

        self.body.append('</text:footnote-body>\n')
        self.body.append('</text:footnote>')
        raise nodes.SkipNode

-- 
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 Tue, 22 Oct 2002, David Goodger wrote:

> >> If this code is being called for the "web site" field, there is a logic
> >
> > not really
>
> Yes, really!
>
> > after all both are in the docinfo, so from a formatting point they
> > are equal.
>
> Did you look at the internal doctree representation?  The "author" field is
> completely different from the "web site" field.

i know where it comes from, you are talking from the internal represantation
i am talking of the output structure.

"Web site" and "Author" both end up in the documents docinfo.
this means: if i donot want to put formatting information
into two places one needs a function for it.


> > the pre (literal) environment in latex is verbatim.
> > how does one get the input with parsing: astext() removes the reST markup ?
>
> I don't understand the question.  Examples, please.

::
   This is *some* thing

this.astext() gives the text without stars.


-- 
 BINGO: be careful of mafia, the swindlers, the tour manager ...
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

On 21 October 2002, David Goodger said:
> The docs look good.  Please note that if you regenerate the docs with
> the latest Docutils (which I recommend you do, to take advantage of
> the improvements to the HTML produced)

OK, done.

> you should also replace the
> stylesheet.  It looks like you've made some modifications to the stock
> stylesheet, which is fine.  To keep your modifications *and* get the
> benefit of the recent improvements, without having to edit the
> stylesheet each time, I recommend extracting your modifications into a
> separate .css file and using the "@import" statement to cascade the
> stylesheets.  See http://docutils.sf.net/docs/tools.html#stylesheets
> for details.

OK, tried that.  Problem: the main modification I made was to completely
*remove* your styles for the 'a' and 'tt' tags.  (I think link colouring
should be up to the browser, and I don't like a background on inline
literals.)

So how do I override your stylesheet with removal information?  I tried
  tt { }
but that didn't work.  Didn't really expect it to.

        Greg
-- 
Greg Ward - software developer                gw...@me...
MEMS Exchange                            http://www.mems-exchange.org