From fdrake@acm.org  Fri Feb  2 15:48:27 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 2 Feb 2001 10:48:27 -0500 (EST)
Subject: [Doc-SIG] Doc tree frozen for 2.1a2
Message-ID: <14970.54987.29292.178440@cj42289-a.reston1.va.home.com>

  The Doc/ tree in the Python CVS is frozen until Python 2.1a2 has
been released.  No further changes should be made in that part of the
tree.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations



From fdrake@acm.org  Fri Feb  2 17:56:27 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 2 Feb 2001 12:56:27 -0500 (EST)
Subject: [Doc-SIG] Python 2.1 alpha 2 docs released
Message-ID: <14970.62667.518807.370544@cj42289-a.reston1.va.home.com>

  The documentation for the Python 2.1 alpha 2 release is now
available.  View it online at:

	http://python.sourceforge.net/devel-docs/

(This version will be updated as the documentation evolves, so will
be updated beyond what's in the downloadable packages.)
  Downloadable packages in many formats are also available at:

	ftp://ftp.python.org/pub/python/doc/2.1a2/

  Please avoid printing this documentation -- it's for the alpha, and
could waste entire forests!
  Thanks to everyone who has helped improve the documentation!  As
always, suggestions and bug reports are welcome.  For more
instructions on how to file bug reports and where to send suggestions
for improvement, see:

	http://python.sourceforge.net/devel-docs/about.html


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations



From tony@lsl.co.uk  Thu Feb  8 12:41:02 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 8 Feb 2001 12:41:02 -0000
Subject: [Doc-SIG] Pre-alpha release of docutils
Message-ID: <001b01c091cc$652344e0$f05aa8c0@lslp7o.int.lsl.co.uk>

Well, I took Tuesday off as holiday to work on docutils, on the grounds
that my since-the-new-year work rate of about an hour a week on it was
getting, well, nowhere, and thus I can now announce:

	The very first very pre-alpha release 0.0.1 of docutils

The current status of the code is documented at:

	http://www.tibsnjoan.co.uk/docutils/status.html
	http://www.tibsnjoan.demon.co.uk/docutils/status.html
	http://homepage.ntlworld.com/tibsnjoan/docutils/status.html

(technically, those first two should be the same place, but I know
there's been trouble with that first URL in the past).

That page also includes information on downloading the code (well, the
current snapshot of my "working" directory). Note that the "Structured
Text for Python docstrings" page is now moved to be in the same
directory - so if you care, please adjust your bookmarks appropriately
(it's referenced from the "status" page).

What does it do? Well, it will read a Python file and output its
docstrings as not-terribly-good HTML, and it will also read a
StructuredText file and output that as similar quality HTML. There's a
detailed checklist of exactly which bits of ST it supports in the
"status" document, but it does enough to be potentially useful (although
it's not very fast).

The reason I'm still calling it "pre-alpha" is that I want to do a
significant code rewrite of the main innards - but on the other hand, if
I waited until that was finished, I probably wouldn't be releasing
anything until at least a month away.

As normal, all comments are welcomed. But I already know that the
docstrings are often wrong...

Tibs

Postcript: Damn, checking the output of stpy.py when run on
Colourise.py, I see there's a major bug in (at least some) list items -
it's dropping all but the first line (see, for instance, the Module
documentation). It's probably something very stupid, and I don't have
time to look at it right now, so I might as well announce this stuff
anyway, and I'll try to look at it this evening. Ho hum.

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From tony@lsl.co.uk  Mon Feb 12 11:59:51 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 12 Feb 2001 11:59:51 -0000
Subject: [Doc-SIG] More on docutils
In-Reply-To: <001b01c091cc$652344e0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <005201c094eb$4deb1010$f05aa8c0@lslp7o.int.lsl.co.uk>

Well, there are also some serious (stupid) problems with the
amalgamating of literal paragraphs (i.e., the subparagraphs of a
paragraph ending in '::') in the "old form" docutils code.

As it turned out, I spent some time over the weekend working on the code
rewrite - it's just too frustrating to try to work on the old code when
the new code is already cooking in my head. Not to mention embarassing.

*Unfortunately*, the floppy I brought in to work this morning only had
Friday evening's (well, Saturday morning's) version of DocNodes.py,
which is significantly out-of-date with respect to the end of Sunday.
I'll try to bring in a current version tomorrow and upload it (my modem
connection at home is, well, flaky).

As a taster, DocNodes.py already has the following:

* paragraph splitting, including at list items
* support for '::' literal paragraphs (which *appears to work*)
* support for '>>>' Python paragraphs
* much simpler object model, much simpler internal tree structure,
generally less faffing around
* much better docstrings
* docstrings include doctest "code", and the module is being written to
use doctest for self-testing (and yes, this is both fun (hmm, running
code that parses the text that includes the result of the parse - nice
stuff) and makes it easier to test)

It should rapidly (erm, remember this is Glacial Software Development
Unlimited, when interpreting that word) gain:

* support for list items

shortly to be followed by

* paragraph markup
* output to DOM tree

and so on, bringing it back to where the "old" code was, but (heh heh)
working this time...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Feet first on 3 wheels...
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From tony@lsl.co.uk  Tue Feb 13 12:58:05 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 13 Feb 2001 12:58:05 -0000
Subject: [Doc-SIG] docutils - DocNodes.py
In-Reply-To: <005201c094eb$4deb1010$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <007701c095bc$9b67df40$f05aa8c0@lslp7o.int.lsl.co.uk>

I've now uploaded DocNodes.py to both servers (although not updated the
documentation page to point to it yet). Try one of:

	http://www.tibsnjoan.co.uk/docutils/DocNodes.py
	http://www.ntlworld.com/~tibsnjoan/docutils/DocNodes.py

