From goodger@users.sourceforge.net  Thu Aug  1 02:09:39 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 31 Jul 2002 21:09:39 -0400
Subject: [Doc-SIG] ANN: Docutils 0.2 Released
Message-ID: <B96E0291.268D9%goodger@users.sourceforge.net>

The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX.  It is the subject of PEPs 256 & 258.  Docutils
currently supports input from standalone files and PEPs; the emphasis
for release 0.3 will be support for inline documentation from Python
modules and packages.  Docutils uses the reStructuredText markup, the
subject of PEP 287; but other markups are possible.  It currently
produces simple HTML for CSS and Docutils-native XML.  PDF and DocBook
XML are under development, and other formats will become available in
time.

Quick link to the download:

    http://prdownloads.sourceforge.net/docutils/docutils-0.2.tar.gz

Docutils home page: http://docutils.sourceforge.net/

There have been many improvements since release 0.1:

* The front-end tools have increased in number and now have support
  for command-line options (thanks to Greg Ward's Optik) and
  configuration files.

* Added PEP processing (see http://docutils.sf.net/spec/pep-0287.html
  for an example).  Under consideration by PythonLabs and Python-Dev
  for python.org use.

* Added a new "simple tables" construct to reStructuredText.

* Improved the generated HTML.  Now XHTML-compatible.  Improved
  stylesheet support

* Unicode and input/output encoding support.

* Swedish and German output support (boilerplate translations; thanks
  to Adam Chodorowski and Gunnar Schwant).

* Lots of internal improvements.

To subscribe to the mailing lists:

* Development discussions (docutils-develop@lists.sourceforge.net):
  http://lists.sourceforge.net/lists/listinfo/docutils-develop

* CVS checkin messages:
  http://lists.sourceforge.net/lists/listinfo/docutils-checkins

High-level discussions take place on the Python Doc-SIG mailing list:
http://mail.python.org/mailman/listinfo/doc-sig,
mailto:Doc-SIG@python.org

User documentation:

* A ReStructuredText Primer (gentle introduction):
  http://docutils.sf.net/docs/rst/quickstart.html

* Quick reStructuredText (user reference):
  http://docutils.sf.net/docs/rst/quickref.html

* Docutils Front-End Tools: http://docutils.sf.net/docs/tools.html

Further details here:

* Docutils README: http://docutils.sf.net/README.html

* Docutils History: http://docutils.sf.net/HISTORY.html

* Copying Docutils: http://docutils.sf.net/COPYING.html

There is still much work to be done.  Contributors are welcome!

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From pearu@cens.ioc.ee  Sat Aug  3 12:51:13 2002
From: pearu@cens.ioc.ee (Pearu Peterson)
Date: Sat, 3 Aug 2002 14:51:13 +0300 (EEST)
Subject: [Doc-SIG] docutils HTML contents generation and Netscape
Message-ID: <Pine.LNX.4.21.0208031421100.12552-100000@cens.kybi>

Hi,

While viewing docutils generated html files with Netscape (4.77) I have
noticed that links in Contents to document sections do not work at all
(they work nicely with Mozilla though). It seems that Netscape does not
understand HTML div tags well.

Here follows my changes to docutils/writers/html4css1.py (in CVS) that
make the links work for Netscape as well:

diff -r1.32 html4css1.py
920,921c920,922
<                 self.body.append('<a class="toc-backref" href="#%s">'
<                                  % node['refid'])
---
>                 node_id = nodes.make_id(node.astext())
>                 self.body.append('<a class="toc-backref" href="#%s" name="%s">'
>                                  % (node['refid'],node_id))

BTW, I just started to use docutils-0.2 for documenting the f2py project
and I already find docutils quite usable despite its alpha nature that
sometimes shows up. I'll try to report these glitches but without trying
to fix them too hard if that's OK.

Thanks,
	Pearu



From goodger@users.sourceforge.net  Sat Aug  3 20:27:34 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 03 Aug 2002 15:27:34 -0400
Subject: [Doc-SIG] docutils HTML contents generation and Netscape
In-Reply-To: <Pine.LNX.4.21.0208031421100.12552-100000@cens.kybi>
Message-ID: <B971A6E5.26B2A%goodger@users.sourceforge.net>

Pearu Peterson wrote:
> While viewing docutils generated html files with Netscape (4.77) I have
> noticed that links in Contents to document sections do not work at all
> (they work nicely with Mozilla though). It seems that Netscape does not
> understand HTML div tags well.

Netscape 4 is broken when it comes to HTML 4 & CSS 1 support, which is what
html4css1.py produces.  Thanks for the patch; unfortunately it won't work in
all circumstances.  ``nodes.make_id`` cannot be relied upon to produce a
unique ID; see ``nodes.document.set_id`` to see how it's used.  But based on
your bug report I've reworked the HTML writer in several places to get
better results from Netscape 4 (footnote & other references didn't work
either).  I'm not going to commit to full Netscape 4 support (it's a
bottomless pit), but if you find other cases where the HTML doesn't work, I
may fix the writer if the fixes aren't too hard.

> I'll try to report these glitches but without trying
> to fix them too hard if that's OK.

Yes, please do.  Bug reports are welcome.  The best place for them is the
SourceForge bug tracker:
http://sourceforge.net/tracker/?func=add&group_id=38414&atid=422030

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From guido@python.org  Sat Aug  3 20:31:36 2002
From: guido@python.org (Guido van Rossum)
Date: Sat, 03 Aug 2002 15:31:36 -0400
Subject: [Doc-SIG] docutils HTML contents generation and Netscape
In-Reply-To: Your message of "Sat, 03 Aug 2002 15:27:34 EDT."
 <B971A6E5.26B2A%goodger@users.sourceforge.net>
References: <B971A6E5.26B2A%goodger@users.sourceforge.net>
Message-ID: <200208031931.g73JVaA25942@pcp02138704pcs.reston01.va.comcast.net>

[David Goodger]

> I'm not going to commit to full Netscape 4 support (it's a
> bottomless pit),

I resent this attitude.

According to recent statistics, NS4 is still more common than Mozilla,
NS6, and everything else together (though behind IE, all versions
together).

Generating HTML 4.0 that doesn't rely on style sheets for features
isn't hard at all.  Use CSS for pretty looks, but please stick to HTML
for functionality.

--Guido van Rossum (home page: http://www.python.org/~guido/)


From goodger@users.sourceforge.net  Sat Aug  3 21:02:11 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 03 Aug 2002 16:02:11 -0400
Subject: [Doc-SIG] docutils HTML contents generation and Netscape
In-Reply-To: <200208031931.g73JVaA25942@pcp02138704pcs.reston01.va.comcast.net>
Message-ID: <B971AF02.26B2D%goodger@users.sourceforge.net>

[David Goodger]
>> I'm not going to commit to full Netscape 4 support (it's a
>> bottomless pit),

