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

Engelbert Gruber wrote:
> i am willing to give support for real problems, meaning not the
> pathologic test.txt.

I've got to call you on this one.  "Pathological"?!?  That is a gross
misrepresentation.  The tools/test.txt file is pretty complete (*not*
100% though), but there's nothing in it that can't be found elsewhere.
Certainly nothing pathological!

> sorry my time is limited and there are so much possibilities.

Join the club. ;-)

> maybe we schould split test.txt, so one could get a compliance page,
> which construct works how good with which writer.

tools/test.txt *is* the compliance file, the only one we've got.  I
don't see a need for a weakened compliance test.

As I've said before, to get out of the sandbox the LaTeX Writer
doesn't have to handle every construct perfectly, but it *does* have
to handle every construct without (a) crashing or (b) silently
omitting data.  If the Writer can't handle a particular construct,
have it say so explicitly ("**X Not Implemented Yet**"), *and* have it
output a simpler form, such as the string returned by the
``.astext()`` node method.  I earlier objected to the presence of many
Writer/Visitor methods containing only "pass", which is not
acceptable.

    Errors should never pass silently.
    Unless explicitly silenced.

-- 
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 Wed, 9 Oct 2002, Aahz wrote:

> On Wed, Oct 09, 2002, gr...@us... wrote:
> > On Tue, 8 Oct 2002, Aahz wrote:
> >>
> >> (i.e. chapter references); later on, it could evolve into a true
> >> multi-file system for garnering internal references.  But because I'm
> >> focused on book writing at this point, hyperlinks are *not* what I'm
> >> after.
> >
> > as a notice to book writers, maybe the latex backend is good enough.
> > i am willing to give support for real problems, meaning not the pathologic
> > test.txt. sorry my time is limited and there are so much possibilities.
> >
> > so if someone wants a pdf from his rest-docs contact me.
>
> You're missing the background here.  ;-)  Unfortunately, the book I'm
not really, although this background dates back a month, i can remember
someone asking for word output. but i can not remember if it would suffice
to convert in one direction only or if the review would be done in word
asf .. anyway my offer is to you too, but not exclusive.
> writing needs to be delivered in Word format.  Based on the information
> available to me, I've decided that the best approach is to output
> OpenOffice.org XML format from reST, then use OpenOffice to convert to
> Word.

--
engelbert gruber
email: eng...@ss...

On Wed, Oct 09, 2002, gr...@us... wrote:
> On Tue, 8 Oct 2002, Aahz wrote:
>>
>> (i.e. chapter references); later on, it could evolve into a true
>> multi-file system for garnering internal references.  But because I'm
>> focused on book writing at this point, hyperlinks are *not* what I'm
>> after.
>
> as a notice to book writers, maybe the latex backend is good enough.
> i am willing to give support for real problems, meaning not the pathologic
> test.txt. sorry my time is limited and there are so much possibilities.
> 
> so if someone wants a pdf from his rest-docs contact me.

You're missing the background here.  ;-)  Unfortunately, the book I'm
writing needs to be delivered in Word format.  Based on the information
available to me, I've decided that the best approach is to output
OpenOffice.org XML format from reST, then use OpenOffice to convert to
Word.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

On Tue, 8 Oct 2002, Aahz wrote:

> On Tue, Oct 08, 2002, David Goodger wrote:
> > Aahz wrote:
<snip>
</snip>
> (i.e. chapter references); later on, it could evolve into a true
> multi-file system for garnering internal references.  But because I'm
> focused on book writing at this point, hyperlinks are *not* what I'm
> after.
as a notice to book writers, maybe the latex backend is good enough.
i am willing to give support for real problems, meaning not the pathologic
test.txt. sorry my time is limited and there are so much possibilities.

so if someone wants a pdf from his rest-docs contact me.

maybe we schould split test.txt, so one could get a compliance page,
which construct works how good with which writer.

ad ToC: maybe have a look into latex style:
  toc = table of contents, lot = list of tables, lof = list of figures
  and when generating pdf these are bookmarks (i guess).

cheers
-- 
 BINGO: Ich komme auf Sie zu
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Aahz wrote:
> To repeat what I've said above differently, one concern I've had in
> reading through the reST docs is the extent to which references,
> particularly external references, are often equated with hyperlinks.
> That's simply not particularly applicable to my domain.