I didn't have any more time to spend on it last night, so the status is
still as before. This means about all you can do with it is run the self
tests, and look at the output.

More later in the week.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Feet first on 3 wheels...
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From fdrake@users.sourceforge.net  Wed Feb 14 21:04:29 2001
From: fdrake@users.sourceforge.net (Fred L. Drake)
Date: Wed, 14 Feb 2001 13:04:29 -0800
Subject: [Doc-SIG] [development doc updates]
Message-ID: <E14T96D-0002tb-00@usw-pr-web1-f.sourceforge.net>

The development version of the documentation has been updated:

	http://python.sourceforge.net/devel-docs/




From mwh21@cam.ac.uk  Mon Feb 19 13:05:45 2001
From: mwh21@cam.ac.uk (Michael Hudson)
Date: Mon, 19 Feb 2001 13:05:45 +0000 (GMT)
Subject: [Doc-SIG] A draft for a "defining new types" chapter for ext.tex
Message-ID: <Pine.LNX.4.10.10102191257110.937-100000@localhost.localdomain>

After various people noticing that there is no documentation at all for
defining new types for python in the standard docs I set to work:

http://www-jcsu.jesus.cam.ac.uk/~mwh21/hacks/ext/defining-new-types.html

It's not even nearly finished; I would like to add sections on supporting
GC, coercion, rich comparisons &c (partly because documenting such things
would force me to learn about them!).  But I would like to see what people
think.

It strikes me that

(a) to define a new type really you need to understand how Python is
    implemented.  So perhaps I should write a Python-Internals-HOWTO
    first.
(b) The Extending and Embedding Manual could really do with being entirely
    rewritten.
(c) It's hard to think of a sensible order to write such a thing in
    without lots of circular dependencies (of the form you need to read
    chapter I to understand chapter II, but to understand chapter I you
    need to have read chapter III which requires understanding chapter
    II...).

Anybody got some spare-time-in-a-tin?

Cheers,
M.



From fdrake@acm.org  Mon Feb 19 14:06:02 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 19 Feb 2001 09:06:02 -0500 (EST)
Subject: [Doc-SIG] A draft for a "defining new types" chapter for ext.tex
In-Reply-To: <Pine.LNX.4.10.10102191257110.937-100000@localhost.localdomain>
References: <Pine.LNX.4.10.10102191257110.937-100000@localhost.localdomain>
Message-ID: <14993.10314.859082.458595@cj42289-a.reston1.va.home.com>

Michael Hudson writes:
 > After various people noticing that there is no documentation at all for
 > defining new types for python in the standard docs I set to work:
 > 
 > http://www-jcsu.jesus.cam.ac.uk/~mwh21/hacks/ext/defining-new-types.html

  I'll take a look at this; hopefully later today.  Do I have
permission to integrate this into the existing documentation?

 > It's not even nearly finished; I would like to add sections on supporting
 > GC, coercion, rich comparisons &c (partly because documenting such things
 > would force me to learn about them!).  But I would like to see what people
 > think.

  I have some text from Neil Schemenauer on adding GC support to
objects; I'll try and integrate that before the upcoming beta.

 > (a) to define a new type really you need to understand how Python is
 >     implemented.  So perhaps I should write a Python-Internals-HOWTO
 >     first.

  That might even reasonably be part of the Extending & Embedding