[Guido van Rossum]
> I resent this attitude.
> 
> According to recent statistics, NS4 is still more common than Mozilla,
> NS6, and everything else together (though behind IE, all versions
> together).
> 
> Generating HTML 4.0 that doesn't rely on style sheets for features
> isn't hard at all.  Use CSS for pretty looks, but please stick to HTML
> for functionality.

Didn't mean to offend.  What I meant was, NS4 doesn't have good support for
CSS or even HTML 4 ("id" attributes are ignored, for example).
Functionality that is broken in the HTML under NS4, like the links that
didn't work that Pearu reported, will of course be fixed.  When I said "full
Netscape 4 support", I meant the CSS-side, the pretty looks; trying to get
NS4 rendering to look as good as NS6 or IE5/6 or Mozilla seems to be an
exercise in futility, especially since I'm not an HTML expert.  Patches and
advice are always welcome, of course.

Out of curiosity, do you have a URL for those statistics?

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From goodger@users.sourceforge.net  Sat Aug  3 23:45:04 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 03 Aug 2002 18:45:04 -0400
Subject: [Doc-SIG] HTML puzzle
Message-ID: <B971D52F.26B54%goodger@users.sourceforge.net>

I've been fiddling with the stylesheet for Docutils output, and I came
across something strange in Netscape 4.7 (MacOS).  I've reduced it to one
variable: web server.  I've copied the HTML and stylesheet for PEP 257 from
python.org to docutils.sf.net, so I'm looking at the exact same data, but
they render differently.  Here are the two URLs:

    http://www.python.org/peps/pep-0257.html
    http://docutils.sf.net/spec/pep0257.html

(Note there's no "-"; that's so it doesn't clobber the locally-generated
file that does have a "-".  Otherwise insignificant.)

Specifically, the typeface and spacing of the RFC2822 headers and section
headers render differently.  The python.org one comes out correctly, with
headers in a sans-serif font, but the sf.net one uses a serif font.  In the
sf.net version, there's more space between the lines in the header.

Can anyone reproduce or explain this?

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From guido@python.org  Sun Aug  4 01:19:57 2002
From: guido@python.org (Guido van Rossum)
Date: Sat, 03 Aug 2002 20:19:57 -0400
Subject: [Doc-SIG] docutils HTML contents generation and Netscape
In-Reply-To: Your message of "Sat, 03 Aug 2002 16:02:11 EDT."
 <B971AF02.26B2D%goodger@users.sourceforge.net>
References: <B971AF02.26B2D%goodger@users.sourceforge.net>
Message-ID: <200208040019.g740Jvt26225@pcp02138704pcs.reston01.va.comcast.net>

> [David Goodger]
> >> I'm not going to commit to full Netscape 4 support (it's a
> >> bottomless pit),
> 
> [Guido van Rossum]
> > I resent this attitude.
> > 
> > According to recent statistics, NS4 is still more common than Mozilla,
> > NS6, and everything else together (though behind IE, all versions
> > together).
> > 
> > Generating HTML 4.0 that doesn't rely on style sheets for features
> > isn't hard at all.  Use CSS for pretty looks, but please stick to HTML
> > for functionality.
> 
> Didn't mean to offend.  What I meant was, NS4 doesn't have good support for
> CSS or even HTML 4 ("id" attributes are ignored, for example).
> Functionality that is broken in the HTML under NS4, like the links that
> didn't work that Pearu reported, will of course be fixed.  When I said "full
> Netscape 4 support", I meant the CSS-side, the pretty looks; trying to get
> NS4 rendering to look as good as NS6 or IE5/6 or Mozilla seems to be an
> exercise in futility, especially since I'm not an HTML expert.  Patches and
> advice are always welcome, of course.