And to paraphrase what I've said before, that's simply because the only
well-developed Writer so far is for HTML.  Writers for OpenOffice XML or RTF
will present their own challenges.  I'm not concerned at all.  I'm sure such
a Writer will influence the Docutils document tree structure and system
internals, and I welcome that influence -- I'm sure it will improve the
system.  Don't blame the tool for not being able to do a job it wasn't
designed to do; instead, let's improve the tool so it *can* do the job,
naturally.

-- 
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, Oct 08, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
>> figure 3.11"), how do I do that?
> 
> I don't know.  Currently, figures don't have any attribute which can be
> referenced.  Perhaps a "name" option on figures?  For example::
> 
>     .. figure:: image.png
>        :name: image's name
> 
> DocBook and others do this kind of reference (all references, actually)
> using IDs.  reStructuredText uses reference names, not IDs, and the names
> are converted to IDs internally.  Perhaps Docutils needs an explicit ID
> mechanism, something like::
> 
>     .. figure:: image.png
>        :id: image-id
> 
> How to refer to a figure though?  Perhaps something like this::
> 
>     See :figure:`image's name`.
> 
> This could produce "See figure 1.", assuming that figures grow a numbering
> mechanism as well (they don't have one yet).

That's roughly what I was thinking of.  There will need to be a generic
naming and numbering mechanism, because other kinds of document elements
(e.g.  tables) will want references and numbering.

> In order to get "figure 3.11"-style references, we'd need sequences,
> such as chapter numbers, that are persistent across multi-file
> processing runs.  This is getting complicated.

That's one way of doing it, but see below.

>> (I've now read much of reStructuredText.txt, so I've got a better grasp
>> of what's available (i.e. knowing about "::"), but I'm still having some
>> trouble knowing which constructs are best for specific purposes.)
> 
> Such as?  Have you looked at http://docutils.sf.net/docs/rst/quickref.html?
> (OT: It would be nice if this file were converted to "self-hosted"
> reStructuredText.  It's the only hand-coded HTML in the project.)  The
> tools/test.txt file (http://docutils.sf.net/tools/test.html) may also
> provide clues.

Well, such as this figure referencing problem.  ;-)  Don't worry, I'll
mention others as I come across them.

>> I'm probably going to create some kind of ToC directive that goes in an
>> include file so I can create cross-chapter references easily.
> 
> I don't follow.  Examples?  Perhaps this To-Do entry is relevant:
> 
>     * 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"?)

Not quite.  What I'm thinking more of (at least for starters) is an
extremely simple list of references to reST documents.  Initially, it'd
just be for the purpose of auto-numbering references to those documents
(i.e. chapter references); later on, it could evolve into a true
multi-file system for garnering internal references.  But because I'm
focused on book writing at this point, hyperlinks are *not* what I'm
after.

So for now I'm likely to hard-code the actual figure numbers (but not
the chapter numbers) for cross-chapter references.

>> I'm thinking that interpreted text is likely the way to go, but David
>> has previously expressed some distaste for interpreted text that gets
>> completely removed.
> 
> I wouldn't worry about that.  If interpreted text ends up being the way to
> go, then so be it (interpreted text isn't actually implemented yet; it
> awaits real world use cases).  More importantly, we need to work out the
> mechanism before we can say what syntax applies.

To repeat what I've said above differently, one concern I've had in
reading through the reST docs is the extent to which references,
particularly external references, are often equated with hyperlinks.
That's simply not particularly applicable to my domain.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Aahz wrote:
> Let's suppose I've got a figure, and I want to refer to it (e.g. "See
> figure 3.11"), how do I do that?

I don't know.  Currently, figures don't have any attribute which can be
referenced.  Perhaps a "name" option on figures?  For example::

    .. figure:: image.png
       :name: image's name

DocBook and others do this kind of reference (all references, actually)
using IDs.  reStructuredText uses reference names, not IDs, and the names
are converted to IDs internally.  Perhaps Docutils needs an explicit ID
mechanism, something like::

    .. figure:: image.png
       :id: image-id

How to refer to a figure though?  Perhaps something like this::

    See :figure:`image's name`.

This could produce "See figure 1.", assuming that figures grow a numbering
mechanism as well (they don't have one yet).

In order to get "figure 3.11"-style references, we'd need sequences, such as
chapter numbers, that are persistent across multi-file processing runs.
This is getting complicated.

> (I've now read much of reStructuredText.txt, so I've got a better grasp
> of what's available (i.e. knowing about "::"), but I'm still having some
> trouble knowing which constructs are best for specific purposes.)

Such as?  Have you looked at http://docutils.sf.net/docs/rst/quickref.html?
(OT: It would be nice if this file were converted to "self-hosted"
reStructuredText.  It's the only hand-coded HTML in the project.)  The
tools/test.txt file (http://docutils.sf.net/tools/test.html) may also
provide clues.

> I'm probably going to create some kind of ToC directive that goes in an
> include file so I can create cross-chapter references easily.

I don't follow.  Examples?  Perhaps this To-Do entry is relevant:

    * 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"?)

(To-Do list is here: http://docutils.sf.net/spec/notes.html)

> So whatever syntax you give me ought to allow me to say
> <chapter name>:<figure name> and have it get processed properly.

I believe this is a larger issue, applicable to all kinds of references.  It
should be kept separate from figure references.  There's already an entry in
the To-Do list, which requires more thought:

    * 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.

> I'm thinking that interpreted text is likely the way to go, but David
> has previously expressed some distaste for interpreted text that gets
> completely removed.

I wouldn't worry about that.  If interpreted text ends up being the way to
go, then so be it (interpreted text isn't actually implemented yet; it
awaits real world use cases).  More importantly, we need to work out the
mechanism before we can say what syntax applies.

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

Let's suppose I've got a figure, and I want to refer to it (e.g. "See
figure 3.11"), how do I do that?  

(I've now read much of reStructuredText.txt, so I've got a better grasp
of what's available (i.e. knowing about "::"), but I'm still having some
trouble knowing which constructs are best for specific purposes.)

I'm probably going to create some kind of ToC directive that goes in an
include file so I can create cross-chapter references easily.  So
whatever syntax you give me ought to allow me to say 
<chapter name>:<figure name> and have it get processed properly.  I'm
thinking that interpreted text is likely the way to go, but David has
previously expressed some distaste for interpreted text that gets
completely removed.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

On Tue, Oct 08, 2002, David Goodger wrote:
>
> The "::" attached to the end of a paragraph is merely a convenience.

Yeah, I learned that ten minutes ago.  ;-)

Okay, I'll start the next issue in another message.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

Mathew Yeates wrote:
> I take it that doc utils cannot currently be used for
> extracting documentation from doc strings. Bummer.

Yes, I haven't had time to get this going yet.  I hope to get moving
"real soon now".  You are (and anyone is) welcome to help out.
Unfortunately, it requires knowledge of most of the Docutils system
and more beyond, so I don't expect to be inundated with voluteers.

> This will be an awesome feature when it finally makes it in.

I hope so!

> In the meantime, what is everybody using for python documentation?

I'm not using anything except for the source itself, in anticipation
of eventually using Docutils.  But there are several other tools out
there, such as HappyDoc (http://happydoc.sf.net) and epydoc
(http://epydoc.sf.net).  Only Docutils uses reStructuredText though.

-- 
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 Wed, 9 Oct 2002 5:15 am, Mathew Yeates wrote:
> Hi-
>
> I take it that doc utils cannot currently be used for
> extracting documentation from doc strings. Bummer.
> This will be an awesome feature when it finally makes it in.

Feel free to poke around the pysource sandbox :)

I recently hacked together the rjhack.py script in that directory that will 
produce a page of documentation for a python module or package. I just needs:

a) splitting into multiple files,
b) a nicer, more relevant stylesheet, and
c) additional index pages generated.

so, not much work at all ;)


> In the meantime, what is everybody using for python documentation?

epydoc does a fair job, but it's limited by two factors:

a) you've got to set up your list of modules for it - it won't automatically
   discover a package's contents, and
b) it works by importing the modules, so run-time-only modules, or those with
   unsatisfied dependencies, won't get documented. It also doesn't handle
   attribute docstrings.

It does produce nice output though :)  See the api docs at 
http://roundup.sf.net/ for an example.


      Richard