manual, given the necessity of understanding the material.  If you
write it, it's pretty much your call where it goes.

 > (b) The Extending and Embedding Manual could really do with being entirely
 >     rewritten.

  Yep!

 > (c) It's hard to think of a sensible order to write such a thing in
 >     without lots of circular dependencies (of the form you need to read
 >     chapter I to understand chapter II, but to understand chapter I you
 >     need to have read chapter III which requires understanding chapter
 >     II...).

  Sure!  It'll open when my kids are on there own, so it will be a
while before it's available.  ;-)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations



From mwh21@cam.ac.uk  Mon Feb 19 14:21:56 2001
From: mwh21@cam.ac.uk (Michael Hudson)
Date: Mon, 19 Feb 2001 14:21:56 +0000 (GMT)
Subject: [Doc-SIG] A draft for a "defining new types" chapter for ext.tex
In-Reply-To: <14993.10314.859082.458595@cj42289-a.reston1.va.home.com>
Message-ID: <Pine.LNX.4.10.10102191415540.937-100000@localhost.localdomain>

On Mon, 19 Feb 2001, Fred L. Drake, Jr. wrote:

> 
> Michael Hudson writes:
>  > After various people noticing that there is no documentation at all for
>  > defining new types for python in the standard docs I set to work:
>  > 
>  > http://www-jcsu.jesus.cam.ac.uk/~mwh21/hacks/ext/defining-new-types.html
> 
>   I'll take a look at this; hopefully later today.  Do I have
> permission to integrate this into the existing documentation?

By all means; I was going to submit it as a patch when I'd got some more
done.  But if you like what's there, go for it.  

I would probably be easier if I sent you the Tex, too...

>  > It's not even nearly finished; I would like to add sections on supporting
>  > GC, coercion, rich comparisons &c (partly because documenting such things
>  > would force me to learn about them!).  But I would like to see what people
>  > think.
> 
>   I have some text from Neil Schemenauer on adding GC support to
> objects; I'll try and integrate that before the upcoming beta.

That'd be cool.

>  > (a) to define a new type really you need to understand how Python is
>  >     implemented.  So perhaps I should write a Python-Internals-HOWTO
>  >     first.
> 
>   That might even reasonably be part of the Extending & Embedding
> manual, given the necessity of understanding the material.  If you
> write it, it's pretty much your call where it goes.

OK.  I'll see what I come up with, and when.

>  > (b) The Extending and Embedding Manual could really do with being entirely
>  >     rewritten.
> 
>   Yep!

I even thought about replying to one of those "write a book about Python
for us" posts on clpy with the suggestion of a Python internals book, but
then I thought I'd better worry about passing this year...

>  > (c) It's hard to think of a sensible order to write such a thing in
>  >     without lots of circular dependencies (of the form you need to read
>  >     chapter I to understand chapter II, but to understand chapter I you
>  >     need to have read chapter III which requires understanding chapter
>  >     II...).
> 
>   Sure!  It'll open when my kids are on there own, so it will be a
> while before it's available.  ;-)

Don't have that time-sink yet...

Cheers,
M.



From fdrake@acm.org  Mon Feb 19 14:41:58 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 19 Feb 2001 09:41:58 -0500 (EST)
Subject: [Doc-SIG] A draft for a "defining new types" chapter for ext.tex
In-Reply-To: <Pine.LNX.4.10.10102191415540.937-100000@localhost.localdomain>
References: <14993.10314.859082.458595@cj42289-a.reston1.va.home.com>
 <Pine.LNX.4.10.10102191415540.937-100000@localhost.localdomain>
Message-ID: <14993.12470.365566.970433@cj42289-a.reston1.va.home.com>

Michael Hudson writes:
 > By all means; I was going to submit it as a patch when I'd got some more
 > done.  But if you like what's there, go for it.  

  Thanks!

 > I would probably be easier if I sent you the Tex, too...

  That certainly would make it easier.  ;-)

 > I even thought about replying to one of those "write a book about Python
 > for us" posts on clpy with the suggestion of a Python internals book, but
 > then I thought I'd better worry about passing this year...

  Don't know if that would attract a large enough audiance to interest
publishers, but I'd pick up a copy just for fun.  ;)


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Digital Creations



From fdrake@users.sourceforge.net  Mon Feb 19 16:50:52 2001
From: fdrake@users.sourceforge.net (Fred L. Drake)
Date: Mon, 19 Feb 2001 08:50:52 -0800
Subject: [Doc-SIG] [development doc updates]
Message-ID: <E14UtWW-0005Ux-00@usw-pr-web1-f.sourceforge.net>

The development version of the documentation has been updated:

	http://python.sourceforge.net/devel-docs/