OK, maybe I was overreacting.  We've gone through this a few times in
the Zope world, where a few young zealots wanted to do everything with
style sheets.  I agree that you don't have to get the CSS support for
NS4 right (as long as it isn't broken), as long as the functionality
is there.

> Out of curiosity, do you have a URL for those statistics?

Someone mailed them around, but I forgot to save them and can't easily
find them back.  Searching Google for "browser statistics" gave me a
few useful pages, e.g. this:

http://www.cen.uiuc.edu/bstats/latest-month.html

IE's clearly the winner, with NS a distant second.

--Guido van Rossum (home page: http://www.python.org/~guido/)


From Simon.Budig@unix-ag.org  Mon Aug  5 22:11:20 2002
From: Simon.Budig@unix-ag.org (Simon Budig)
Date: Mon, 5 Aug 2002 23:11:20 +0200
Subject: [Doc-SIG] HTML puzzle
In-Reply-To: <B971D52F.26B54%goodger@users.sourceforge.net>; from goodger@users.sourceforge.net on Sat, Aug 03, 2002 at 06:45:04PM -0400
References: <B971D52F.26B54%goodger@users.sourceforge.net>
Message-ID: <20020805231119.A14774@vmax.unix-ag.uni-siegen.de>

David Goodger (goodger@users.sourceforge.net) wrote:
> I've been fiddling with the stylesheet for Docutils output, and I came
> across something strange in Netscape 4.7 (MacOS).  I've reduced it to one
> variable: web server.

Yep, it is a web server issue on the sourceforge site.

Some relevant bits from the http-conversation:

> I've copied the HTML and stylesheet for PEP 257 from
> python.org to docutils.sf.net, so I'm looking at the exact same data, but
> they render differently.  Here are the two URLs:
> 
>     http://www.python.org/peps/pep-0257.html

simon@ping-pong:~$ telnet www.python.org 80
HEAD /peps/style.css HTTP/1.0
Host: www.python.org 

HTTP/1.1 200 OK
Content-Type: text/css

>     http://docutils.sf.net/spec/pep0257.html

simon@ping-pong:~$ telnet docutils.sf.net 80
HEAD /spec/style.css HTTP/1.0 
Host: docutils.sf.net

HTTP/1.1 302 Found
Content-Type: text/html; charset=iso-8859-1

> Can anyone reproduce or explain this?

Yes. The sourceforge server does not label the style.css as the content
type text/css, it instead serves this as text/html which is wrong. Some
browsers might choose to ignore/misinterpret the stylesheet when the
webserver announces it as HTML instead of CSS.

I am not sure how liberal the sourceforge server is, it definitely
should serve files ending in .css as text/css. *Maybe* (probably not) you
can override this with a .htaccess in the webdirectory containing
the line

AddType text/css .css

If the administrators of sourceforge do allow .htaccess-files this
should make the apache specify the correct content type.

Hope this helps,
        Simon
-- 
      Simon.Budig@unix-ag.org       http://www.home.unix-ag.org/simon/


From goodger@users.sourceforge.net  Mon Aug  5 22:51:00 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Mon, 05 Aug 2002 17:51:00 -0400
Subject: [Doc-SIG] HTML puzzle
In-Reply-To: <20020805231119.A14774@vmax.unix-ag.uni-siegen.de>
Message-ID: <B9746B82.26C7D%goodger@users.sourceforge.net>

Simon Budig wrote:
[detailed explanation]
> Hope this helps,

Thanks, Simon, great explanation!  I'm relieved that I'm not going crazy.
I'll try the .htaccess trick after some research.  And I'll forward your
explanation on to SourceForge if you don't mind.

One puzzle still remains though.  *Some* of the styles in the stylesheet
from SourceForge *are* being acted upon.  In a compound style (more than one
";"-separated entry in the style), *some* of those lines are being acted
upon, some not.  Looks like a weird Netscape 4 bug.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From delza@mac.com  Tue Aug  6 21:05:36 2002
From: delza@mac.com (Dethe Elza)
Date: 06 Aug 2002 13:05:36 -0700
Subject: [Doc-SIG] Re: HTML Puzzle
In-Reply-To: <20020804160001.29978.89400.Mailman@mail.python.org>
References: <20020804160001.29978.89400.Mailman@mail.python.org>
Message-ID: <1028664337.593.24.camel@laptop>

I would check to see if the stylesheets are being served with the proper
MIME types.  Navigator tends to be sensitive to that sort of thing,
while IE tends to ignore MIME types in favor of extension-mapping.

--Dethe

> I've been fiddling with the stylesheet for Docutils output, and I came
> across something strange in Netscape 4.7 (MacOS).  I've reduced it to one
> variable: web server.  I've copied the HTML and stylesheet for PEP 257 from
> python.org to docutils.sf.net, so I'm looking at the exact same data, but
> they render differently.  Here are the two URLs:
> 
>     http://www.python.org/peps/pep-0257.html
>     http://docutils.sf.net/spec/pep0257.html
> 
> (Note there's no "-"; that's so it doesn't clobber the locally-generated
> file that does have a "-".  Otherwise insignificant.)
> 
> Specifically, the typeface and spacing of the RFC2822 headers and section
> headers render differently.  The python.org one comes out correctly, with
> headers in a sans-serif font, but the sf.net one uses a serif font.  In the
> sf.net version, there's more space between the lines in the header.
> 
> Can anyone reproduce or explain this?




From Dmitry Jemerov <yole@yole.ru>  Thu Aug  8 20:55:21 2002
From: Dmitry Jemerov <yole@yole.ru> (Dmitry Jemerov)
Date: Thu, 8 Aug 2002 23:55:21 +0400
Subject: [Doc-SIG] numbered headings in reST
Message-ID: <62303168653.20020808235521@yole.ru>

Hello David,

  Recently I decided to use reST to write the documentation for my
(soon to be released) project. The formatting features provided by
reST seem to match my needs pretty well, with one exception. One of
the first things I tried to write in my file was:

1. This is the heading of section one
=====================================

  However, this doesn't work, and the following error message is
given:
  
WARNING (level 2 system message)
Enumerated list ends without a blank line; unexpected unindent at line 5.

  I've seen no mention of numbered headings in the spec, but in my
opinion, they are a very commonly used construct. Are you planning to
support numbered headings in the future version of DocUtils? Maybe I
could try to do a patch for numbered headings support myself?

-- 
Best regards,
 Dmitry                          mailto:yole@yole.ru



From goodger@users.sourceforge.net  Fri Aug  9 02:02:30 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 08 Aug 2002 21:02:30 -0400
Subject: [Doc-SIG] numbered headings in reST
In-Reply-To: <62303168653.20020808235521@yole.ru>
Message-ID: <B9788CE5.26F6F%goodger@users.sourceforge.net>

Dmitry Jemerov wrote:
> Recently I decided to use reST to write the documentation for my
> (soon to be released) project.

Our first report from Russia.  Cool.  Are you using Docutils for Russian or
English text?

> One of the first things I tried to write in my file was:
> 
> 1. This is the heading of section one
> =====================================
> 
> However, this doesn't work, and the following error message is
> given:
> 
> WARNING (level 2 system message)
> Enumerated list ends without a blank line; unexpected unindent at line 5.

Yes, the "1." is recognized as a list marker.  I've had another similar bug
report recently; see http://docutils.sf.net/spec/notes.html#bugs (marked
with "@@@").  I'll be looking into it soon.  It may be time to re-examine
the PELI (potential enumerated list item) idea; see the block quote in
http://docutils.sf.net/spec/rst/problems.html#enumerated-list-markup .

> I've seen no mention of numbered headings in the spec, but in my
> opinion, they are a very commonly used construct. Are you planning to
> support numbered headings in the future version of DocUtils?

In the spec/notes.txt file there is this idea for a "sectnum" directive:

    _`parts.sectnum` (automatic section numbering; add support to
    the "contents" directive; could be cmdline option also)

By this I'm thinking of an option to automatically number sections; the user
wouldn't have to write or maintain the numbering.  Would that be a better
solution for you?

In the meantime, you can backslash-escape the title to avoid it being
mistaken for a list marker::

      \1. This is the heading of section one
      ======================================

I know, it's ugly.

> Maybe I could try to do a patch for numbered headings support myself?

If you'd like to give it a try, please go for it!  But I think the correct
approach would be to fix the current naive parsing, rather than just allow
for special cases like numbered titles.  Fixing the enumerated list parsing
would require some lookahead, as is done with definition lists and section
headers: the first line isn't acted upon until the second line is checked.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From Dmitry Jemerov <yole@yole.ru>  Fri Aug  9 16:47:05 2002
From: Dmitry Jemerov <yole@yole.ru> (Dmitry Jemerov)
Date: Fri, 9 Aug 2002 19:47:05 +0400
Subject: Re[2]: [Doc-SIG] numbered headings in reST
Message-ID: <122839867.20020809194705@yole.ru>

Hello David,

Friday, August 9, 2002, 5:02:30 AM, you wrote:

>> Recently I decided to use reST to write the documentation for my
>> (soon to be released) project.

DG> Our first report from Russia.  Cool.  Are you using Docutils for Russian or
DG> English text?

  English for now, but a Russian translation is planned for a later
time.

>> One of the first things I tried to write in my file was:
>> 
>> 1. This is the heading of section one
>> =====================================
>> 
>> However, this doesn't work, and the following error message is
>> given:
>> 
>> WARNING (level 2 system message)
>> Enumerated list ends without a blank line; unexpected unindent at line 5.

DG> Yes, the "1." is recognized as a list marker.  I've had another similar bug
DG> report recently; see http://docutils.sf.net/spec/notes.html#bugs (marked
DG> with "@@@").  I'll be looking into it soon.  It may be time to re-examine
DG> the PELI (potential enumerated list item) idea; see the block quote in
DG> http://docutils.sf.net/spec/rst/problems.html#enumerated-list-markup .

  In my opinion, it is not a good idea to require multiple adjacent
