From fdrake@users.sourceforge.net  Thu Dec  7 06:26:54 2000
From: fdrake@users.sourceforge.net (Fred L. Drake)
Date: Wed, 6 Dec 2000 22:26:54 -0800
Subject: [Doc-SIG] [development doc updates]
Message-ID: <200012070626.WAA22103@orbital.p.sourceforge.net>

The development version of the documentation has been updated:

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


Lots of small changes, but most important, more DOM documentation:

	http://python.sourceforge.net/devel-docs/lib/module-xml.dom.html


From mwh21@cam.ac.uk  Thu Dec  7 14:35:24 2000
From: mwh21@cam.ac.uk (Michael Hudson)
Date: Thu, 7 Dec 2000 14:35:24 +0000 (GMT)
Subject: [Doc-SIG] latex2html
Message-ID: <Pine.LNX.4.10.10012071431440.28885-100000@localhost.localdomain>

My installation of latex2html seems to have withered and died (like,
gosh).

What's the current blessed version and where can I get it from? 

Much thanks in advance!
M.

Grumble, grumble, all software sucks, etc.



From fdrake@acm.org  Thu Dec  7 14:49:23 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Thu, 7 Dec 2000 09:49:23 -0500 (EST)
Subject: [Doc-SIG] latex2html
In-Reply-To: <Pine.LNX.4.10.10012071431440.28885-100000@localhost.localdomain>
References: <Pine.LNX.4.10.10012071431440.28885-100000@localhost.localdomain>
Message-ID: <14895.41843.602777.109203@cj42289-a.reston1.va.home.com>

Michael Hudson writes:
 > My installation of latex2html seems to have withered and died (like,
 > gosh).

  LaTeX2HTML tends to do that, unfortunately.

 > What's the current blessed version and where can I get it from? 

  I'm using 99.2b8 with Perl 5.6.  LaTeX2HTML should still be
available at http://saftsack.fs.uni-bayreuth.de/~latex2ht/current/.


  -Fred

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



From mwh21@cam.ac.uk  Thu Dec  7 16:03:02 2000
From: mwh21@cam.ac.uk (Michael Hudson)
Date: Thu, 7 Dec 2000 16:03:02 +0000 (GMT)
Subject: [Doc-SIG] latex2html
In-Reply-To: <14895.41843.602777.109203@cj42289-a.reston1.va.home.com>
Message-ID: <Pine.LNX.4.10.10012071600150.28885-100000@localhost.localdomain>

On Thu, 7 Dec 2000, Fred L. Drake, Jr. wrote:

> Michael Hudson writes:
>  > My installation of latex2html seems to have withered and died (like,
>  > gosh).
> 
>   LaTeX2HTML tends to do that, unfortunately.

No kidding!  This release seems to install html.sty in the same place as
the last one - which is something new, at least.

>  > What's the current blessed version and where can I get it from? 
> 
>   I'm using 99.2b8 with Perl 5.6.  LaTeX2HTML should still be
> available at http://saftsack.fs.uni-bayreuth.de/~latex2ht/current/.

Right, this now seems to be working (after I tracked down netpbm).

Thanks!

It has to be said the trailer to the "make install", where it says:

Done. Have a lot of fun with LaTeX2HTML!

just makes me want to hit something.  "I didn't mean that sort of fun!"

Cheers,
M.



From fdrake@acm.org  Thu Dec  7 16:03:11 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Thu, 7 Dec 2000 11:03:11 -0500 (EST)
Subject: [Doc-SIG] latex2html
In-Reply-To: <Pine.LNX.4.10.10012071600150.28885-100000@localhost.localdomain>
References: <14895.41843.602777.109203@cj42289-a.reston1.va.home.com>
 <Pine.LNX.4.10.10012071600150.28885-100000@localhost.localdomain>
Message-ID: <14895.46271.962791.905252@cj42289-a.reston1.va.home.com>