Greg Ward wrote:
> I'm having problems validating HTML output by Docutils using nsgmls,
> my HTML/XHTML validator of choice.  (It's from the James Clark's SP
> package -- installed on my Debian "unstable" box as
> sp_1.3.4-1.2.1-28.)

Brings back memories.  I used SP/nsgmls and their predecessor sgmls
intensively for 3 years, back when I lived in Japan.

> I'm sure you're all familiar with the first two lines of Docutils
> HTML output:
>
> $ head -2 upload.html
> <?xml version="1.0" encoding="us-ascii"?>
> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
> SYSTEM "" rel="nofollow">http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
>
> If I ask nsgmls to parse this (I just use it for the errors and warnings
> it prints), it barfs almost immediately:
...
> So what's up here -- is Docutils emitting bad HTML here?  or is
> nsgmls barfing on valid HTML?

That was just a thinko.  I thought the word "SYSTEM" was needed there,
but it isn't.  I had the same bug with the XML writer
(docutils_xml.py), fixed recently.  I've fixed the DOCTYPE header for
HTML; please try it again with the latest snapshot.

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

Greg Ward wrote:
> David -- I've been playing around with Docutils' HTML output and
> default.css, and I think it's possible to tighten up treatment of
> inline literal text a bit.  In particular, this:
>
>   <tt class="literal"><span class="pre">...</span></tt>
>
> can be rendered as
>
>   <tt class="literal">...</tt>
>
> if you just add this:
>
>   tt.literal {
>     white-space: nowrap
>   }
>
> to default.css.