list items. As far as I understand, this will cause the following not
to be treated as a list:

  * List item one

     Here is a long list of considerations related to the list item
     one.

  * List item two

     And some more considerations.

  What I would prefer is a different form of lookahead: if the line
following a potential list item is definitely not a list item (a
heading marker, or the start of a table, or something like that), then
the list is not created.

>> I've seen no mention of numbered headings in the spec, but in my
>> opinion, they are a very commonly used construct. Are you planning to
>> support numbered headings in the future version of DocUtils?

DG> In the spec/notes.txt file there is this idea for a "sectnum" directive:

DG>     _`parts.sectnum` (automatic section numbering; add support to
DG>     the "contents" directive; could be cmdline option also)

DG> By this I'm thinking of an option to automatically number sections; the user
DG> wouldn't have to write or maintain the numbering.  Would that be a better
DG> solution for you?

  How exactly would that look and work? Automatic section numbering would
be a good thing for me.

  Another idea is to have section auto-numbering like proposed by Tony Ibbs
(alternatives.txt, Auto-Enumerated Lists, item 4):

#1. Section 1.
==============

#1.#1. This is a subsection of section 1.
-----------------------------------------

#1.#2. And another subsection
-----------------------------

  This looks more readable as plaintext than embedding some directives
like _`parts.sectnum` in the section title.

DG> In the meantime, you can backslash-escape the title to avoid it being
DG> mistaken for a list marker::

DG>       \1. This is the heading of section one
DG>       ======================================

DG> I know, it's ugly.

  OK, I'll use this if nothing else works. However, numbered headings
are common enough to require a better solution.

>> Maybe I could try to do a patch for numbered headings support myself?

DG> If you'd like to give it a try, please go for it!  But I think the correct
DG> approach would be to fix the current naive parsing, rather than just allow
DG> for special cases like numbered titles.  Fixing the enumerated list parsing
DG> would require some lookahead, as is done with definition lists and section
DG> headers: the first line isn't acted upon until the second line is checked.

  OK, once we decide on the best solution, I'll try to do the implementation.

-- 
Best regards,
 Dmitry                            mailto:yole@yole.ru



From Dmitry Jemerov <yole@yole.ru>  Sat Aug 10 17:38:08 2002
From: Dmitry Jemerov <yole@yole.ru> (Dmitry Jemerov)
Date: Sat, 10 Aug 2002 20:38:08 +0400
Subject: Re[2]: [Doc-SIG] numbered headings in reST
In-Reply-To: <B97A10C0.27078%goodger@users.sourceforge.net>
References: <B97A10C0.27078%goodger@users.sourceforge.net>
Message-ID: <13079963781.20020810203808@yole.ru>

Hello David,

Saturday, August 10, 2002, 8:37:22 AM, you wrote:

>>> In the spec/notes.txt file there is this idea for a "sectnum"
>>> directive:
>>>
>>>     _`parts.sectnum` (automatic section numbering; add support to
>>>     the "contents" directive; could be cmdline option also)
>>>
>>> By this I'm thinking of an option to automatically number sections;
>>> the user wouldn't have to write or maintain the numbering.  Would
>>> that be a better solution for you?
>> 
>> How exactly would that look and work? Automatic section numbering
>> would be a good thing for me.

DG> Something like this::

DG>     .. sectnum::

DG>     Section One
DG>     ===========

DG>     Section Two
DG>     ===========

DG>     Subsection One
DG>     --------------

DG> When processed, the numbers "1", "2", and "2.1" would be prefixed to
DG> the titles automatically.  The directive name could be "sectnum" or
DG> "section-numbers" or "section-numbering", perhaps with a ":global:"
DG> attribute.

  OK. Docutils is still quite new to me, and I didn't understand at
once that sectnum will be a global transform specified once in the
document, and not in every section title.

  And after all, document transforms seemed easier to figure out than
list parsing code, and so the patch implementing the sectnum directive
is now at:

  http://sourceforge.net/tracker/index.php?func=detail&aid=593461&group_id=38414&atid=422032

  The directive doesn't have any attributes (should there be any?
which?). Also, the auto-generated numbers are not added to the section
IDs, and only to the title text visible in the document. A test-case
is included with the patch.

  Please review the code and check it in if you consider it worthy.
I don't give up on correct list parsing yet - I'll try to solve the
list parsing problem tomorrow.

DG> On a related note, in a 2001-07-10 post to Doc-SIG, I wrote:

DG>     I'm also toying with the idea of removing leading numbers from
DG>     implicit link names, so a section titled "3. Conclusion" can be
DG>     referred to by "Conclusion_" (i.e., without the "3.").

DG> I've added it to the to-do list, but with a "?", so it's low-to-no
DG> priority.

  I could fix this too if you like. This should be consistent with
section auto-numbering, I think - either the section auto-numberer
should add the numbers to link names, or the numbers specified in link
names by the user should be removed. The second option looks
better.

-- 
Best regards,
 Dmitry                            mailto:yole@yole.ru



From goodger@users.sourceforge.net  Sun Aug 11 03:28:37 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 10 Aug 2002 22:28:37 -0400
Subject: [Doc-SIG] numbered headings in reST
In-Reply-To: <13079963781.20020810203808@yole.ru>
Message-ID: <B97B4414.270C5%goodger@users.sourceforge.net>

[David]
>>>> In the spec/notes.txt file there is this idea for a "sectnum"
>>>> directive:
>>>>
>>>>     _`parts.sectnum` (automatic section numbering; add support to
>>>>     the "contents" directive; could be cmdline option also)
>>>>
>>>> By this I'm thinking of an option to automatically number sections;
>>>> the user wouldn't have to write or maintain the numbering.  Would
>>>> that be a better solution for you?

[Dmitry]
>>> How exactly would that look and work? Automatic section numbering
>>> would be a good thing for me.

[David]
>> Something like this::
>> 
>>     .. sectnum::
>> 
>>     Section One
>>     ===========
>> 
>>     Section Two
>>     ===========
>> 
>>     Subsection One
>>     --------------
>> 
>> When processed, the numbers "1", "2", and "2.1" would be prefixed to
>> the titles automatically.  The directive name could be "sectnum" or
>> "section-numbers" or "section-numbering", perhaps with a ":global:"
>> attribute.