Michael Hudson writes:
 > just makes me want to hit something.  "I didn't mean that sort of fun!"

  If you stopped yourself, you're a stronger man than I!


  -Fred

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



From tony@lsl.co.uk  Fri Dec  8 14:17:27 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 8 Dec 2000 14:17:27 -0000
Subject: [Doc-SIG] docutils status report 2
Message-ID: <000001c06121$98040830$f05aa8c0@lslp7o.int.lsl.co.uk>

Here is a further status report on the docutils work.

I currently have some code that will:

  1. Find the docstrings in a Python file (currently itself!)
  2. Split the text into paragraphs at blank lines.
  3. Identify lines within a paragraph that start like a list
     item, and split there as well - this allows::

         This is a paragraph.
         1. So is this
         fred -- and so is this

     to produce a paragraph and two lists.
  4. Partition list items up into lists (so that a "bare" <li> is
     actually a child of an <ol>, or whatever, to use HTML terms)
  5. Identify paragraphs starting ">>>" (allowing leading whitespace)
     as Python code (i.e., literal)
  6. Recognise bullet list items (as in ST - the use of "o" may go away
     following David's comments)
  7. Recognise numbered list items (but the final dot *is* required,
     otherwise 3 above will fail on::

        My favourite drink is tea, but also
        I like coffee

     (thinking the second line to have a Roman numeral at the start!)).
     Note that one won't be able to do::

        And the final number is
        1.

     without a spurious list, but I reckon we can live with that!
     (We have to pay for apparent simplicity with true complexity.)
  8. Recognise descriptive list items (note that markup is allowed in
     the "title" of the item, and I'm still hoping to get round to
     enabling::

        ' -- ' -- This is an awkward case

     (I forgot to tweak the RE yet)
  9. Recognise *emphasised* text, **strong** text and 'literal' text
     (but, except by "accident" nesting of markup does not work (well,
     you can't *nest* markup in literal, since it won't be seen!)).
     The emphasised and strong texts may contain any characters (except
     the terminating sequence, of course), and inline literals may
     contain anything but "'". Escaping characters is not yet addressed.
 10. Produce something that's getting close to a sensible DOM tree
     (the only issue is "paragraph within paragraph", which will be
     addressed in my documentation - see next week!).

That's not too dissimilar to what I reported last week, and indeed the
main thing that I've been working on is the "DOM"ising of the code,
including getting lists to nest themselves nicely (well, the code isn't
neat yet, but it works).

There's also been a fair amount of restructuring, part of which is why
the "::" recognition has gone away (don't worry, it's not away for
long).

As before, I'd rather not release code yet, but can if someone *really*
wants to take a look (damn, that sounds so, well, non-open-source).

Things to do next
-----------------
The task list (in no particular order) includes:

 A. Document the supported pyST syntax, so that David and company can
    haggle over the exact syntax that *should* be supported.

 B. Update the internal documentation.

 C. Add support for more markup (I've got a bare minimum for testing at
    the moment).

 D. Define what the command line interface is (i.e., how to specify that
    one wants to parse a file or package, what one wants the output to
    be, and so on.)

 E. Make nested markup work, so one can do::

        *This is **strong and 'literal'** text within emphasised*

I intend to do a little more implementation work (but not a lot) and
then attack task A, pyST syntax, aiming to have a document by the end of
next week. Cross fingers and I might still hit the "before Christmas"
release point...

Tibs
--
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 tony@lsl.co.uk  Fri Dec 15 16:58:55 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 15 Dec 2000 16:58:55 -0000
Subject: [Doc-SIG] docutils status report - STpy.html draft
Message-ID: <004401c066b8$4f1389b0$f05aa8c0@lslp7o.int.lsl.co.uk>

What with school and nursery concerts, office lunch, work dinner and the
imminent approach of Christmas exhaustion (oh, and "real" work as well,
mustn't forget that), I haven't had time to do any docutils programming
this week. However, I've got the *start* of some docutils
documentation - it's available at:

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

Note that it isn't finished - but it's probably already got enough in it
to comment on.

We'll see if the first version of docstring.py is *actually* finished
before my Christmas holiday (when I'll be incommunicado until the new
year) or not next week...

All the best, Tibs

--
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 Dec 18 16:41:10 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 18 Dec 2000 16:41:10 -0000
Subject: [Doc-SIG] docutils - STpy.html v0.2
In-Reply-To: <004401c066b8$4f1389b0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <005101c06911$53ae0d50$f05aa8c0@lslp7o.int.lsl.co.uk>

Version 0.2 of the Structured Text for Python docstrings document is now
available at the "normal" places:

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

This should be enough documentation to be going on with, I hope.
Apologies for the HTML - I was aiming for quick and legible, but not
necessarily pretty when viewed. Why the "big" browsers want so much
space after a "PRE" I can't figure out (but then, who can figure out why
they render as they do, anyway?).

The "spare time" I have left before the Christmas break (when I'm not
wrapping presents, nursing my cold, playing with the kids, eating my
mother-in-law's food, and so on) will now go into implementation - I
fear me that I may not make the self-imposed deadline of having
something useful released by the end of the week, but with luck I should
have a *little* time over the break to do some work.

Any comments welcomed, 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.)



From tony@lsl.co.uk  Tue Dec 19 10:18:30 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 19 Dec 2000 10:18:30 -0000
Subject: [Doc-SIG] docutils - STpy.html v0.2.1
In-Reply-To: <005101c06911$53ae0d50$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <000001c069a5$0900c6a0$f05aa8c0@lslp7o.int.lsl.co.uk>

OK - I had a chance to proofread last night (and almost all the
Christmas presents are now wrapped!), so some minor typos fixed, and
some slight reorganisation at:

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

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



From Edward Welbourne <eddy@chaos.org.uk>  Tue Dec 19 18:43:13 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Tue, 19 Dec 2000 18:43:13 +0000 (GMT)
Subject: [Doc-SIG] docutils status report
In-Reply-To: <00ae01c05ada$9f043f80$f05aa8c0@lslp7o.int.lsl.co.uk>
 (tony@lsl.co.uk)
References: <00ae01c05ada$9f043f80$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <m148RjF-00002HC@vortigen.demon.co.uk>

>   8. Recognise descriptive list items (note that markup is allowed in
>      the "title" of the item, so one can do::
>
>         ' -- ' -- This is an awkward case

but, for all that, a necessary one.  Consider, for instance, the
docstring of a function called main which parses the command-line of a
program which supports, among other things, some --long-style flags; the
doc-string will need to use the flags as keys in a descriptive list !

Meanwhile, consider (e.g.) a function whose docstring lists the ways a
line can start a list item, in which one might say:

   1. -- ordered list (using arabic numerals)
   I. -- ordered list (using uppercase roman numerals)
   i. -- ordered list (using lowercase roman numerals)
   a. -- ordered list (lowercase alphabetic lables)
   A. -- ordered list (uppercase alphabetic labels)
   o. -- `unordered' list, i.e. bulletted (unless preceded by list items a...n)

which, clearly, I want to see as a description list, not a very confused
ordered list.  Will that work ? and can I use `1)' and `a)' instead of
`1.' and `a.' ? (as lead-in to list items)

	Eddy.


From tony@lsl.co.uk  Wed Dec 20 08:59:32 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 20 Dec 2000 08:59:32 -0000
Subject: [Doc-SIG] docutils status report
In-Reply-To: <m148RjF-00002HC@vortigen.demon.co.uk>
Message-ID: <000601c06a63$2b190360$f05aa8c0@lslp7o.int.lsl.co.uk>

Edward Welbourne wrote:
> But not as slowly as LSL's tools update program ...

Ooh - cutting! At least we did upgrade eventually (and both Bill and
Graham were quite enthusiastic about it). Some day we'll have to
consider 2.0...

> >         ' -- ' -- This is an awkward case
> but, for all that, a necessary one.

Well, yes.

It is also easy enough to do with regular expressions - one just makes
the descriptive case allow the literal markup case to occur in its title
(and, of course, finds lists before markup!)

> Meanwhile, consider (e.g.) a function whose docstring lists
> the ways a line can start a list item, in which one might say:
>
>    1. -- ordered list (using arabic numerals)
...etc...
> which, clearly, I want to see as a description list, not a
> very confused ordered list.  Will that work ?

That will work because descriptive lists are (very deliberately) looked
for before the other sorts of list, to cope with exactly that sort of
point.

> and can I use `1)' and `a)' instead of
> `1.' and `a.' ? (as lead-in to list items)

No. Not for any greatly fundamental reason, but because it's not in the
original definition(s) of ST[NG]. This is the sort of thing people could
ask for as an "enhancement" - I can't (off the top of my head, and with
no great depth of thought) see why it shouldn't be able to work.