I actually tried the same thing, back when we were discussing
line-wrapping at hyphens WRT both Docutils and textwrap.  The problem
with a "white-space: nowrap" style on the entire <tt> is that
sometimes ``inline literal text`` is longer than one line and
therefore *should* wrap.  Sometimes the line in the source is wrapped,
but the rendered output doesn't need to wrap.  Even if the line isn't
so long, wrapping often helps.  Adding all those <span> tags is an
attempt (that doesn't work in all browsers) to prevent wrapping inside
words or at hyphens, but I think wrapping at whitespace is kosher.
Inline literals are *supposed* to flow.

If the author doesn't want any line wrapping at all, they should use
literal blocks.

-- 
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]
>> I'd suggest that your "index" directive *precede* the paragraph
>> they're targeting.  That makes more sense to me, and it's more in
>> keeping with the hyperlink target construct:
>>
>>     .. _name:
>>
>>     The "name" above targets this paragraph.

[Aahz]
> <grimace> That's what I was thinking, and for some reason it offends
> my sense of esthetics.  I think of index entries as being like
> footnote entries, and footnote contents generally follow their
> references.

Having the "index" directive follow the object it targets is not a
problem.  It seems like it's a matter of personal preference, and
either way would be fine.  Having "index" after the target could
actually make processing easier; the target object will already exist
when the directive is encountered, so processing won't have to be put
off.

> I may just create a "code" directive (if one doesn't already exist),
> so the order becomes paragraph, index directive, code directive.

In my first reading of this, I thought you meant to make a
special-purpose directive for the "paragraph followed by a literal
block followed by an index directive" case.  I hope that's not the
case.  I think you mean a directive to create a code block, correct?
It's not necessary.

The "::" attached to the end of a paragraph is merely a convenience.
"::" alone will also do the trick.  This paragraph and literal block::

    A paragraph::

        # A literal
        # block

is equivalent to this::

    A paragraph:

    ::

        # A literal
        # block

If you want to have your "index" directive follow the object it
targets, and that object is the paragraph, you can put the directive
in-between like this::

    A paragraph:

    .. index:
       one
       two
       three

    ::

        # A literal
        # block

> WRT to indexing in general, I'm not likely to think about it until I
> see how my needs work in the Real World [tm].

That's a good rule of thumb.

-- 
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 8, 2002, at 12:15, Mathew Yeates  was heard saying:

> In the meantime, what is everybody using for python documentation?

With a custom LaTeX style, LaTeX2HTML and a few stylesheets :) Poke around
on python.org; I remember seeing a tarball with the necessary files in the
documentation section.

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

Hi-

I take it that doc utils cannot currently be used for
extracting documentation from doc strings. Bummer.
This will be an awesome feature when it finally makes it in.

In the meantime, what is everybody using for python documentation?

Mathew