[Dmitry]
> OK. Docutils is still quite new to me, and I didn't understand at
> once that sectnum will be a global transform specified once in the
> document, and not in every section title.

Actually, I'd first thought of "sectnum" altering how sections were
handled by the parser, but this way is probably better.  It's
certainly simpler!

> And after all, document transforms seemed easier to figure out than
> list parsing code, and so the patch implementing the sectnum
> directive is now at:
> 
> 
http://sourceforge.net/tracker/index.php?func=detail&aid=593461&group_id=384
14&atid=422032

Thank you!  The patch looks good, but there are some issues we should
consider.

> A test-case is included with the patch.

That's great; thank you.  How are you at documentation? ;-)

The first issue is,

> The directive doesn't have any attributes (should there be any?
> which?).

Perhaps, like with the "contents" directive, there could be a "depth"
attribute?  Would it be useful to limit the depth of numbered
sections?  Sections too deeply nested wouldn't be numbered.

Also, should there be a "local" attribute?  Perhaps sections from a
certain level down could have numbering enabled, where sections in the
rest of the document are not numbered.  For example, a reference
section of a manual might be numbered, but not the rest.  OTOH, an
all-or-nothing approach would probably be enough.

Perhaps there should be some way to control the enumeration sequences?
For example, in a long document chapters are usually numbered, but
appendices use letters (A, B, C, ...).  Perhaps multiple "sectnum"
directives could exist, each specifying the style of the remainder of
the document.  So just before the first appendix, there could be a "..
sectnum:: :enum: A" directive.  Should this apply only to the first
part of the section number, or should each part be adjustable?  Of
course, this doesn't have to be implemented now; we can add it to the
to-do list until someone actually needs it.

In any case, the directive as is doesn't do anything with its ``data``
parameter.  If it doesn't accept attributes, it should signal an error
if there *is* any directive data.

The second issue is the interaction of "sectnum" with the "contents"
directive.  Try processing a document with both directives; the order
of the directives is significant.  If the "contents" directive comes
before "sectnum", the section numbers are not reflected in the table
of contents.  If "sectnum" comes first, the section number do make it
to the table of contents.  I've put examples on the web:

- "contents" first: http://docutils.sourceforge.net/tools/test1.html
- "sectnum" first: http://docutils.sourceforge.net/tools/test2.html

The reason for this is because the "sectnum" directive inserts a
``pending`` element, which is fine.  The "contents" directive does
too.  Both are labeled "last reader", meaning they're both triggered
after the standard reader transforms are finished; a simple scheduling
mechanism.  But within "last reader", it's first come, first served.
Should we leave the behavior dependent on the order of directives, or
choose one and enforce it?  It would be easy to enforce either order
by labeling one of the ``pending`` elements as "first writer" instead
of "last reader".

(Actually, in the test documents there's a small local table of
contents under "Directives", so in test1.html you can see *both*
styles!)

It's clear that the ``pending`` elements need to be documented: what
they're used for and when they're triggered ("first reader", "last
writer", etc.).

Notice the table of contents in the test2.html document.  Currently
it looks something like this::

    * 1. Structural Elements
      - 1.1. Section Title
      - 1.2. Transitions
    * 2. Body Elements
      - 2.1. Paragraphs

I think it should look like this (perhaps with extra indentation)::

    1. Structural Elements
    1.1. Section Title
    1.2. Transitions
    2. Body Elements
    2.1. Paragraphs

An alternative could look like this::

    1. Structural Elements
       1. Section Title
       2. Transitions
    2. Body Elements
       1. Paragraphs

To enable a different type of table of contents, the section titles
should have an extra attribute, such as "auto".

The third issue has to do with references:

> Also, the auto-generated numbers are not added to the section IDs,
> and only to the title text visible in the document.

I think this is the correct approach.

>> On a related note, in a 2001-07-10 post to Doc-SIG, I wrote:
>> 
>>     I'm also toying with the idea of removing leading numbers from
>>     implicit link names, so a section titled "3. Conclusion" can be
>>     referred to by "Conclusion_" (i.e., without the "3.").
>> 
>> I've added it to the to-do list, but with a "?", so it's low-to-no
>> priority.
> 
> I could fix this too if you like. This should be consistent with
> section auto-numbering, I think - either the section auto-numberer
> should add the numbers to link names, or the numbers specified in
> link names by the user should be removed. The second option looks
> better.

What I meant by statement quoted was that, given a manually numbered
section title like this::

    1. Introduction
    ===============

Currently (if the parser worked properly), we would only be able to
refer to this section with a reference like this::

    `1. Introduction`_

This is a bit unnatural.  It would be better to be able to refer more
simply::

    Introduction_

I think with the "sectnum" directive, we've got the right solution.
It's independent of hyperlinks.  We'd probably have to leave both
reference options open.  Fiddling with the reference names doesn't
feel right to me; too much opportunity for edge-case screw-ups.

Other than that, the directive looks great!

> Please review the code and check it in if you consider it worthy.

Better yet, I'll add you as a developer and let you check it in
yourself.  Let's hash out the issues raised above though.  The
reference issue (third) can be ignored for now.  The table of contents
interaction (second issue) must be dealt with.  And we should at least
decide which attributes could be useful, and which should be tossed
(first issue).

On a related note, the small patch to test/package_unittest.py (which
we discussed off-list) inspired me to finally fix this bug:

    - Fix tests to run standalone.  I.e., allow::
    
          cd test/test_rst
          test_inline_markup.py
    
      Raises an exception with path processing on GNU/Linux (but only
      sometimes???).

I'd been frustrated before because the failure seemed to be random,
not reproducible.  Well, I finally found a way to reproduce it.  Using
code earlier than today's (which no longer has the bug; the 0.2
release does), execute the following shell commands::

    cd docutils
    find . -name '*.pyc' | xargs rm
    cd test
    alltests.py
    cd test_transforms
    for f in test_*.py ; do ls -l $f ; $f ; done

An interaction with the ``inspect`` module causes the test to crash.
``inspect`` is used to get the path of the calling module, and under
conditions that are unclear to me, sometimes the module's path is not
available.  I suspect it has to do with whether the module was
compiled or not, and/or if the module was imported or run as a script.
It remains a bit of a mystery, but the changes appear to have fixed
the tests.  Perhaps Garth Kidd (the original author of the
``package_unittest`` code) can shed some light?

> I don't give up on correct list parsing yet - I'll try to solve the
> list parsing problem tomorrow.

I look forward to the results!