From tony@lsl.co.uk  Thu Feb 22 15:05:07 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 22 Feb 2001 15:05:07 -0000
Subject: [Doc-SIG] docutils 0.0.2 ("are we there yet?")
In-Reply-To: <14993.12470.365566.970433@cj42289-a.reston1.va.home.com>
Message-ID: <001f01c09ce0$d7b27ca0$f05aa8c0@lslp7o.int.lsl.co.uk>

Things progress, albeit slowly.

I've just uploaded a new status document to:

	http://www.tibsnjoan.co.uk/docutils/status.html
	http://homepage.ntlworld.com/tibsnjoan/docutils/status.html

(the ntlworld URL I gave last time was, of course, hopelessly wrong...)

This announces release 0.0.2 ("are we there yet?"), which is a major
step backwards in that it doesn't *do* anything, and a major step
forwards in that I have now finished rewriting the structuring code, in
the form of DocNodes.py, which I am *much* less ashamed of (heh, it even
passes its doctest tests). Next to do is colourising/markup, and then
we'll be talking something useful (and I'm aiming for sometime next
week, so wish me luck).

All the best, Tibs
(developing half-an-hour here, an hour there, a stolen moment on the
quiet...)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From DanM@ActiveState.com  Fri Feb 23 01:35:59 2001
From: DanM@ActiveState.com (Dan Milgram)
Date: Thu, 22 Feb 2001 17:35:59 -0800
Subject: [Doc-SIG] Doc build question
Message-ID: <005401c09d38$f9685e70$c603a8c0@activestate.ca>

I'm having some difficulty simply building the html docs, and was hoping
someone could help me out as I am not familiar with LaTeX. All the docs
build ok, with the exception of the modindex.html files (they simply contain
the header and footer info but no actual index entries). I am using the
following relevant packages on a RedHat box:
    latex2html99.2beta8
    ActivePerl5.6
    tetex-1.0.6-11

Anyone else encountered this, or is there a particular environment variable
that I need to have set before the build? Any help would be greatly
appreciated.

Dan Milgram



From tony@lsl.co.uk  Mon Feb 26 10:24:24 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 26 Feb 2001 10:24:24 -0000
Subject: [Doc-SIG] docutils progress (again)
In-Reply-To: <001f01c09ce0$d7b27ca0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <001901c09fde$4a327230$f05aa8c0@lslp7o.int.lsl.co.uk>

OK - I've written TextNodes.py, which appears to succesfully colourise
(markup) text, with the same caveats as the old implementation (i.e., it
doesn't support nested markup).

Of course, that breaks the self-tests for DocNodes.py (since the
representation of a DocNode tries to show the content of its text), so
I've to fix that before releasing something.

Soon to follow - DOM tree generation...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From tony@lsl.co.uk  Mon Feb 26 14:18:15 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 26 Feb 2001 14:18:15 -0000
Subject: [Doc-SIG] docutils progress (again, again)
In-Reply-To: <001901c09fde$4a327230$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <001c01c09ffe$f57d8f10$f05aa8c0@lslp7o.int.lsl.co.uk>


Hmm - it looks like our internal email situation is still not entirely
fixed up - gods know where the *front* of that last message has gone...

What I've got filed as the message I wrote is as follows:

"""OK - I've written TextNodes.py, which appears to succesfully
colourise (markup) text, with the same caveats as the old implementation
(i.e., it doesn't support nested markup).

Of course, that breaks the self-tests for DocNodes.py (since the
representation of a DocNode tries to show the content of its text), so
I've to fix that before releasing something.

Soon to follow - DOM tree generation...
"""

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow t



From tony@lsl.co.uk  Tue Feb 27 14:27:06 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 27 Feb 2001 14:27:06 -0000
Subject: [Doc-SIG] docutils 0.0.3 ("maybe soon")
In-Reply-To: <001f01c09ce0$d7b27ca0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <003301c0a0c9$5c577500$f05aa8c0@lslp7o.int.lsl.co.uk>

Just an incremental update.

See
	http://www.tibsnjoan.co.uk/docutils/status.html
http://homepage.ntlworld.com/tibsnjoan/docutils/status.html

for information (those *should* now be the same page).

This now supplies colourising (only single level, as before), via
TextNodes.py. The self-tests appear to work again. Still no output. Next
on to DOM trees, and then integration back into the command line app.

(BTW: Note that we will be terminating our Demon account in the not too
distant future (no problem, just we don't use anything that makes it
worth paying for), which means that
	http://www.tibsnjoan.demon.co.uk/docutils/status.html
will go away then, so please amend any bookmarks.)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)