(There are, of course, classes of things one *can't* do with
ST<variants> - not least because they use symmetrical start/end tags.
But the system is surprisingly flexible.)

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




From tony@lsl.co.uk  Wed Dec 20 09:22:48 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 20 Dec 2000 09:22:48 -0000
Subject: [Doc-SIG] docutils - STpy.html v0.2.2
In-Reply-To: <000001c069a5$0900c6a0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <000701c06a66$6b88f4c0$f05aa8c0@lslp7o.int.lsl.co.uk>

I'm not very good at leaving documentation to sit. This new version has
an amendment to how '>>>' blocks are indented, and (more importantly) a
proposal to use "unused" indentation to indicate *actual* indentation (a
la "blockquote" in HTML), so that (for instance)::

   This is the first paragraph.

      This is the second paragraph.

where the indentation of the second paragraph doesn't "mean" anything
terribly useful, would be rendered (in HTML) as::

   <p>This is the first paragraph</p>
   <blockquote>
      <p>This is the second paragraph</p>
   </blockquote>

instead of the rather meaningless (but obvious) default::

   <p>This is the first paragraph
      <p>This is the second paragraph</p>
   </p>

(yes, I know that isn't legal HTML). I'd meant to put this into the
first version of the documentation, but clean forgot (so it isn't
something cooked up "suddenly" - it's more an obvious follow-on from
trying to use a DOM tree to store the data).

The URLs are still:

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

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Are we there yet?
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From Edward Welbourne <eddy@chaos.org.uk>  Fri Dec 22 14:55:21 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Fri, 22 Dec 2000 14:55:21 +0000 (GMT)
Subject: [Doc-SIG] docutils status report
In-Reply-To: <000601c06a63$2b190360$f05aa8c0@lslp7o.int.lsl.co.uk>
 (tony@lsl.co.uk)
References: <000601c06a63$2b190360$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <m149TbN-00000wC@vortigen.demon.co.uk>

>> and can I use `1)' and `a)' instead of
>> `1.' and `a.' ? (as lead-in to list items)
> No. Not for any greatly fundamental reason, but because it's not in
> the original definition(s) of ST[NG].
hasty addendum:

not that I want anyone to bodge the tool into supporting 1) style as
well as 1., I just haven't yet found time to catch up with the flood of
mail on this thread, let alone the web pages (yes, I still connect (from
home) via a dial-up modem on the end of a piece of salty string), so
didn't know whether I'd caught on correctly to the bit to which I
responded; and, of course, I need to know how to mark up my doc strings ...

I'm far more interested in getting a Yes answer to
> Are we there yet?
than in being able to engage in personal-taste deviancies.

God Yul, and keep up the good work,

	Eddy.
--
				...   Few indeed are those who, travelling
it, have crossed the dark and yawning Abyss of Implementation to Delivery.
Many, yea, many in truth stagnate yet in the Desert of Delay, or linger ever
in the ghastly limbo called Perpetual Beta.	(from the LOGINATAKA)