And thanks again!

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From Dmitry Jemerov <yole@yole.ru>  Sun Aug 11 21:03:11 2002
From: Dmitry Jemerov <yole@yole.ru> (Dmitry Jemerov)
Date: Mon, 12 Aug 2002 00:03:11 +0400
Subject: Re[2]: [Doc-SIG] numbered headings in reST
In-Reply-To: <B97B4414.270C5%goodger@users.sourceforge.net>
References: <B97B4414.270C5%goodger@users.sourceforge.net>
Message-ID: <182178667059.20020812000311@yole.ru>

Hello David,

Sunday, August 11, 2002, 6:28:37 AM, you wrote:

>> A test-case is included with the patch.

DG> That's great; thank you.  How are you at documentation? ;-)

  I'll try to write the documentation after the code is finalized and
the issues are solved.

DG> The first issue is,

>> The directive doesn't have any attributes (should there be any?
>> which?).

DG> Perhaps, like with the "contents" directive, there could be a "depth"
DG> attribute?  Would it be useful to limit the depth of numbered
DG> sections?  Sections too deeply nested wouldn't be numbered.

  Yes, that's a good idea, and simple to implement, too. It's
implemented in the version of the patch that I checked in today.

DG> Also, should there be a "local" attribute?  Perhaps sections from a
DG> certain level down could have numbering enabled, where sections in the
DG> rest of the document are not numbered.  For example, a reference
DG> section of a manual might be numbered, but not the rest.  OTOH, an
DG> all-or-nothing approach would probably be enough.

  In my opinion, most documents are numbered all-or-nothing. We could
implement "local" if someone requests it.

DG> Perhaps there should be some way to control the enumeration sequences?
DG> For example, in a long document chapters are usually numbered, but
DG> appendices use letters (A, B, C, ...).  Perhaps multiple "sectnum"
DG> directives could exist, each specifying the style of the remainder of
DG> the document.  So just before the first appendix, there could be a "..
DG> sectnum:: :enum: A" directive.  Should this apply only to the first
DG> part of the section number, or should each part be adjustable?  Of
DG> course, this doesn't have to be implemented now; we can add it to the
DG> to-do list until someone actually needs it.

  This is also a good idea, and I'd like to implement it soon. I think
that it's enough to configure only the first part of the number;
I don't see a clear syntax that will allow configuring all parts.
After all, if some non-trivial numbering is needed, one could just
write the numbers by hand.

DG> In any case, the directive as is doesn't do anything with its ``data``
DG> parameter.  If it doesn't accept attributes, it should signal an error
DG> if there *is* any directive data.

  Well, now the directive does accept an attribute (depth), and it
uses the standard mechanism for parsing attributes and reporting errors.
Hopefully that's good enough. :-)

DG> The second issue is the interaction of "sectnum" with the "contents"
DG> directive.  Try processing a document with both directives; the order
DG> of the directives is significant.  If the "contents" directive comes
DG> before "sectnum", the section numbers are not reflected in the table
DG> of contents.  If "sectnum" comes first, the section number do make it
DG> to the table of contents.  I've put examples on the web:

DG> - "contents" first: http://docutils.sourceforge.net/tools/test1.html
DG> - "sectnum" first: http://docutils.sourceforge.net/tools/test2.html

DG> The reason for this is because the "sectnum" directive inserts a
DG> ``pending`` element, which is fine.  The "contents" directive does
DG> too.  Both are labeled "last reader", meaning they're both triggered
DG> after the standard reader transforms are finished; a simple scheduling
DG> mechanism.  But within "last reader", it's first come, first served.
DG> Should we leave the behavior dependent on the order of directives, or
DG> choose one and enforce it?  It would be easy to enforce either order
DG> by labeling one of the ``pending`` elements as "first writer" instead
DG> of "last reader".

  Well, now the directives are coupled even more, and so there must be
a way to enforce correct processing order, and not make it the user's
responsibility.

  Also, the "sectnum" directive has another dependency: it must run
after the DocTitle transform. This works correctly now, but maybe it
should somehow be made explicit.

  What do you think of introducing a numeric priority system for
pending operations? Is this over-design? I think that we may encounter
more cases of transform order dependencies later, and the current
four-level system may not be enough.

DG> It's clear that the ``pending`` elements need to be documented: what
DG> they're used for and when they're triggered ("first reader", "last
DG> writer", etc.).

  Frankly speaking, I still haven't found the code that triggers
the "pending" elements and handles all the "first reader" stuff. :-)
So I'd appreciate more documentation on that issue very much.

DG> Notice the table of contents in the test2.html document.  Currently
DG> it looks something like this::

DG>     * 1. Structural Elements
DG>       - 1.1. Section Title
DG>       - 1.2. Transitions
DG>     * 2. Body Elements
DG>       - 2.1. Paragraphs

DG> I think it should look like this (perhaps with extra indentation)::

DG>     1. Structural Elements
DG>     1.1. Section Title
DG>     1.2. Transitions
DG>     2. Body Elements
DG>     2.1. Paragraphs

DG> An alternative could look like this::

DG>     1. Structural Elements
DG>        1. Section Title
DG>        2. Transitions
DG>     2. Body Elements
DG>        1. Paragraphs

DG> To enable a different type of table of contents, the section titles
DG> should have an extra attribute, such as "auto".

  In the version that I checked in today, that is also implemented. I
haven't found a DTD element that would be formatted as a plain list of
strings with no paragraph breaks between them. (Footnotes and
citations are formatted like that, but abusing this for the table of
contents would be too much of a hack.) Therefore, the contents for
auto-numbered sections is now generated as an enumerated list.

  This looks pretty nice, with one exception: the HTML writer doesn't
support prefixes for enumerated lists. Thus, the table of contents in
HTML looks as your second alternative, and not the first one (which is
what I would like to achieve).

  Do you have any ideas on implementing the prefixes for enumerated
lists in HTML? I would really like to have this fixed.

DG> The third issue has to do with references:

>> Also, the auto-generated numbers are not added to the section IDs,
>> and only to the title text visible in the document.

DG> I think this is the correct approach.

DG> I think with the "sectnum" directive, we've got the right solution.
DG> It's independent of hyperlinks.  We'd probably have to leave both
DG> reference options open.  Fiddling with the reference names doesn't
DG> feel right to me; too much opportunity for edge-case screw-ups.

  OK, then so be it. The references will not be touched, for now.

DG> Other than that, the directive looks great!

>> Please review the code and check it in if you consider it worthy.