-- 
M47h3w `/34735

I'm having problems validating HTML output by Docutils using nsgmls, my
HTML/XHTML validator of choice.  (It's from the James Clark's SP package
-- installed on my Debian "unstable" box as sp_1.3.4-1.2.1-28.)

I'm sure you're all familiar with the first two lines of Docutils HTML
output:

$ head -2 upload.html
<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" SYSTEM "" rel="nofollow">http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

If I ask nsgmls to parse this (I just use it for the errors and warnings
it prints), it barfs almost immediately:

$ nsgmls upload.html       
nsgmls:upload.html:2:63:E: name start character invalid: only delimiter ">", delimiter "[", system identifier and parameter separators are allowed
nsgmls:upload.html:2:63:E: cannot continue because of previous errors
?xml version="1.0" encoding="us-ascii"?

Line 2 column 63 is the word "SYSTEM".  I don't know much about the
hairy minutiae of (X)HTML DTD lines, so I can't tell offhand if this is
valid -- I don't recall seeing other DTD lines with it, but that's not
saying much.  So what's up here -- is Docutils emitting bad HTML here?
or is nsgmls barfing on valid HTML?

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

David -- I've been playing around with Docutils' HTML output and
default.css, and I think it's possible to tighten up treatment of inline
literal text a bit.  In particular, this:

  <tt class="literal"><span class="pre">...</span></tt>

can be rendered as

  <tt class="literal">...</tt>

if you just add this:

  tt.literal {
    white-space: nowrap
  }

to default.css.

At least that works with Opera 6.01.  It appears to be unnecessary with
Konqueror (2.2.2), which does not appear to wrap <tt> text in any
event.  And... Mozilla appears not to wrap <tt> either.  Guess someone
just needs to test with IE.

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

On Mon, Oct 07, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> What I'm trying to figure out is how to handle the case where two different
>> blocks both get attached to a preceding paragraph::
> 
> The literal block isn't "attached" to the paragraph at all.  One
> merely follows the other.  Perhaps the "::" being at the end of
> the paragraph gives the illusion of attachment, but it's only a
> convenience; no relationship is implied.

That's true for the DOM, but my perception is different WRT the reST
syntax itself.  And conceptually, the code block *is* attached to the
preceding paragraph (generally, if the paragraph gets moved, the code
block goes with it).

>> Should the order of the code block and index directive be swapped?  Does
>> it make any difference?  Do I need to do something special to handle
>> this?  (The index terms should be attached to the paragraph, not the
>> code block.)
> 
> I'd suggest that your "index" directive *precede* the paragraph they're
> targeting.  That makes more sense to me, and it's more in keeping with the
> hyperlink target construct:
> 
>     .. _name:
> 
>     The "name" above targets this paragraph.

<grimace>  That's what I was thinking, and for some reason it offends my
sense of esthetics.  I think of index entries as being like footnote
entries, and footnote contents generally follow their references.  I may
just create a "code" directive (if one doesn't already exist), so the
order becomes paragraph, index directive, code directive.

> Do you actually have an "index" directive, or is it just a
> placeholder?  Have you thought further on details of indexing that we
> discussed some time ago?

I'm currently planning to use "index" as a directive, with the block
following the directive containing one index entry per line.  It turns
out that OpenOffice doesn't support "see" and "see also" entries AFAICT,
so while there will be some annoyance, my formatting code can also be
less complex.  

I haven't actually started coding it yet; I'll probably finally do some
code this week, but I'm not sure where I'm going to start first -- most
likely just hacking together some skeletal writer.  WRT to indexing in
general, I'm not likely to think about it until I see how my needs work
in the Real World [tm].

> On an editorial note, shouldn't it be "built-in scope"? "builtin" may
> be a Python identifier, but it's not a word.

I'll let my real editors complain if they don't like it.  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

I just checked in a reworking of the "system message" reporting mechanism,
for better diagnostics.  Now almost all messages will have a source
("filename" or "<stdin>" etc.) and line number attached.  Previously, line
numbers were only attached to errors reported during the parse, none from
the transforms.  I'm sure there are some cases I've missed, so I'd
appreciate any testing and bug reports.

At the same time, I changed the output format.  The old format was like
this::

    Reporter: ERROR/3 (filename, line 3) Unexpected indentation.

The new format follows the GNU-Tools standard::

    filename:3: (ERROR/3) Unexpected indentation.

This format is understood by many tools so it should make the Reporter
output more useful.  Thanks to Skip Montanaro for the idea.

Gunnar, this change will probably affect DocFactory.  I've bumped Docutils'
version number to 0.2.5 for this change, so DocFactory can check it.  See
tools/pep2html.py for one implementation of a version check.

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

Aahz wrote:
> What I'm trying to figure out is how to handle the case where two different
> blocks both get attached to a preceding paragraph::

The literal block isn't "attached" to the paragraph at all.  One merely
follows the other.  Perhaps the "::" being at the end of the paragraph gives
the illusion of attachment, but it's only a convenience; no relationship is
implied.

> Should the order of the code block and index directive be swapped?  Does
> it make any difference?  Do I need to do something special to handle
> this?  (The index terms should be attached to the paragraph, not the
> code block.)

I'd suggest that your "index" directive *precede* the paragraph they're
targeting.  That makes more sense to me, and it's more in keeping with the
hyperlink target construct:

    .. _name:

    The "name" above targets this paragraph.

Do you actually have an "index" directive, or is it just a placeholder?
Have you thought further on details of indexing that we discussed some time
ago?

On an editorial note, shouldn't it be "built-in scope"?  "builtin" may be a
Python identifier, but it's not a word.

-- 
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'm finally starting to buckle down to the work of emitting OpenOffice
output from my reST files (so far, I've been just writing -- haven't even
checked syntax for correctness).  I'm going to do some tests myself, but
I might as well ask for advice in parallel.  What I'm trying to figure
out is how to handle the case where two different blocks both get
attached to a preceding paragraph::

    The three execution scopes are *function local* (hereafter referred
    to as local), *module global* (hereafter referred to as global), and
    builtin scope.  Local scope exists any time Python's instruction
    pointer is inside a function/method.  Global scope refers to the
    currently executing module; functions defined in another module still
    consider that module their global scope even if imported into the
    current module's namespace::

        import M
        M.f()               # f()'s global scope is the module M
        from M import f
        f()                 # f()'s global scope is still M

    .. index::
        local
        function local
        global
        module global
        builtin

Should the order of the code block and index directive be swapped?  Does
it make any difference?  Do I need to do something special to handle
this?  (The index terms should be attached to the paragraph, not the
code block.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

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

After the following commands::

    cd docutils/tools
    docutils-xml.py test.txt test.xml

I tried running the result (located at
http://docutils.sf.net/tools/test.xml) through the XML validator at
http://www.stg.brown.edu/service/xmlvalid/.  It picked up a content
model bug in the parser, which I fixed.  When I run the XML output
through the validator now, it still reports lots of warnings, but no
errors.  Examining the warnings carefully (and referring to the XML
spec) reveals that they're all bogus.  So I'm quite confident that
Docutils is producing valid XML now.

-- 
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 have just completed the integration of Dethe Elza's refactoring of
the reStructuredText directive API.  A summary is in the module
docstring of docutils/parsers/rst/directives/__init__.py, and complete
details are in the new "Creating reStructuredText Directives" How-To
document (http://docutils.sf.net/spec/howto/rst-directives.html).
Many thanks to Dethe for initiating this refactoring and writing the
initial How-To; it has simplified directive implementation
considerably.

Ramifications of this change:

1. The minimum required Python version is now 2.1 (was 2.0), with
   2.1.3 or 2.2.1 recommended.  The reason for the change is that
   directive functions now employ function attributes, a feature
   introduced in Python 2.1.

2. Any directives that aren't part of the reStructuredText parser
   (e.g. 3rd party patches) will have to be revised, although I'm not
   aware of any.  If anybody has written useful directives, please
   consider contributing them to the Docutils project.

Three new directives (also courtesy of Dethe) have been added to the
parser:

* "include": Including an external document fragment.

* "raw": Raw data pass-through, such as raw HTML.

* "replace": Text substitutions (only valid inside substitution
  definitions).

See http://docutils.sf.net/spec/rst/directives.html for details of the
new directives.

Get the latest snapshot here:

    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/

Hi David

> Yes, precisely.  I wasn't aware that HTML browsers supported MathML
> though.  What do you use?

I have tried it with M$ Internet Explorer and the MathPlayer-Plugin.
To write formulas I evaluate MathType (http://www.dessci.com/dl/).

Of course, there are other browsers which support MathML as well.
Dethe's list is perfect. (Thanks to Dethe :-))

Happy coding,
Gunnar.