DG> Better yet, I'll add you as a developer and let you check it in
DG> yourself.  Let's hash out the issues raised above though.  The
DG> reference issue (third) can be ignored for now.  The table of contents
DG> interaction (second issue) must be dealt with.  And we should at least
DG> decide which attributes could be useful, and which should be tossed
DG> (first issue).

  The TOC issue is half-solved: we still need to decide if the current
way to specify pending operation priorities is sufficient. As for the
attributes: :depth: is implemented, :enum: is planned to be
implemented soon, and that's all. Right?

DG> On a related note, the small patch to test/package_unittest.py (which
DG> we discussed off-list) inspired me to finally fix this bug:

DG>     - Fix tests to run standalone.  I.e., allow::
    
DG>           cd test/test_rst
DG>           test_inline_markup.py
    
DG>       Raises an exception with path processing on GNU/Linux (but only
DG>       sometimes???).

  Well, in fact, the os.getcwd() fix was not correct - I proposed it
without actual testing. The version I checked in today has a different
fix, with some comments added - hope it works fine.

-- 
Best regards,
 Dmitry                            mailto:yole@yole.ru



From goodger@users.sourceforge.net  Mon Aug 12 05:55:47 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Mon, 12 Aug 2002 00:55:47 -0400
Subject: [Doc-SIG] numbered headings in reST
In-Reply-To: <182178667059.20020812000311@yole.ru>
Message-ID: <B97CB812.27161%goodger@users.sourceforge.net>

[David]
>> Perhaps there should be some way to control the enumeration
>> sequences? For example, in a long document chapters are usually
>> numbered, but appendices use letters (A, B, C, ...).  Perhaps
>> multiple "sectnum" directives could exist, each specifying the
>> style of the remainder of the document.  So just before the first
>> appendix, there could be a ".. sectnum:: :enum: A" directive.
>> Should this apply only to the first part of the section number, or
>> should each part be adjustable?  Of course, this doesn't have to be
>> implemented now; we can add it to the to-do list until someone
>> actually needs it.

[Dmitry]
> This is also a good idea, and I'd like to implement it soon. I think
> that it's enough to configure only the first part of the number;
> I don't see a clear syntax that will allow configuring all parts.
> After all, if some non-trivial numbering is needed, one could just
> write the numbers by hand.

Fair enough.  If you implement it, I think the attribute should be
called "start", not "enum".  It will specify the sequence set to use
at the same time as the starting value.  For example::

    .. sectnum: :start: 1
    
    .. sectnum: :start: A
    
    .. sectnum: :start: 5
    
    .. sectnum: :start: I

The first one is the default: start at 1, numbered.  The second one
specifies letters, and start at "A".  The third specifies numbers,
start at 5.  The last example could signal Roman numerals, although I
don't know if they'd be applicable here.  Enumerated lists already do
all this; perhaps that code could be reused.

Here comes the tricky part.  I'd expect to be able to use the
"sectnum" directive multiple times in a single document.  For example,
in a long document with "chapter" and "appendix" sections, there's be
a second "sectnum" before the first appendix, changing the sequence
used (from 1,2,3... to A,B,C...).  This is where the "local" concept
comes in.  This part of the implementation can be left for later.

>> The second issue is the interaction of "sectnum" with the
>> "contents" directive.  Try processing a document with both
>> directives; the order of the directives is significant.  If the
>> "contents" directive comes before "sectnum", the section numbers
>> are not reflected in the table of contents.  If "sectnum" comes
>> first, the section number do make it to the table of contents.
>> I've put examples on the web:
>>
>> - "contents" first: http://docutils.sourceforge.net/tools/test1.html
>> - "sectnum" first: http://docutils.sourceforge.net/tools/test2.html
>>
>> The reason for this is because the "sectnum" directive inserts a
>> ``pending`` element, which is fine.  The "contents" directive does
>> too.  Both are labeled "last reader", meaning they're both
>> triggered after the standard reader transforms are finished; a
>> simple scheduling mechanism.  But within "last reader", it's first
>> come, first served. Should we leave the behavior dependent on the
>> order of directives, or choose one and enforce it?  It would be
>> easy to enforce either order by labeling one of the ``pending``
>> elements as "first writer" instead of "last reader".
> 
> Well, now the directives are coupled even more, and so there must be
> a way to enforce correct processing order, and not make it the
> user's responsibility.

Agreed.  I think changing "contents" to a "first writer" transform
would be fine for now.  That way, "sectnum" always happens first.

> Also, the "sectnum" directive has another dependency: it must run
> after the DocTitle transform. This works correctly now, but maybe it
> should somehow be made explicit.
> 
> What do you think of introducing a numeric priority system for
> pending operations? Is this over-design? I think that we may
> encounter more cases of transform order dependencies later, and the
> current four-level system may not be enough.

I thought about a priority system too.  I think it's too early to say.
We don't quite need it yet, so let's hold off until we do.  I'll add
it to the to-do list though.  For now, documentation should be enough.

>> It's clear that the ``pending`` elements need to be documented:
>> what they're used for and when they're triggered ("first reader",
>> "last writer", etc.).
> 
> Frankly speaking, I still haven't found the code that triggers
> the "pending" elements and handles all the "first reader" stuff. :-)
> So I'd appreciate more documentation on that issue very much.

It's in ``docutils/transforms/universal.py``, from the ``Pending``
class to the end.  ``docutils.nodes.pending`` explains how the
``pending`` node works; I'll add some cross-references.

>> Notice the table of contents in the test2.html document.  Currently
>> it looks something like this::
>>
>>     * 1. Structural Elements
>>       - 1.1. Section Title
>>       - 1.2. Transitions
>>     * 2. Body Elements
>>       - 2.1. Paragraphs
>>
>> I think it should look like this (perhaps with extra indentation)::
>>
>>     1. Structural Elements
>>     1.1. Section Title
>>     1.2. Transitions
>>     2. Body Elements
>>     2.1. Paragraphs
>>
>> An alternative could look like this::
>>
>>     1. Structural Elements
>>        1. Section Title
>>        2. Transitions
>>     2. Body Elements
>>        1. Paragraphs
>>
>> To enable a different type of table of contents, the section titles
>> should have an extra attribute, such as "auto".
> 
> In the version that I checked in today, that is also implemented.

I see that.  It's not exactly what I had in mind though.  It will be
easier for me to fix it than explain what I mean, so I'll handle it.

> I haven't found a DTD element that would be formatted as a plain
> list of strings with no paragraph breaks between them. ...
> Therefore, the contents for auto-numbered sections is now generated
> as an enumerated list.

I think the current bullet list structure is adequate; what's
necessary is some context recognition in the writer.

> This looks pretty nice, with one exception: the HTML writer doesn't
> support prefixes for enumerated lists. Thus, the table of contents
> in HTML looks as your second alternative, and not the first one
> (which is what I would like to achieve).
>
> Do you have any ideas on implementing the prefixes for enumerated
> lists in HTML? I would really like to have this fixed.

CSS2 might be able to handle that, but I don't think we need to go
that route.  Simpler is better, especially since CSS2 support is
spotty.  Adding some more smarts to the HTML writer should solve it.
I'll take care of this also.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From goodger@users.sourceforge.net  Tue Aug 13 02:17:30 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Mon, 12 Aug 2002 21:17:30 -0400
Subject: [Doc-SIG] numbered headings in reST
In-Reply-To: <B97CB812.27161%goodger@users.sourceforge.net>
Message-ID: <B97DD669.2725B%goodger@users.sourceforge.net>

[David]
>>> To enable a different type of table of contents, the section titles
>>> should have an extra attribute, such as "auto".

[Dmitry]
>> In the version that I checked in today, that is also implemented.

[David]
> I see that.  It's not exactly what I had in mind though.  It will be
> easier for me to fix it than explain what I mean, so I'll handle it.
>
>> I haven't found a DTD element that would be formatted as a plain
>> list of strings with no paragraph breaks between them. ...
>> Therefore, the contents for auto-numbered sections is now generated
>> as an enumerated list.
> 
> I think the current bullet list structure is adequate; what's
> necessary is some context recognition in the writer.
> 
>> This looks pretty nice, with one exception: the HTML writer doesn't
>> support prefixes for enumerated lists. Thus, the table of contents
>> in HTML looks as your second alternative, and not the first one
>> (which is what I would like to achieve).
>>
>> Do you have any ideas on implementing the prefixes for enumerated
>> lists in HTML? I would really like to have this fixed.
> 
> CSS2 might be able to handle that, but I don't think we need to go
> that route.  Simpler is better, especially since CSS2 support is
> spotty.  Adding some more smarts to the HTML writer should solve it.
> I'll take care of this also.

I've reworked the "sectnum" directive & transform.  Here's how:

* Changed the "contents" directive to produce a "first writer"
  transform.  Now there's no order issues.

* Moved most of the ``docutils.parsers.rst.directives.parts.sectnum()``
  docstring to the documentation:
  
http://docutils.sf.net/spec/rst/directives.html#automatic-section-numbering

* Reworked the ``docutils.transforms.parts.SectNum`` transform's
  ``update_section_numbers()`` method:

  - Simplified calling the method (default parameter values).

  - Removed the "autonum_origtitle" and "autonum_prefix" attributes
    from "section" elements: unnecessarily redundant.  Instead, the
    "title" elements get an "auto" attribute.

  - The section number text is inserted into the title, wrapped in a
    ``<generated class="sectnum">`` element.  We don't actually use
    this yet, but it could be used this to remove the generated text
    if we need to.

* Reworked the ``docutils.transforms.parts.Contents`` transform's
  ``build_contents()`` method:

  - It turns out that we don't need to build enumerated lists; we
    continue to build bullet lists as before.

  - If an "auto" attribute is detected in a title, we add a
    ``class="auto-toc"`` attribute to the bullet list.

  - The generated text is left alone; there's no need to remove it.

* This style makes the bullets invisible::

      ul.auto-toc {
        list-style-type: none }

Take a look at the results:
http://docutils.sf.net/tools/test.html#table-of-contents

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From goodger@users.sourceforge.net  Fri Aug 16 02:00:03 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 15 Aug 2002 21:00:03 -0400
Subject: [Doc-SIG] enumerated list item parsing fixed
Message-ID: <B981C6D2.2752F%goodger@users.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 one
      =====================================

- 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  <goodger@users.sourceforge.net>  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/



From goodger@users.sourceforge.net  Sat Aug 24 02:40:55 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Fri, 23 Aug 2002 21:40:55 -0400
Subject: [Doc-SIG] "The Docutils Document Tree"
Message-ID: <B98C5C66.27BB5%goodger@users.sourceforge.net>

There's been a lot of progress on "The Docutils Document Tree" lately.
See http://docutils.sf.net/spec/doctree.html.  There are 55 DTD
elements left to describe; I'd appreciate any help I can get.
Proofreading, editing, or writing; even one element section would be
great!

-- 
David Goodger  <goodger@users.sourceforge.net>  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/



From goodger@users.sourceforge.net  Fri Aug 30 05:23:15 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Fri, 30 Aug 2002 00:23:15 -0400
Subject: [Doc-SIG] ANN: New PEP Format: reStructuredText
Message-ID: <B9946B72.28293%goodger@users.sourceforge.net>

With many thanks to Barry Warsaw for his help and patience, I am
pleased to announce that a new format for PEPs (Python Enhancement
Proposals) has been deployed.  The new format is reStructuredText, a
lightweight what-you-see-is-what-you-get plaintext markup syntax and
parser component of the Docutils project.  From the new PEP 12:

    ReStructuredText is offered as an alternative to plaintext PEPs,
    to allow PEP authors more functionality and expressivity, while
    maintaining easy readability in the source text.  The processed
    HTML form makes the functionality accessible to readers: live
    hyperlinks, styled text, tables, images, and automatic tables of
    contents, among other advantages.

The following PEPs have been marked up with reStructuredText:

- PEP 12 -- Sample reStructuredText PEP Template
  (http://www.python.org/peps/pep-0012.html)

- PEP 256 -- Docstring Processing System Framework
  (http://www.python.org/peps/pep-0256.html)

- PEP 257 -- Docstring Conventions
  (http://www.python.org/peps/pep-0257.html)

- PEP 258 -- Docutils Design Specification
  (http://www.python.org/peps/pep-0258.html)

- PEP 287 -- reStructuredText Docstring Format
  (http://www.python.org/peps/pep-0287.html)

- PEP 290 -- Code Migration and Modernization
  (http://www.python.org/peps/pep-0290.html)

In addition, the text of PEP 1 and PEP 9 has been revised.

Authors of new PEPs are invited to consider using the new format, and
authors of existing PEPs are invited to convert their PEPs to
reStructuredText to take advantage of the many enhancements over the
plaintext format.  I, along with the other Docutils developers and
users, will be happy to assist.  Please send questions to:

    docutils-users@lists.sourceforge.net

The latest project snapshot can always be downloaded from:

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

(This is required to process the PEP source into HTML.  It requires
at least Python 2.0; Python 2.1 or later is recommended.)

Docutils and reStructuredText are under active development.  Input is
very welcome, especially HTML rendering/stylesheet issues with
different browsers.  We welcome new contributors.  If you'd like to
get involved, please visit:

    http://docutils.sourceforge.net/

-- 
David Goodger  <goodger@users.sourceforge.net>  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/