From fdrake@acm.org  Wed Mar  1 21:26:24 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 1 Mar 2000 16:26:24 -0500 (EST)
Subject: [Doc-SIG] Forthcoming doc release; request for help
In-Reply-To: <NDBBJAKILMEBBFEDCMKKGEGHCBAA.willguaraldi@mediaone.net>
References: <14523.599.24651.207764@weyr.cnri.reston.va.us>
 <NDBBJAKILMEBBFEDCMKKGEGHCBAA.willguaraldi@mediaone.net>
Message-ID: <14525.35584.396141.954973@weyr.cnri.reston.va.us>

  For everyone:  I've posted new packages at:

	ftp://ftp.python.org/pub/python/doc/.test/

  This version is also online at:

	http://www.python.org/doc/1.5.2p2/

  A major, systematic navigational failure reported by Peter Funk has
been fixed, as well as a number of small fixes being integrated, and a 
note on the removal of multi-arg [].append has been added.

will writes:
 > how do you want us to relate "errors" back to you?  directly, or on
 > this list, or on another list, or bug-tracker?

  The bug tracker is probably the best, but python-docs@python.org is
good too.

 > i've been programming python for a while, but i would just gloss over
 > subtle python inconsistencies.  so i'll stare through the html code,
 > run it through the w3c validator (they do matching of tags and such

  I don't know that the HTML is good to look at; it definately shows
that it's generated!  The validator is a good idea.

 > which is useful), and tell my friends to sift through it with their
 > browsers.  (i know various folks at companies that do web-sites so
 > they have a lot of the browser/os/platform test-beds, i think).  i can

  I hope you're only asking people that don't mind checking this stuff 
for free!

 > beyond that, i'm running IE 5.0 on WinNT 4.0 and Win2000 and M13 on
 > WinNT 4.0 (which i haven't had that many problems with other than the
 > ui).

  Great!  Hopefully I'll manage to install M13 on my home machines
this weekend.

 > i've found a few problems with the code posted at the url.  lines 267
 > and 276 of .../lib/typesseq-strings.html  have stray unmatched <var>
 > and </var> tags.  looking at the web-page (not the html), it's in
 > section 2.1.5.2 Mutabe Sequence Types in the table.  you can actually
 > see two of the parens are in a var enclosure and shouldn't be.  9th
 > and 12th row, first column in the table under 2.1.5.2.

  I see -- this will be hard to fix, but I know where the problem is.
I'll see what I can do.
  For anyone here who really understands LaTeX2HTML's implementation
(there are so many people in that group! ;), the problem is this:  in
perl/python.perl:do_cmd_optional(), I need to be able to determine if
the current markup context include <var>.  If so, it needs to be
closed and re-opened (potentially along with other elements) to insert 
"unmolested" square brackets.  If anyone has any ideas on this, or a
patch to perl/python.perl, I'd love to hear from you!  ;)

 > also links on the modules and index pages turn up 404's.  i may untar
 > the tarball and see if i have the same problems.

  Try the new version, & let me know which specific links are broken
if that's still a problem.


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From fdrake@acm.org  Fri Mar  3 19:00:17 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 3 Mar 2000 14:00:17 -0500 (EST)
Subject: [Doc-SIG] Doc packages updated again...
Message-ID: <14528.3009.347163.590685@weyr.cnri.reston.va.us>

  The Global Module Index still isn't working, but I think the rest of 
the linking issues are dealt with.  Please let me know if that's not
the case!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From laurie@eh.org  Sun Mar  5 11:22:00 2000
From: laurie@eh.org (Laurence Tratt)
Date: Sun, 05 Mar 2000 11:22:00 GMT
Subject: [Doc-SIG] Some random thoughts
Message-ID: <98b87b9a49.laurie@btinternet.com>

Things have been a little quiet on here recently once again confirming the
doc-sigs yoyo nature; I sometimes wonder if people here are on a 3 month
hibernation cycle <wink>.

Anyway, I'd like to share a few thoughts with you based on my recent
experiences implementing my Crystal system: take them for what they're
worth. These are quite long, and maybe irrelevant; the recent massive debate
on hyperlinks etc came at a point where coding was more important to me
than reading so maybe some of these have been covered and maybe I'm just
being dumb...

For those of you who were asleep / bored / had server problems etc, Crystal
is a javadoc / pythondoc type system which you can download from:

  http://eh.org/~laurie/comp/python/crystal/

There is also some sample output on the page to give an idea of what output
it produces on given inputs. Both of these are a little out of date (and
please bear in mind this project is in the *very* early days - it's not user
friendly although probably easier to get running than pythondoc!), but they
give the general idea... I badgered my university to let me produce Crystal
as my undergraduate degree project, so that may put a few things into
perspective in the following...

OK, the rest from here on is definitely all IMHO.


 StructuredText

One of the few things I did pull out of the recent debate was that it has
been decreed that inline documentation should be at least based on
StructuredText. That made me do a little U-turn as I had been working on
something a little different; fortunately Crystal works on the idea of
plugins so I just made a StructuredText compatible plugin[0]. Initially I
wanted to use Jim Fultons module, but this turned out to be a bit of a
problem for the following reasons:

  * It seems to be geared up for subclasses returning strings (I needed a
      recursive data structure, not a string representation)
    In fact, realistically, the implementation is set up with only HTML in
      mind
  * There's no real documentation for the implementation
  * The implementation is *very* hard to understand if you haven't watched
      it evolve

So after a few hours attempting to munge the StructuredText module into
something I could use, I gave up and coded my own "compatible" version based
on the rules in the module and:

  http://www.zope.org/Members/millejoh/structuredText

I actually quite like the concept of StructuredText, but in my opinion,
there are some problems with the current specification. The major factor is
that the "Specification" isn't really that specific; one could argue that
"the implementation is the specification", but the current module is a
pretty hard implementation to understand. Some specific points include (in
no real order):

  * There is no protocol for escaping characters (ouch)

  * There is scope for ambiguous doc strings in the current spec. eg:

    """
    Here's some example code::

        def __init__(self):
             pass

        My next heading

    The start of a paragraph
    """

    Is "my next heading" part of the example code or a header to the
      following paragraph?

    Interestingly, on the zope.org page referenced above, at one point in
      the raw_text, there is:

    """
    Notes

      <>

    Including Structured Text in DML
    """

    And - unexpectedly - the notes header completely disappears in the
      output. Undocumented behaviour?

  * Are lists allowed to be recursive?
     * Should this work?
       * Is this out of this world?
    My implementation allows this (I find it useful)

  * Ordered lists are ill defined: can they go in any order, or should it
      be like the <OL Start = > HTML?

  * It is unclear whether the definition in a definition list should be
      allowed to take styles. eg is:

    """
       'code' -- description
       *emph* -- description
    """

    Going to work as one expects? In my implementation it (in the
      development version) does

  * The example code protocol is crufty & non-overridable. What should:

    """
    ...so for example:

       * element 1
       * element 2
    """

    do? C++ programs might get caught out with the actions of '::' in
      StructuredText <wink>

  * Forcing anything between ' ' into <Code> seems particularly clumsy; * has
      a good history of being an emphasis effect and ** is a cunning
      extension to that, but ' ' seems unnatural

    (Incidentally the implementation looks like <Code>something</Code> is
    valid but the spec mentions nothing)

  * From a purely Python perspective, having _ _ as the underline protocol
      tends to cause __init__ type method names to come out somewhat
      unexpectedly. But that's not StructuredTexts fault <wink>

  * Should styles nest? So is *this **going** to work* ?


The first point is the most crucial. Without an escape character protocol,
one can come up with all sorts of unpleasantness from the StructuredText
implementation.

I don't know what the definitive answer to some of the above problems is,
and maybe "the" implementation solves them; but from my point of view, the
current definition might get us into trouble in the long term by allowing
implementation specific things to accidentally work or fail. Python itself
gained much I believe from gaining a second implementation in JPython
forcing standardisation of many things.

My opinion is that what is currently the complete specification for
StructuredText is basically about right for an "overview", but that there
then needs to be a further section where things are explained in complete
detail to resolve the ambiguities and problems I've mentioned.


  Current doc strings

One thing I don't think any of us are sure of is what we should do with all
the doc strings we've already got. Thankfully my experience is that most doc
comments are very nearly in a StructuredText compatible format anyway.
Certainly, running Crystal over the 1.5.2 standard library produced fairly
good output with no alterations. As a test, I made a few quick minor
alterations to some files to bring them into line with StructuredText:
thankfully I don't see that doing it to even a large number of files is
actually going to be that difficult or time consuming.

Here are some things that tend to cause complications in current doc
strings:

  * Many look like:

    def __init__(self):
    """The first line

       The rest of the body

       Blah blah
    """

    What exactly is the indentation of that whole thing? To the human eye
      the answer is 8. In my implementation the above *doesn't* do what you
      expect because the first line gets an indentation of 0 and the rest
      an indentation of 8 (meaning the body is a sub paragraph of the rest):

    def __init__(self):
    """
       The first line

       The rest of the body

       Blah blah
    """

  * Sometimes lists and so on look like this:

    """
    - element 1 gets
    split over two lines
    - and so does
    element 2
    """

    whereas the way I read StructuredText (and the way I prefer things)
      means it should be:

    """
    - element 1 gets
      split over two lines
    - and so does
      element 2
    """

  * Example code sometimes isn't properly flagged (but see my earlier point)

As you can see none of these is exactly serious. It is my opinion that it is
*not* necessary to simply output all current doc comments in a monospaced
pre-formatted font: aesthetically this is awful, and practically I think
I've demonstrated with Crystal that it's not really necessary.


Unsurprisingly, I also have some thoughts about how to construct the "right"
tool for the job, but I think this little lot is enough for one post, so
comments etc are welcome.


Laurie

[0] So, yes, you can plugin different parsers for different inline
      comment syntaxes. You want POD? Fine. JavaDoc? Fine. So long as
      someone codes a plugin, this is one less thing hardcoded into
      the system
-- 
http://eh.org/~laurie/


From irmina@ctv.es  Sun Mar  5 13:48:50 2000
From: irmina@ctv.es (Manuel Gutierrez Algaba)
Date: Sun, 5 Mar 2000 13:48:50 +0000 (GMT)
Subject: Python lexicon/Crosswords Python (was Re: [Doc-SIG] Some random thoughts )
In-Reply-To: <98b87b9a49.laurie@btinternet.com>
Message-ID: <Pine.LNX.3.95.1000305133633.3592A-100000@localhost>

On Sun, 5 Mar 2000, Laurence Tratt wrote:

> Things have been a little quiet on here recently once again confirming the
> doc-sigs yoyo nature; I sometimes wonder if people here are on a 3 month
> hibernation cycle <wink>.
> 

Snakes dream in winter, and spring is near ;). yoyos are far more
predictable, they go up and down, docsig is more like a crazy
drunken goat running up and down  stairs.


> 
> Laurie
> 
> [0] So, yes, you can plugin different parsers for different inline
>       comment syntaxes. You want POD? Fine. JavaDoc? Fine. So long as
>       someone codes a plugin, this is one less thing hardcoded into
>       the system

I thought that plugin[0] was an element of a list, or a dictionary
(too much python programming ? ;) ) . Plugin sounds very sensible,
much much more than "one single standard". Anyway I'm starting
to think that "python docstring strandardzation" problem is 
NP-compatible. ;)

BTW, I've improved the "crosswords-making technology", perhaps 
after a while you'll live the "revival" of Crosswords for python
http://www.ctv.es/USERS/irmina/cruo/cruo.html (in the 
Computer sciences...)
Now what I need is a lexicon of words like:

pickle - Good class for persistent objects


I think such a lexicon would be great. And if we could enrich
it with fixed terms like :"db", "socket", "persistence"...

I don't trust cathedral design, or mega-projects any more, 
the real solution is
small chunks of info that unite into something really bigger.
Designs that start at the bottom, not at the top. You can 
reuse the bottom always, but the top is more complex to reuse.

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
/pyttex.htm  /pythonring.html /MiniBloquiHeader.html

  I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright



From doc-sig@python.org  Sun Mar  5 13:57:47 2000
From: doc-sig@python.org (Peter Funk)
Date: Sun, 5 Mar 2000 14:57:47 +0100 (MET)
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <98b87b9a49.laurie@btinternet.com> from Laurence Tratt at "Mar 5, 2000 11:22: 0 am"
Message-ID: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>

Hi!

Laurence Tratt:
> Things have been a little quiet on here recently once again confirming the
> doc-sigs yoyo nature; I sometimes wonder if people here are on a 3 month
> hibernation cycle <wink>.

I apologize for not answering immediately on your annoucement of Crystal.
But at least I have downloaded your code and spend one or two hours
looking into it.  I decided to wait a bit, what other people think 
about it before going to critize someone elses code without providing
something better.

First I wonder, why you decided  to use John Aycocks Spark as parser
instead of using the builtin parser provided by the standard library.
John Aycocks parser sure has its advantages and I use it myself in 
another project.  But if the task is parsing Python sourcecode, using 
the builtin parser seems to be more obvious.

The structure of your program was somewhat hard to grasp for me:
As far as I can see, the interesting functionality is contained 
(or may I say somewhat hidden?) in the following two modules:
   crystal/Defaults/Python_To_HTML3.py
and
   crystal/Doc_Parsers/StructuredText/Facade.py
This was not easy to figure out.  The overuse of 12 packages for a
program with only 19 modules containing real code seems to be too
much structure for a 0.1 version.  The 8 char TAB-indentation, the
long lines and the waste of vertical space made your code rather hard
to read for me.

As far as I understood your code, the "outputter" has the task
to transform an intermediate structure tree and produce for example
HTML using the definitions provided by a dictionary like that in 
Python_To_HTML3.py, right?  The definitions are not much simpler
as if they would have been coded directly as Python class.
So why do you define your own special purpose language for such 
definitions, when html3_outputter__styles could have been a class
containing methods for each structure element?  May be I should
have spend more time on studying your code (which I didn't had).

> Anyway, I'd like to share a few thoughts with you based on my recent
> experiences implementing my Crystal system: take them for what they're
> worth. These are quite long, and maybe irrelevant; the recent massive debate
> on hyperlinks etc came at a point where coding was more important to me
> than reading so maybe some of these have been covered and maybe I'm just
> being dumb...
> 
> For those of you who were asleep / bored / had server problems etc, Crystal
> is a javadoc / pythondoc type system which you can download from:
> 
>   http://eh.org/~laurie/comp/python/crystal/
> 
> There is also some sample output on the page to give an idea of what output
> it produces on given inputs. Both of these are a little out of date (and
> please bear in mind this project is in the *very* early days - it's not user
> friendly although probably easier to get running than pythondoc!), but they
> give the general idea... I badgered my university to let me produce Crystal
> as my undergraduate degree project, so that may put a few things into
> perspective in the following...
> 
> OK, the rest from here on is definitely all IMHO.
> 
> 
>  StructuredText
> 
> One of the few things I did pull out of the recent debate was that it has
> been decreed that inline documentation should be at least based on
> StructuredText. That made me do a little U-turn as I had been working on
> something a little different; fortunately Crystal works on the idea of
> plugins so I just made a StructuredText compatible plugin[0]. Initially I
> wanted to use Jim Fultons module, but this turned out to be a bit of a
> problem for the following reasons:
> 
>   * It seems to be geared up for subclasses returning strings (I needed a
>       recursive data structure, not a string representation)
>     In fact, realistically, the implementation is set up with only HTML in
>       mind
>   * There's no real documentation for the implementation
>   * The implementation is *very* hard to understand if you haven't watched
>       it evolve

Well.  I was able to do my own small modifications on StructuredText.py
but I agree to some degree with you.  Jim Fultons approach is too heavily
based in string processing.  What I had in mind was to get rid of the
vertical space wasting empty line between UL or OL list portions.
[...]
>   * Are lists allowed to be recursive?
>      * Should this work?
>        * Is this out of this world?
[...]
>   * Ordered lists are ill defined: can they go in any order, or should it
>       be like the <OL Start = > HTML?
> 
>   * It is unclear whether the definition in a definition list should be
>       allowed to take styles. eg is:
> 
>     """
>        'code' -- description
>        *emph* -- description
>     """
[...]
>   * The example code protocol is crufty & non-overridable. What should:
> 
>     """
>     ...so for example:
> 
>        * element 1
>        * element 2
>     """
> 
>     do? C++ programs might get caught out with the actions of '::' in
>       StructuredText <wink>

Personally I would prefer the idea of Tim Peters doctest for examples.
He suggests to use the Interpreter prompt as markup for example code:

	>>> a = FooBar("Baz")
	>>> a.something_completely_different()
	>>> a.spam()

>   * Forcing anything between ' ' into <Code> seems particularly clumsy; * has
>       a good history of being an emphasis effect and ** is a cunning
>       extension to that, but ' ' seems unnatural

Agreed.  This has been discussed here before.
[...]
>   * From a purely Python perspective, having _ _ as the underline protocol
>       tends to cause __init__ type method names to come out somewhat
>       unexpectedly. But that's not StructuredTexts fault <wink>

As has been said before, underlining is bad markup anyway.  It is not
used in any reasonable typeset output.

>   * Should styles nest? So is *this **going** to work* ?

I would say *not*.  
[...]
> One thing I don't think any of us are sure of is what we should do with all
> the doc strings we've already got. Thankfully my experience is that most doc
> comments are very nearly in a StructuredText compatible format anyway.

section headlines
-----------------
I think it would buy much, if a few additional features will be added to the 
structured text idea:  lists are fine, but another important doc structure 
element are section and subsection headers.  Often they are marked up as a line 
of text containing the headline followed by line of '-' with the same
length.  Both lines may be indented.  The standard library modules 
'cgi', 'pipes' and 'pprint' contain examples of this kind of markup.

[...]
> As you can see none of these is exactly serious. It is my opinion that it is
> *not* necessary to simply output all current doc comments in a monospaced
> pre-formatted font: aesthetically this is awful, and practically I think
> I've demonstrated with Crystal that it's not really necessary.

Agreed.

Just my 2 cents, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)


From laurie@eh.org  Sun Mar  5 15:48:54 2000
From: laurie@eh.org (Laurence Tratt)
Date: Sun, 05 Mar 2000 15:48:54 GMT
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <d827949a49.laurie@btinternet.com>

In message <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
          pf@artcom-gmbh.de (Peter Funk) wrote:

Thanks for the comments. OK, here goes...

> First I wonder, why you decided  to use John Aycocks Spark as parser
> instead of using the builtin parser provided by the standard library.

I don't. Well I do. But to parse Python files, I use the builtin parser. The
code's in lib/crystal/Languages/Python/Parsers/CPython/ (snappy eh?).

SPARK is used to compile the internal LayoutLanguage, which is it's own
little thing.

If it used SPARK to compile Python files you would know about it at
execution time! On my P233, I reckon SPARK munches somewhere just under 1Kb
a second: fine for the Layout Language (which has relatively little input),
but too slow for big Python files. On his website, John mentions the next
version will be faster which would be great. Even with the speed issues,
SPARK is truly great, and so to have speed less of an issue will be cool.

> The structure of your program was somewhat hard to grasp for me

Yes, without documentation it looks like a mess. In reality, there is a
method behind the madness, and all those packages are intended so that
future expansion is easy. For example, I decided to use '_' to indicate a
private or protected (in the Java sense) 'thing', be that an object, module,
class or whatever. A lot of those decisions just aren't apparent in a
straight source release and for that I apologise.

Now that I have written the appropriate tool, I'm working on putting doc
comments into Crystal itself. This should aid things a bit. The package
hierarchy isn't something that's going to (or should) go away, and so that
particular learning curve will remain.

> As far as I can see, the interesting functionality is contained 
> (or may I say somewhat hidden?) in the following two modules:
>    crystal/Defaults/Python_To_HTML3.py
> and
>    crystal/Doc_Parsers/StructuredText/Facade.py

I think I'd go with that, although I would add the file I mentioned earlier
and crystal/Languages/Python/Formatters/Default/_Format.py to that list as
well. There's a lot of other important code strewn around, but those 4 files
are probably the main workhorses.

crystal/Outputters/_Layout_Language.py is pretty important too.

> This was not easy to figure out.

The good things in life never are :)

> As far as I understood your code, the "outputter" has the task to
> transform an intermediate structure tree and produce for example HTML
> using the definitions provided by a dictionary like that in
> Python_To_HTML3.py, right?

The basic stages of Crystal are:

  * munch files using a Languages parser
      * at the same time munch doc comments using a Doc_Parser
  * create a 'logical' page using a Languages Formatter
  * convert the logical page into a physical page using an Ouputter and
      the Layout language to output to disk / screen / whatever

Important concepts are:

  * Language
    eg Python, Java
    A Language contains *everything* specific to a language

  * Doc_Parser
    eg javadoc, StructuredText
    This munches doc comments in a specific style into an internal format

  * Formatter
    eg 'Default', UML
    These live within a Language (they're language specific) and create a
      logically formmatted page
    A language doesn't actually have to have a seperate Formatter, but it
      would have to have some code which did the same job

  * Outputter
    eg HTML, Text, man
    Utilises the Layout Language to convert a logical page into physical
      output

> So why do you define your own special purpose language for such
> definitions, when html3_outputter__styles could have been a class
> containing methods for each structure element?  May be I should have spend
> more time on studying your code (which I didn't had).

I am not a fan of Yet Another Little Language, so I didn't take the decision
lightly. Basically, you *could* definitely do everything the Layout Language
does in pure Python but by taking control (or at least the illusion of
control) away from the programmer, I make simple things very easy to write
(that 13 or 14Kb of stuff in Python_To_HTML3.py would IMHO be much larger -
and convuluted - in standard Python) and do some useful little things on
their behalf. Again, undocumented :(

Initially I did do things in pure Python, but I found it forced me to write
un-Pythonic Python thus satisfying noone. The Layout Language also includes
a few things like type checking (well, the information is in there, even if
the code that does the checking isn't) to make things a bit more strict. I'd
class it as an experimental feature rather than a definite: I'm certainly
open to suggestions.

There is also the fact that I have got a reference manual for the Layout
Language in about 5 sides of A4: for people who don't know Python (the idea
behind the system is that it isn't Python specific), the chances are this
tiny little language (the grammar is about 15 lines with one-rule-per-line)
will be easier to learn than Python. Of course one could say they should
learn Python, but that's another issue <wink>.

[...on the StructuredText module]
>> * It seems to be geared up for subclasses returning strings (I needed a
>>     recursive data structure, not a string representation)
>>   In fact, realistically, the implementation is set up with only HTML in
>>     mind
>> * There's no real documentation for the implementation
>> * The implementation is *very* hard to understand if you haven't watched
>>     it evolve
> Well.  I was able to do my own small modifications on StructuredText.py
> but I agree to some degree with you.  Jim Fultons approach is too heavily
> based in string processing.

I think that's fair enough. I feel fairly certain in saying Jim had HTML as
his target market in mind, and that it fits that bill perfectly. Also, I
doubt he had the eventual continued expansion in mind when he started it in
about '95 / '96!

>>   * The example code protocol is crufty & non-overridable. What should:
>> 
>>     """
>>     ...so for example:
>> 
>>        * element 1
>>        * element 2
>>     """
>> 
>>     do? C++ programs might get caught out with the actions of '::' in
>>       StructuredText <wink>
> Personally I would prefer the idea of Tim Peters doctest for examples.
> He suggests to use the Interpreter prompt as markup for example code:
> 
>       >>> a = FooBar("Baz")
>       >>> a.something_completely_different()
>       >>> a.spam()

I could live with that, definitely: most Pythonic. But only *provided*
the >>> doesn't necessarily come out in the output (unless you switched that
on... Er, that might be tricky to do sensibly). Any ideas?

>> * Forcing anything between ' ' into <Code> seems particularly clumsy; *
>>     has a good history of being an emphasis effect and ** is a cunning
>>     extension to that, but ' ' seems unnatural
> Agreed.  This has been discussed here before.

Do we have any suggestions for an alternative?

>> * From a purely Python perspective, having _ _ as the underline protocol
>>     tends to cause __init__ type method names to come out somewhat
>>     unexpectedly. But that's not StructuredTexts fault <wink>
> As has been said before, underlining is bad markup anyway.  It is not
> used in any reasonable typeset output.

I think I could live with that.

>> * Should styles nest? So is *this **going** to work* ?
> I would say *not*.

My thinking is that perhaps there need to be two "types" of style. The * **
simple ones, and then something like perhaps <Emph> </Emph> ; the later ones
could be used in more complex situations and could nest.

> section headlines
> -----------------
> I think it would buy much, if a few additional features will be added to
> the structured text idea:  lists are fine, but another important doc
> structure element are section and subsection headers.  Often they are
> marked up as a line of text containing the headline followed by line of
> '-' with the same length.  Both lines may be indented.  The standard
> library modules 'cgi', 'pipes' and 'pprint' contain examples of this kind
> of markup.

I am currently doing some fence sitting on section headlines and sections
and subsections etc. I don't know how to strike the right balance between
good quality output and ease of use / readibility in the code in this
respect.


One thing that's surprised me is that I thought people were going to tear me
to shreds over the HTML output (in terms of both the quality and the actual
look in the browser) and ignore the source (which is still rough) whereas so
far it's been mostly the other way around. Shows you how wrong I can be :)


we're-going-somewhere-now-though-ly y'rs Laurie
-- 
http://eh.org/~laurie/comp/python/


From willguaraldi@mediaone.net  Sun Mar  5 17:38:18 2000
From: willguaraldi@mediaone.net (will)
Date: Sun, 5 Mar 2000 12:38:18 -0500
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <d827949a49.laurie@btinternet.com>
Message-ID: <NDBBJAKILMEBBFEDCMKKCEHFCBAA.willguaraldi@mediaone.net>

> -----Original Message-----
...
> One thing that's surprised me is that I thought people were
> going to tear me
> to shreds over the HTML output (in terms of both the
> quality and the actual
> look in the browser) and ignore the source (which is still
> rough) whereas so
> far it's been mostly the other way around. Shows you how
> wrong I can be :)

Hey!  I commented on the html output like a week ago...  :(

I've been using Crystal to generate documentation for the mud project
I've been working on with the other Varium folks because I was never
able to get pythondoc working.  I spent a couple hours with pythondoc
trying to make it happy.  In comparison, I think I got Crystal up and
running in a half hour or so.  And had built a script to re-generate
html docs for our varium mud server code every night.

I find the visual parts of the output to be slightly
confusing--certainly not as nice as Ping's thing's output.  Course the
visual output can be changed to some extent to suit one's needs.  In
the test#.py example files, if you call
html3_outputter_styles.update() you can replace various elements in
the html style dictionary and thus affect the visual aspects of the
final html.  I have yet to figure out enough of which elements are
which and then how to adjust them to suit my tastes.  I was telling
Laurence that he's built Crystal in such a way that theoretically you
could build themes without changing/patching the Crystal code.

I also dislike some other things about the html output which comes
from how Crystal translates the html classes into actual html text
files.  Specifically the fact that Crystal is not quoting values in
attributes of the various tags and the use of tabs as indentation
rather than 3 or 4 spaces.

<Table CellSpacing = 0 Align = Center Width = 100% CellPadding = 3>
vs.
<Table CellSpacing="0" Align="Center" Width="100%" CellPadding="3">

This is pretty trivial, but "Generated by Crystal 0.2 (24 February
2000) Copyright &copy;Laurence Tratt 1999 - 2000 at 07:16AM Sunday 05
March 2000" which is printed at the bottom of every html page is
confusing.  It sounds like Lawrence generated and copyrighted MY html
output, not that he created and copyrighted Crystal which generated my
html output.  Actually, that's not trivial.  It should be two
different lines:

   Generated at 07:16AM Sunday 05 March 2000 by willg
   using Crystal 0.2 (24 February 2000) Copyright &copy;Laurence Tratt
1999-2000

Or something to that effect.

Beyond that, it's pretty good about some things.  We've had problems
with doc-string comments being formatted in a funky manner in the html
output.  But that's mostly due to the fact we're pretty ignorant as to
what the markup methods are.

It would be really nice to be able to mark certain variables and
functions and classes as "internal use only" so that they don't show
up in the documentation.

So that's a semi-html-oriented rough review from my perspective.

If you want to look at the output we've got (based on code that's in a
state of constant flux), feel free to look at:
http://www.varium.com/coders/mudserver/index.html

I told Laurence that I was going to play with the style and change it
to something that I find less confusing (less lines).  I haven't done
much since then, though.  I keep getting sidetracked.

/will



From laurie@eh.org  Sun Mar  5 17:59:28 2000
From: laurie@eh.org (Laurence Tratt)
Date: Sun, 05 Mar 2000 17:59:28 GMT
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <NDBBJAKILMEBBFEDCMKKCEHFCBAA.willguaraldi@mediaone.net>
References: <NDBBJAKILMEBBFEDCMKKCEHFCBAA.willguaraldi@mediaone.net>
Message-ID: <3e1ca09a49.laurie@btinternet.com>

In message <NDBBJAKILMEBBFEDCMKKCEHFCBAA.willguaraldi@mediaone.net>
          "will" <willguaraldi@mediaone.net> wrote:

[Laurie]
>> One thing that's surprised me is that I thought people were going to tear
>> me to shreds over the HTML output (in terms of both the quality and the
>> actual look in the browser) and ignore the source (which is still rough)
>> whereas so far it's been mostly the other way around. Shows you how wrong
>> I can be :)
> Hey!  I commented on the html output like a week ago...  :(

I did say mostly: you're the honourable exception :)

> I find the visual parts of the output to be slightly confusing--certainly
> not as nice as Ping's thing's output.  Course the visual output can be
> changed to some extent to suit one's needs.  In the test#.py example
> files, if you call html3_outputter_styles.update() you can replace various
> elements in the html style dictionary and thus affect the visual aspects
> of the final html.  I have yet to figure out enough of which elements are
> which and then how to adjust them to suit my tastes.  I was telling
> Laurence that he's built Crystal in such a way that theoretically you
> could build themes without changing/patching the Crystal code.

Documentation is an issue, and I apologise again... But themes are
definitely something I want to do (I had the concept, but stupidly didn't
call them themes. So thanks to Will for pointing out the obvious!), and then
hopefully I can keep more people happy.

If anyone's got something specifically they dislike (perhaps the indices),
then I can take it from there.

> I also dislike some other things about the html output which comes from
> how Crystal translates the html classes into actual html text files. 
> Specifically the fact that Crystal is not quoting values in attributes of
> the various tags and the use of tabs as indentation rather than 3 or 4
> spaces.
> <Table CellSpacing = 0 Align = Center Width = 100% CellPadding = 3>
> vs.
> <Table CellSpacing="0" Align="Center" Width="100%" CellPadding="3">

The first of those is definitely a fault; the second I'm ambivalent about
(I'm a tab person myself). If it's a problem, a search and replace "\t" with
"   " in lib/crystal/Defaults/Python_To_HTML3.py is a quick hack fix.

> This is pretty trivial, but "Generated by Crystal 0.2 (24 February 2000)
> Copyright &copy;Laurence Tratt 1999 - 2000 at 07:16AM Sunday 05 March
> 2000" which is printed at the bottom of every html page is confusing.  It
> sounds like Lawrence generated and copyrighted MY html output, not that he
> created and copyrighted Crystal which generated my html output.  Actually,
> that's not trivial.  It should be two different lines:
> 
>    Generated at 07:16AM Sunday 05 March 2000 by willg
>    using Crystal 0.2 (24 February 2000) Copyright &copy;Laurence Tratt
> 1999-2000
> 
> Or something to that effect.

OK. I think that's reasonable; I only put it in there to test the address
tag in Netscape (it's broken. Surprise). I'll change it so that by default
it's "Generated at 07:15AM Sunday 05 March 2000 using Crystal Copyright
Laurence Tratt" etc. I actively *don't* want to copyright anyones HTML!

> Beyond that, it's pretty good about some things.  We've had problems with
> doc-string comments being formatted in a funky manner in the html output. 
> But that's mostly due to the fact we're pretty ignorant as to what the
> markup methods are.

Currently what's implemented is a subset of StructuredText. You can get a
rough idea of what's what:

  http://www.zope.org/Members/millejoh/structuredText

But please note it's not a perfect implementation since some of those rules
are currently open for debate. Specifically, intra-page links are currently
not at all supported (not that I don't like them. I just haven't done them).

> It would be really nice to be able to mark certain variables and functions
> and classes as "internal use only" so that they don't show up in the
> documentation.

I'm going to work on that. ATM Crystal itself uses an initial single "_" to
do this; adding in overrides for specific variables etc will be pretty hard
to do sensibly (it'll grow like wildfire is my first thought), but it is on
my list.

I might make another release in a few days time to just clear up a couple of
the HTML issues (my current version doesn't cause browser windows to
oversize horizontally). There won't be much other difference though.


Laurie
-- 
http://eh.org/~laurie/comp/python/


From DavidA@ActiveState.com  Sun Mar  5 21:05:13 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Sun, 5 Mar 2000 13:05:13 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <98b87b9a49.laurie@btinternet.com>
Message-ID: <LMBBIEIJKMPMLBONJMFCEEBECCAA.DavidA@ActiveState.com>

>  StructuredText

StructuredText has a couple of problems which we already discussed here.  I
agree with all of your comments about it, and I think there were a couple of
other ones -- please check the archives for the details.

>   * Forcing anything between ' ' into <Code> seems particularly
> clumsy; * has
>       a good history of being an emphasis effect and ** is a cunning
>       extension to that, but ' ' seems unnatural
>
>     (Incidentally the implementation looks like <Code>something</Code> is
>     valid but the spec mentions nothing)

emphasis and <code> markup are different things.  FWIW, I still don't think
we have a great solution for that one.

> Unsurprisingly, I also have some thoughts about how to construct
> the "right" tool for the job, but I think this little lot is enough for
one post, so
> comments etc are welcome.

A few other points:

1) Does your version allow knowledge of the line numbers?  error-capturing
is important, and StructuredText.py doesn't keep that.

2) The Zope folks will likely keep their own version as a separate fork
until and unless your or anyone else's version does the same thing at least
as fast -- they care about speed in Zope.

Good work!

[I haven't had a chance to look at the code but will do ASAP]

--david



From ping@lfw.org  Sun Mar  5 21:23:18 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Sun, 5 Mar 2000 13:23:18 -0800 (PST)
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <98b87b9a49.laurie@btinternet.com>
Message-ID: <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>

On Sun, 5 Mar 2000, Laurence Tratt wrote:
> Here are some things that tend to cause complications in current doc
> strings:
> 
>   * Many look like:
> 
>     def __init__(self):
>     """The first line
> 
>        The rest of the body
> 
>        Blah blah
>     """
> 
>     What exactly is the indentation of that whole thing? To the human eye
>       the answer is 8. In my implementation the above *doesn't* do what you
>       expect because the first line gets an indentation of 0 and the rest
>       an indentation of 8 (meaning the body is a sub paragraph of the rest):

I came across this problem too.  "manpy"'s solution to this problem
is to look for the minimum indentation of all lines except the first,
and remove that amount of indentation from all the lines in the string.

More compactly stated,

    lines = split(expandtabs(docstring), "\n")
    margin = min(map(lambda line: len(line) - len(lstrip(line)), lines[1:]))
    for i in range(1, len(lines)): lines[i] = lines[i][margin:]

It does make assumptions, but it's always done the right thing so far.


-- ?!ng

"To be human is to continually change.  Your desire to remain as you are
is what ultimately limits you."
    -- The Puppet Master, Ghost in the Shell



From DavidA@ActiveState.com  Sun Mar  5 21:21:03 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Sun, 5 Mar 2000 13:21:03 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>
Message-ID: <LMBBIEIJKMPMLBONJMFCOEBECCAA.DavidA@ActiveState.com>

> I came across this problem too.  "manpy"'s solution to this problem
> is to look for the minimum indentation of all lines except the first,
> and remove that amount of indentation from all the lines in the string.

FWIW, I made the same assumption in my unreleased code.

--da


From laurie@eh.org  Sun Mar  5 21:39:32 2000
From: laurie@eh.org (Laurence Tratt)
Date: Sun, 05 Mar 2000 21:39:32 GMT
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <LMBBIEIJKMPMLBONJMFCEEBECCAA.DavidA@ActiveState.com>
References: <LMBBIEIJKMPMLBONJMFCEEBECCAA.DavidA@ActiveState.com>
Message-ID: <0a42b49a49.laurie@btinternet.com>

In message <LMBBIEIJKMPMLBONJMFCEEBECCAA.DavidA@ActiveState.com>
          "David Ascher" <DavidA@ActiveState.com> wrote:

> StructuredText has a couple of problems which we already discussed here.
> I agree with all of your comments about it, and I think there were a
> couple of other ones -- please check the archives for the details.

OK, I'm looking back in the archives (for various
lets-shut-down-the-mail-server-for-10-days-for-y2k, mailman set delivery off
for me on the doc-sig for about a month which meant I missed that)... Yeah,
OK. Although unless I've missed something there doesn't appear to be a
solution to the problem yet :(

> A few other points:
>
> 1) Does your version allow knowledge of the line numbers?  error-capturing
> is important, and StructuredText.py doesn't keep that.

Not yet. Currently there's no error handling (it's a bit too early days for
that).

Realistically, at the moment I reckon we need to sharpen up our ideas on
*what* we want, and then I'll recode from scratch based on that. At that
point I would probably put in full error handling and reporting. My current
implementation was less than a days work from start to finish, so I'm not
too emotionally attached to it <wink>.

> 2) The Zope folks will likely keep their own version as a separate fork
> until and unless your or anyone else's version does the same thing at
> least as fast -- they care about speed in Zope.

I doubt mine is faster, and I don't really care because it's not important
for my tasks (it's not API compatible with the current StructuredText
either); I can see that the current Jim module would probably be fairly fast
as it uses regex instead of re and some other little optimisation tricks. I
reckon it could be made even faster if they got rid of a lot of the small
function calls; maybe that's something on the cards. It'll reduce
readability even further though :)

> [I haven't had a chance to look at the code but will do ASAP]

Thanks, although bear in mind that it's not yet a masterpiece (in fact as
Peter Funk pointed out, in its undocumented state it's darn right confusing
at first). But it is generating some useful discussion which is good.


Laurie
-- 
http://eh.org/~laurie/comp/python/


From laurie@eh.org  Sun Mar  5 21:43:59 2000
From: laurie@eh.org (Laurence Tratt)
Date: Sun, 05 Mar 2000 21:43:59 GMT
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>
References: <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>
Message-ID: <6caab49a49.laurie@btinternet.com>

In message <Pine.LNX.4.10.10003051317340.1788-100000@skuld.lfw.org>
          Ka-Ping Yee <ping@lfw.org> wrote:

>> Here are some things that tend to cause complications in current doc
>> strings:
>> 
>>   * Many look like:
>> 
>>     def __init__(self):
>>     """The first line
>> 
>>        The rest of the body
>> 
>>        Blah blah
>>     """
>> 
>>  What exactly is the indentation of that whole thing? To the human eye
>>    the answer is 8. In my implementation the above *doesn't* do what you
>>    expect because the first line gets an indentation of 0 and the rest
>>    an indentation of 8 (meaning the body is a sub paragraph of the rest):
> I came across this problem too.  "manpy"'s solution to this problem
> is to look for the minimum indentation of all lines except the first,
> and remove that amount of indentation from all the lines in the string.
> 
> More compactly stated,
> 
>  lines = split(expandtabs(docstring), "\n")
>  margin = min(map(lambda line: len(line) - len(lstrip(line)), lines[1:]))
>  for i in range(1, len(lines)): lines[i] = lines[i][margin:]
> 
> It does make assumptions, but it's always done the right thing so far.

I nearly did that, but my personal preference is to cut down on these sorts
of assumptions where possible. My thinking was (without wishing to start a
flame war), this sort of auto-pseudo-intelligence is quite Perl like and
tends to lead one into troubles in the future when one finds a need to break
the assumption to allow something else to work...

From an aesthetics point of view, I actually find:

   """
   The first line

   The main body
   """

clearer than:

   """The first line

   The main body
   """

or:

   """The first line

   The main body"""


you-win-some-you-lose-some-it's-much-the-same-to-me-ly y'rs Laurie
-- 
http://eh.org/~laurie/comp/python/


From DavidA@ActiveState.com  Sun Mar  5 22:36:41 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Sun, 5 Mar 2000 14:36:41 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <6caab49a49.laurie@btinternet.com>
Message-ID: <LMBBIEIJKMPMLBONJMFCKEBFCCAA.DavidA@ActiveState.com>

> I nearly did that, but my personal preference is to cut down on
> these sorts of assumptions where possible. My thinking was (without
wishing to start a
> flame war), this sort of auto-pseudo-intelligence is quite Perl like and
> tends to lead one into troubles in the future when one finds a
> need to break the assumption to allow something else to work...

At the risk of offending, it doesn't matter what your aesthetics are.  If
you want your code to become the standard doc-processing tool, it should
process the standard docstrings appropriately -- alternatively, you can
submit one mondo patch and fight that battle.

--david



From doc-sig@python.org  Mon Mar  6 06:21:17 2000
From: doc-sig@python.org (Peter Funk)
Date: Mon, 6 Mar 2000 07:21:17 +0100 (MET)
Subject: indent of very first line of doc string (was Re: [Doc-SIG] Some random thoughts)
In-Reply-To: <LMBBIEIJKMPMLBONJMFCKEBFCCAA.DavidA@ActiveState.com> from David Ascher at "Mar 5, 2000  2:36:41 pm"
Message-ID: <m12RqtJ-000CnDC@artcom0.artcom-gmbh.de>

Hi!

Laurie:
> > I nearly did that, but my personal preference is to cut down on
> > these sorts of assumptions where possible. My thinking was (without
> > wishing to start a
> > flame war), this sort of auto-pseudo-intelligence is quite Perl like and
> > tends to lead one into troubles in the future when one finds a
> > need to break the assumption to allow something else to work...

David Ascher comments:
> At the risk of offending, it doesn't matter what your aesthetics are.  If
> you want your code to become the standard doc-processing tool, it should
> process the standard docstrings appropriately -- alternatively, you can
> submit one mondo patch and fight that battle.

I aggree with David.  I've many doc strings that look like
	"""FooBar -- short one line description of the class

	more detailed bla bla about this class...."""

The "artificial intelligence" contained in Ping three lines of code
seems perfectly reasonable to me.

Regards, Peter
P.S.: Finally it looks, if Doc-Sig is awakened again. ;-)
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany


From Edward Welbourne <eddyw@lsl.co.uk>  Mon Mar  6 13:46:32 2000
From: Edward Welbourne <eddyw@lsl.co.uk> (Edward Welbourne)
Date: Mon, 6 Mar 2000 13:46:32 +0000
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <d827949a49.laurie@btinternet.com>
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
 <d827949a49.laurie@btinternet.com>
Message-ID: <E12RxqC-0004H6-00@lsls4p>

>>> * Forcing anything between ' ' into <Code> seems particularly clumsy; *
>> Agreed.  This has been discussed here before.
> Do we have any suggestions for an alternative?

Yes, but no take-up on it: use #blah# for <code>blah</code>
The only objection (I've heard) to this is that it looks ugly, but then
so do monospaced fonts and that's what it's asking for.

I believe this is conflict-free for inline code blocks (of course, code
paragraphs may want to include comments; but such paragraphs will be
introduced by a tag such as Example or a prefix such as >>> and, being
parsed as paragraphs, can suppress the special meaning of # for the
duration).

> My thinking is that perhaps there need to be two "types" of style.

No ! don't do it !  Doc-strings should (and StructuredText provides for
them to) use only minimal mark-up.  If you need to do fancy markup, it
belongs in the accompanying (out-of-line) documentation, *not* in the
doc-strings.  If it can't be said with minimal markup, it doesn't belong
in the doc string ...

> I am currently doing some fence sitting on section headlines

How about a line starting (at the indent of its predecessors) with a
colon ?
  ... """First line

      Introductory paragraph, ...

      Arguments:

          blah -- desription

      : First section

          paragraphs indented relative to it

          : sub-section

             With further nesting to arbitrary depth ?
             Discourage depth > 6, of course, for HTML's sake.

          more paragraphs in first section ?  [ would be confusing ]

      : Second section

          and so on


      more paragraphs ?  [ again, would be confusing ]

      Tailpiece:
          All that stuff that got discussed earlier about
          cross-references and so on; XML-style info content using
          indentation instead of nested <tag>...</tag> pairs.
      """

I can't think of any case where that might otherwise appear (but is : a
valid list-item-bullet ?).  Otherwise, in the style of the `keyword:'
setups discussed earlier (and illustrated as Tailpiece), use `Section:'
with the indentation relative to earlier `Section:' lines serving to
decide whether this is a sub-section or a new section at the same level.

	Eddy.


From Edward Welbourne <eddyw@lsl.co.uk>  Mon Mar  6 13:29:05 2000
From: Edward Welbourne <eddyw@lsl.co.uk> (Edward Welbourne)
Date: Mon, 6 Mar 2000 13:29:05 +0000
Subject: indent of very first line of doc string (was Re: [Doc-SIG] Some random
In-Reply-To: <m12RqtJ-000CnDC@artcom0.artcom-gmbh.de>
References: <LMBBIEIJKMPMLBONJMFCKEBFCCAA.DavidA@ActiveState.com>
 <m12RqtJ-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <E12RxZJ-0004GL-00@lsls4p>

>    for i in range(1, len(lines)): lines[i] = lines[i][margin:]
Hmm.  Mightn't it be a good idea to strip up to margin spaces off the
start of the first line also ?  e.g.

    """ Someone left a blank at the start of the string.

    And then documented the rest."""
->
"""Someone left a blank at the start of the string.

And then documented the rest."""

and I'd rather compute

    margin = min(map(lambda line: len(line) - len(lstrip(line)), 
                 filter(lstrip, lines[1:]))) # ignore blank lines

so that the blank line in my doc-string doesn't force a margin of 0.

	Eddy.


From pf@artcom-gmbh.de  Mon Mar  6 13:45:42 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Mon, 6 Mar 2000 14:45:42 +0100 (MET)
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <E12RxqC-0004H6-00@lsls4p> from Edward Welbourne at "Mar 6, 2000  1:46:32 pm"
Message-ID: <m12RxpO-000CnDC@artcom0.artcom-gmbh.de>

Hi!

Edward Welbourne wrote:
[...about section headings in doc strings...]
> How about a line starting (at the indent of its predecessors) with a
> colon ?
>   ... """First line
> 
>       Introductory paragraph, ...
> 
>       Arguments:
> 
>           blah -- desription
> 
>       : First section
> 
>           paragraphs indented relative to it
> 
>           : sub-section
[...]

I don't like this.  Why invent something new, when there is natural
and appealing notation available, which is already used several times
within the Python standard library?  Have a look at the docstrings
contained in 'cgi.py', 'pipes.py' or 'pprint.py'.  Here is an
(shortened) example:

"""
[...]
Using the cgi module
--------------------
[...]
"""

This should be easy to detect and is unlikely to fail.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)


From Edward Welbourne <eddyw@lsl.co.uk>  Mon Mar  6 14:33:15 2000
From: Edward Welbourne <eddyw@lsl.co.uk> (Edward Welbourne)
Date: Mon, 6 Mar 2000 14:33:15 +0000
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <m12RxpO-000CnDC@artcom0.artcom-gmbh.de>
References: <E12RxqC-0004H6-00@lsls4p> <m12RxpO-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <E12RyZP-0004J2-00@lsls4p>

>>           : sub-section
> I don't like this.
Can't say as I do either, having given it a few hours to settle.

> Using the cgi module
> --------------------

Can't argue ;^>

Meanwhile, what do folk make of #inline-code# ?

	Eddy.


From pf@artcom-gmbh.de  Mon Mar  6 14:56:41 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Mon, 6 Mar 2000 15:56:41 +0100 (MET)
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <E12RyZP-0004J2-00@lsls4p> from Edward Welbourne at "Mar 6, 2000  2:33:15 pm"
Message-ID: <m12Ryw6-000CnDC@artcom0.artcom-gmbh.de>

Edward Welbourne wrote:
> Meanwhile, what do folk make of #inline-code# ?

Personally I find this ugly.  But I've looked through the Python 
standard library and my own code and found out, that such 
inline code is absolutely rare.  code examples occur almost always
in separated paragraphs.

What is more often used, are references to identifiers.  We had some 
discussion about this before.  I suggested the use of a single '^' in
front of the identifer as markup.  In the meantime I have used this in my 
docstrings and find it rather appealing.  Here are two examples:

    def __init__(self, typedValue):
        """This class behaves similar to the class ^Tkinter.Variable
        If the ^typedValue is something simple like a number or a string, 
        most functionality is delegated to a private member ^self._tk_var.

        But ^typedValue may also be a list or a dictionary containing
        other structures or simple values.
        """

    def setval(self, value, from_listener = None):
        """assigns a new data ^value to ^self.

        After assigning the ^value all listeners will be called.  To avoid
        loops, the calling object should submit itself as second parameter 
        ^from_listener to this method here.
        """

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)


From laurie@eh.org  Mon Mar  6 18:45:04 2000
From: laurie@eh.org (Laurence Tratt)
Date: Mon, 06 Mar 2000 18:45:04 +0000
Subject: [Doc-SIG] Some random thoughts
References: <LMBBIEIJKMPMLBONJMFCKEBFCCAA.DavidA@ActiveState.com>
Message-ID: <38C3FCAF.F915B2B@eh.org>

David Ascher wrote:

[The First line indenting problem]
[Laurie]
>> I nearly did that, but my personal preference is to cut down on
>> these sorts of assumptions where possible. My thinking was (without
>> wishing to start a flame war), this sort of auto-pseudo-intelligence
>> is quite Perl like and tends to lead one into troubles in the future
>> when one finds a need to break the assumption to allow something else
>> to work...
> At the risk of offending

Don't worry about that. We're not exactly into John Cleese on a battlement
insults yet <wink>.

> it should process the standard docstrings appropriately --

OK, I'm going to qualify my earlier statement: if the first line indent rule
(Pings or Edwards) is incorporated into the standard rules, I'd be happy.
What I'm not happy with is tools adding "pseudo intelligence" on top of a
standard. Standards make our life easier in the long run, and I think that -
for better or for worse - they should be adhered to except in extreme
circumstances.

I admit that the standard needs, er, more standardising.

> alternatively, you can submit one mondo patch and fight that battle.

In my opinion when / if we standardise on a set of rules, someone will
almost certainly need to go through the standard library and bring things
into line. The main reason this is necessary is that, as of the 1.5.2
library at least, there isn't a standard within the library (and thus many
files aren't StructuredText compatible). Mercifully I don't think this will
be a long or difficult job which is a consolation!


Laurie


From laurie@eh.org  Tue Mar  7 12:36:24 2000
From: laurie@eh.org (Laurence Tratt)
Date: Tue, 07 Mar 2000 12:36:24 +0000
Subject: [Doc-SIG] Some random thoughts
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
 <d827949a49.laurie@btinternet.com> <E12RxqC-0004H6-00@lsls4p>
 <38C41592.864063C5@eh.org> <E12SHsd-0005Xp-00@lsls4p>
Message-ID: <38C4F7C8.8A62367E@eh.org>

Edward Welbourne wrote:

>> # doesn't seem entirely appropriate ... an attachment to it for
>> delimiting comments ... perhaps |blah| ... TeX heritage IIRC?
> and someone else remarked that in-paragraph code is rare.  So, if it's
> just delimiting *identifiers* that's needed, |blah| will do fine;
> however, this can't be stretched to include the few instances of in-line
> code, whereas #arbitrary.code('fragment')# will be unambiguous (subject to
> `usual' tricks like #recognising('# within a string')# as not a
> terminator); but use of bitwise or in an expression will present a
> problem for |blah| ...

OK, you've lost me here :) All I was suggesting was substituting | for # :
if # can cover something, then I guess | can as well. It's mostly
aesthetics.

Whether | or # should cover identifiers or arbitrary code fragments is
another discussion (I had assumed that | would cover identifiers and we'd
have another mechanism for code fragments: my mistake). In my opinion we
will have to come up with a mechanism for precise specification of remote
identifiers. In English: if a doc string references "a" and a is within the
namespace of the current module/class/method (via imports or other
definitions etc) then I'm happy (my system contains all the information
necessary for this to work as one would expect); if it isn't then I think
I'd need a way of specifying exactly what "a" is referring to so as to avoid
ambiguity.
 
> I'll be well disgruntled if my string *loses its quotes* because
> someone thought they meant `put this in code face'. 

I don't think you need to worry about this: we all seem to agree that ' ' is
crufty for code markup.

Not that we've agreed on an alternative yet <wink>.

>>> If it can't be said with minimal markup, it doesn't belong
>>> in the doc string ...
>> I'm not going to buy that: ...
> sorry, I was paraphrasing Calvin: As far as *I'm* concerned, if
> something is so complicated that you can't exlain it in 10 seconds, then
> it's probably now worth knowing anyway.  I don't buy this either, but it
> *does* contain a grain of truth.

What I would like is something that can be *mostly* understood in a short
space of time (10 seconds is pushing it), but which explains all those nasty
little what-ifs in a more precise way somewhere else.
 
> I really don't see that doc strings need more than structured text; and
> anything which *does*, it seems to me, *is* trying too hard in the wrong
> place; anything which *needs* nested emphasis/strong/... is over-using
> font-changes.

OK, I think I agree with that. Nested font changes are probably evil, but
they weren't my original thinking (I thought | might do for identifiers and
<Code> for code fragments etc. That seemed, by default, to allow nested font
styles).

> There's always out-of-line documentation and cross-references for when
> the information content is just too complex to encode with structured
> text; and those times are exactly when the information, if put into the
> doc-string, would take up so much vspace on screen that the function's
> def line and body get too far separated for practical readability.

I want to keep doc strings as simple as feasible, but I've also never bought
into the whole vspace argument (witness someone's complaint about the
whitespace I use), probably because the world I've been bought up in has big
screens and no line editors <wink>. I guess I'm trying to strike a
compromise between ultimate simplicity, and C++ doc TeX monstrosities
neither of which seems quite appropriate.


Laurie



From Edward Welbourne <eddyw@lsl.co.uk>  Tue Mar  7 16:01:42 2000
From: Edward Welbourne <eddyw@lsl.co.uk> (Edward Welbourne)
Date: Tue, 7 Mar 2000 16:01:42 +0000
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <38C4F7C8.8A62367E@eh.org>
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
 <d827949a49.laurie@btinternet.com> <E12RxqC-0004H6-00@lsls4p>
 <38C41592.864063C5@eh.org> <E12SHsd-0005Xp-00@lsls4p>
 <38C4F7C8.8A62367E@eh.org>
Message-ID: <E12SMQY-0005w3-00@lsls4p>

> OK, you've lost me here :) All I was suggesting was substituting | for # :
> if # can cover something, then I guess | can as well.

Well, if the `something' in question may contain (unprotected) uses of |
but mayn't contain (unprotected) uses of #, then #something# will work
and |something| will be ambiguous; this applies when `something' is an
arbitrary expression written in python (i.e. the stuff one uses in an
in-paragraph code fragment: the use of comments in doc-string code
blocks isn't affected (code *blocks* being introduced other ways, either
by keyword or by >>> and ...) as they're not part of paragraph text).

By contrast, when discussing a set of flag constants to be combined with
bitwise or, one will want to use | in code fragments within the text of
a paragraph, which will cause problems if | is also in use as the
delimiter by which the paragraph tries to spot the end of the code
fragment.  So | is prettier, and sufficient as long as we only care
about indicating identifiers, but totally useless for delimiting code
fragments within paragraphs of doc-string text.

Now, 
 * Ping and others have adequate machinery for spotting identifiers,
   albeit Tibs and I don't like those,
 * I would argue that, for all that they're reputedly rare, we *do* need
   some mechanism for marking up code fragments,
 * identifiers are code fragments too, and most of my objections to
   Ping's heuristics evaporate when they are applied only to the text of
   code fragments (and to other appropriately marked-up pieces of text,
   such as where an argument name appears in the Arguments: block)

> It's mostly aesthetics.
Nope: #code|fragment# is parseable; |code|fragment| is broken.
No code fragment needs to include a # (outside quotes), some code
fragments do need to use bitwise or.
Parsers are not aesthetes.
Not even mostly.

The argument *against* # is aesthetic.
The argument *for* it is practical.
The argument for | is aesthetic and impractical.

Note that | also suffers problems if someone is illustrating a unix
shell command """... to find users of this module, cd to the python
installation directory and use find | xargs grep to hunt for .py files
which import it ...""".  I am a little concerned (non-British
anglophones, please comment - this is not normal UK usage) by the
possibility that some folk may use # to mean `number' in their doc
strings (outside code fragments), which would present a corresponding
deficiency for #.

> we all seem to agree that ' ' is crufty for code markup.
cool.

> Not that we've agreed on an alternative yet <wink>.
OK, am I making any progress towards persuading you ?

> I've also never bought into the whole vspace argument
Fair dinkum.  That one is aesthetic.

> probably because the world I've been bought up in has big screens
while I was brought up with 25-line screens and now exploit big screens
to give me friendly-sized fonts and about 50 lines, but still desire
tight vertical layout - Tibs tells me my habitual use of, e.g.

    try: val = dict[key]
    except KeyError: val = default

is unkind to other pythoneers.  But this one is aesthetic.

> I guess I'm trying to strike a compromise between ultimate simplicity
> and ... monstrosities.
Yup, that's what we're all here for, so thanks for your contribution ;^)

	Eddy.


From laurie@eh.org  Tue Mar  7 20:40:56 2000
From: laurie@eh.org (Laurence Tratt)
Date: Tue, 07 Mar 2000 20:40:56 +0000
Subject: [Doc-SIG] Some random thoughts
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de>
 <d827949a49.laurie@btinternet.com> <E12RxqC-0004H6-00@lsls4p>
 <38C41592.864063C5@eh.org> <E12SHsd-0005Xp-00@lsls4p>
 <38C4F7C8.8A62367E@eh.org> <E12SMQY-0005w3-00@lsls4p>
Message-ID: <38C56958.A4BA1510@eh.org>

Edward Welbourne wrote:

>  * I would argue that, for all that they're reputedly rare, we *do* need
>    some mechanism for marking up code fragments,

OK, I personally can accept the need for arbitrary code fragments. And I can
accept the need for some guesswork in order to pick the identifiers out of
that fragment (some people here may remember me doing this on the LaTeX
documentation some years back... check out the archives). What I worry about
is that I sometimes use <code> type markup for *non* Python stuff, and I
don't really want that to be heuristicised (yeah, I just made that up) in
the same way. So perhaps what we need is a markup for code fragments (and
I'd agree that an identifier could be seen as a special instance of a code
fragment) and something else for genuine <code> markup.

So I have now rather cleverly doubled the problem space. Probably not my
best move.

>> It's mostly aesthetics.
> Nope: #code|fragment# is parseable; |code|fragment| is broken.
> No code fragment needs to include a # (outside quotes), some code
> fragments do need to use bitwise or.
> Parsers are not aesthetes.

Aesthetes? That's a word and not a Greek island? You can now see why IIRC
Eddy's based in Cambridge and I'm only in London <wink>.

OK, so | can't be used as a code fragment thingy (if we want one). I
originally thought it would only be applied to identifiers anyway...
 
> The argument *against* # is aesthetic.
> The argument *for* it is practical.
> The argument for | is aesthetic and impractical.

I'll take that as a vote against | then :)
 
> Note that | also suffers problems if someone is illustrating a unix
> shell command """... to find users of this module, cd to the python
> installation directory and use find | xargs grep to hunt for .py files
> which import it ...""".

Woah there... By that token, any single printable character you choose is a
potential Unix command line input. I'm trying to keep things a little
simpler than that (I notice we already seem to have lost everyone else on
this thread, and I'm only just about hanging in here). My first complaint
about StructuredText is that there isn't a protocol for escaping character;
if there is (and there *has* to be in my opinion. It's possibly the biggest
single ommission at the moment), then the problem goes away.

>> Not that we've agreed on an alternative yet <wink>.
> OK, am I making any progress towards persuading you ?

I remain mostly confused. Mostly over why we're arguing the toss over a
single character <wink>.

> Tibs tells me my habitual use of, e.g.
> 
>     try: val = dict[key]
>     except KeyError: val = default
> 
> is unkind to other pythoneers.

Yeah, that's fairly evil as is the whitespace abuse <wink>.


tongue-in-cheek-ly y'rs Laurie


From ke@gnu.franken.de  Tue Mar  7 21:40:37 2000
From: ke@gnu.franken.de (Karl EICHWALDER)
Date: 07 Mar 2000 22:40:37 +0100
Subject: [Doc-SIG] Re: Some random thoughts
In-Reply-To: Laurence Tratt's message of "Tue, 07 Mar 2000 20:40:56 +0000"
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de> <d827949a49.laurie@btinternet.com> <E12RxqC-0004H6-00@lsls4p> <38C41592.864063C5@eh.org> <E12SHsd-0005Xp-00@lsls4p> <38C4F7C8.8A62367E@eh.org> <E12SMQY-0005w3-00@lsls4p> <38C56958.A4BA1510@eh.org>
Message-ID: <shput65ui2.fsf@tux.gnu.franken.de>

Laurence Tratt <laurie@eh.org> writes:

|   simpler than that (I notice we already seem to have lost everyone
|   else on this thread, and I'm only just about hanging in here).

I've the feeling you just start to re-invent the minimization features
of SGML.  Why not using SGML?  SGML is _not_ "verbose", some
implementations of SGML are verbose, intentionally (TEI and DocBook);
but QWERTZ (linuxdoc) is terse.

-- 
work : ke@suse.de                          |
     : http://www.suse.de/~ke/             |          ------    ,__o
home : ke@gnu.franken.de                   |         ------   _-\_<,
     : http://www.franken.de/users/gnu/ke/ |        ------   (*)/'(*)



From laurie@eh.org  Tue Mar  7 21:57:26 2000
From: laurie@eh.org (Laurence Tratt)
Date: Tue, 07 Mar 2000 21:57:26 +0000
Subject: [Doc-SIG] Re: Some random thoughts
References: <m12RbXY-000CnDC@artcom0.artcom-gmbh.de> <d827949a49.laurie@btinternet.com> <E12RxqC-0004H6-00@lsls4p> <38C41592.864063C5@eh.org> <E12SHsd-0005Xp-00@lsls4p> <38C4F7C8.8A62367E@eh.org> <E12SMQY-0005w3-00@lsls4p> <38C56958.A4BA1510@eh.org> <shput65ui2.fsf@tux.gnu.franken.de>
Message-ID: <38C57B46.B51D7345@eh.org>

Karl EICHWALDER wrote:

> I've the feeling you just start to re-invent the minimization features
> of SGML.  Why not using SGML?  SGML is _not_ "verbose", some
> implementations of SGML are verbose, intentionally (TEI and DocBook);
> but QWERTZ (linuxdoc) is terse.

Personally I'm not that worried (but take it from me, I don't think you'd
have many happy people on this sig if you used SGML inline - SGML is
probably a little over the top), but the decision has already been taken to
a certain extent. We're supposed to get on with StructuredText or - at least
- something resembling StructuredText.

My main worry is that we will do what has happened so many times before, and
talk and talk and talk and not get anything done (discussions about this
have been going on for years). To a large extent, something is better than
nothing. The Java community has not only stolen a march on us by having
javadoc, they've had it for *ages* and they use it on virtually *everything*
and are thus reaping the rewards. And their markup is reasonably minimal
<wink>.


Laurie


From DavidA@ActiveState.com  Wed Mar  8 00:26:22 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Tue, 7 Mar 2000 16:26:22 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <38C56958.A4BA1510@eh.org>
Message-ID: <NDBBJPNCJLKKIOBLDOMJGEGOCBAA.DavidA@ActiveState.com>

> So perhaps what we need is a markup for code fragments (and
> I'd agree that an identifier could be seen as a special instance of a code
> fragment) and something else for genuine <code> markup.

Uh?  What's non-genuine code markup?

> My first complaint
> about StructuredText is that there isn't a protocol for escaping
> character;
> if there is (and there *has* to be in my opinion. It's possibly
> the biggest
> single ommission at the moment), then the problem goes away.

Fine.  How should that work?

> > Tibs tells me my habitual use of, e.g.
> >
> >     try: val = dict[key]
> >     except KeyError: val = default
> >
> > is unkind to other pythoneers.
>
> Yeah, that's fairly evil as is the whitespace abuse <wink>.

Especially because it should be spelled

  val = dict.get(key, default)

=)

-david



From tony@lsl.co.uk  Wed Mar  8 09:28:53 2000
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 8 Mar 2000 09:28:53 -0000
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <NDBBJPNCJLKKIOBLDOMJGEGOCBAA.DavidA@ActiveState.com>
Message-ID: <003b01bf88e0$b8562b50$f0c809c0@lslp7o.lsl.co.uk>

First off topic, then back on (honest)...

> Edward Welbourne wrote:
> Tibs tells me my habitual use of, e.g.
>
>     try: val = dict[key]
>     except KeyError: val = default
>
> is unkind to other pythoneers.

to which Laurence Tratt replied:
> Yeah, that's fairly evil as is the whitespace abuse <wink>.

and then David Ascher said:
> Especially because it should be spelled
>
>   val = dict.get(key, default)
>
> =)

I should point out in Eddy's defence here that the company we work for
(although not for much longer in his case) is still using Python 1.3, in
which his example is correct (if evil).

As to the debate - I don't think there *is* much disagreement. We have three
cases (I reserve the right to add more as we go on - this *is* Python, after
all):

		(PS: please excuse any misformatting - I'm
		 fighting Outlook <fx:spit> - does anyone know
		 how to get its editor out of overwrite mode?)

NB: note I'm using EXAMPLES - can we try to do this, it makes it easier for
me to think...

1. Very short code fragments inline, typically containing identifiers.
   I'm willing to mandate that they can't cross line boundaries, even,
   if someone would like that.
   For example #fred# or #self.text = 3#

   (think of TeX and the $maths$ notation, I guess). These are candidates
   for the "guess the identifier and insert a cross reference" algorithm.

   I still don't like the appearance of Eddy's choice, but am yet to be
   convinced of any other choice either...

2. Examples of code that we expect to run Tim Peter's doc test tool over
   For example:

	>>> 1+4
	5

   This does not (by Tim's argument) need delimiting in any other way, as it
   can be detected by the same mechanism that doc test itself uses.
Furthermore,
   it is (I believe) Tim's contention that examples of code like this
*should*
   be perused by doc test, so this is a Good Way of doing it. See previous
   articles in this group, and also Tim's doctest.py itself.

3. Other code stuff - examples of chunks of invalid Python code, bits of
code
   we're showing for other reasons, pieces of Fortran, etc.
   For example:

	Code:
	    C Sometimes one wants misformatted Fortran examples...
	    DO I = 1,3
	       J = J + 1

   Note that the tag "Code:" is not necessarily correct - I think we
actually
   had "Example:" in an earlier draft.

Finally, we clearly need some way of escaping characters (otherwise I can't
refer to the Python comment character in a doc string's main text, for
instance!). We can't use \ (backslash) because that's already working as an
escape character (unless we were to insist on raw strings, which is a
no-no). I hereby propose, just for something to do, that it be ~,
so we could have:

	"""This is a test docstring

	I expect somewhere there's a variable called #fred#, to which
	I expect to assign integers (e.g., #fred = 3#). However, I'll
	be sure to comment it when I do, and comments start with ~#
	(or should that be #~##?).
	"""

Do I *like* ~ as the character? No. But a proposal people can disagree with
is better than no proposal (I hope).

Tibs (am I being conciliatory or argumentative?)

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.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 jack@oratrix.nl  Wed Mar  8 10:03:28 2000
From: jack@oratrix.nl (Jack Jansen)
Date: Wed, 08 Mar 2000 11:03:28 +0100
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: Message by "Tony J Ibbs (Tibs)" <tony@lsl.co.uk> ,
 Wed, 8 Mar 2000 09:28:53 -0000 , <003b01bf88e0$b8562b50$f0c809c0@lslp7o.lsl.co.uk>
Message-ID: <20000308100329.20095370CF2@snelboot.oratrix.nl>

> I should point out in Eddy's defence here that the company we work for
> (although not for much longer in his case) [...]

You mean he's being *fired* for using incorrect Python idiom??!? Phew....






:-)
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++
Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++
www.oratrix.nl/~jack    | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm 




From Edward Welbourne <eddyw@lsl.co.uk>  Wed Mar  8 10:45:18 2000
From: Edward Welbourne <eddyw@lsl.co.uk> (Edward Welbourne)
Date: Wed, 8 Mar 2000 10:45:18 +0000
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <NDBBJPNCJLKKIOBLDOMJGEGOCBAA.DavidA@ActiveState.com>
References: <38C56958.A4BA1510@eh.org>
 <NDBBJPNCJLKKIOBLDOMJGEGOCBAA.DavidA@ActiveState.com>
Message-ID: <E12Sdxu-0007Dp-00@lsls4p>

>> >     try: val = dict[key]
>> >     except KeyError: val = default
>> Yeah, that's fairly evil as is the whitespace abuse <wink>.
> Especially because it should be spelled
>   val = dict.get(key, default)

Heh.  At the end of this week, I leave my present job and finally get to
say goodbye to python 1.3 ... but, until then,

>>> bok = {1:2}
>>> bok.get
Traceback (innermost last):
  File "<stdin>", line 1, in ?
AttributeError: get

so now you know why I don't write it like that ;^}

	Eddy.


From laurie@eh.org  Wed Mar  8 08:23:53 2000
From: laurie@eh.org (Laurence Tratt)
Date: Wed, 08 Mar 2000 08:23:53 +0000
Subject: [Doc-SIG] Some random thoughts
References: <NDBBJPNCJLKKIOBLDOMJGEGOCBAA.DavidA@ActiveState.com>
Message-ID: <38C60E18.CCFD34D3@eh.org>

David Ascher wrote:

>> So perhaps what we need is a markup for code fragments (and
>> I'd agree that an identifier could be seen as a special instance of a code
>> fragment) and something else for genuine <code> markup. 
> Uh?  What's non-genuine code markup?

Sorry, I should have made myself clearer: genuine <tt> (typewriter style)
markup. I think there's a need for both.

>> My first complaint about StructuredText is that there isn't a
>> protocol for escaping character; if there is (and there *has*
>> to be in my opinion. It's possibly the biggest
>> single ommission at the moment), then the problem goes away.
> Fine.  How should that work?

It could be as simple as using a backslash character \ much as in current
Python strings. I'm  not arguing for anything complicated, just something :)


Laurie



From laurie@eh.org  Wed Mar  8 13:19:21 2000
From: laurie@eh.org (Laurence Tratt)
Date: Wed, 08 Mar 2000 13:19:21 +0000
Subject: [Doc-SIG] Some random thoughts
References: <003b01bf88e0$b8562b50$f0c809c0@lslp7o.lsl.co.uk>
Message-ID: <38C65359.911AB2EA@eh.org>

"Tony J Ibbs (Tibs)" wrote:

> As to the debate - I don't think there *is* much disagreement. We have three
> cases 
[snip]

Yes, I think I'd agree with that.

> Finally, we clearly need some way of escaping characters (otherwise I can't
> refer to the Python comment character in a doc string's main text, for
> instance!). We can't use \ (backslash) because that's already working as an
> escape character (unless we were to insist on raw strings, which is a
> no-no). I hereby propose, just for something to do, that it be ~,
> so we could have:
> 
>         """This is a test docstring
> 
>         I expect somewhere there's a variable called #fred#, to which
>         I expect to assign integers (e.g., #fred = 3#). However, I'll
>         be sure to comment it when I do, and comments start with ~#
>         (or should that be #~##?).
>         """
> 
> Do I *like* ~ as the character? No. But a proposal people can
> disagree with is better than no proposal (I hope).

~ is plain evil in my opinion as it has a lot of history associated with it.
But you expected that <wink>. I'm not sure what to use, to be honest. At the
moment - until someone comes up with something better - I'd actually be
tempted to suggest that raw strings aren't a bad option either because at
least everyone knows, recognises and understands \ .

I'm presuming that, at least initially, we're going to use a single
character to denote an escape sequence. Looking around my keyboard, one
possibility is the backtick ` but there again, Python already uses that; but
does that preclude it?

> am I being conciliatory or argumentative?

Actually my vote goes for "#" <wink>.


Laurie



From DavidA@ActiveState.com  Wed Mar  8 18:36:02 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Wed, 8 Mar 2000 10:36:02 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <38C60E18.CCFD34D3@eh.org>
Message-ID: <NDBBJPNCJLKKIOBLDOMJAEHPCBAA.DavidA@ActiveState.com>

> Sorry, I should have made myself clearer: genuine <tt> (typewriter style)
> markup. I think there's a need for both.

Can you justify it a bit better?  IMO, <tt> is like <bold> -- it's
presentation tagging, not content tagging.  Note that I think that *this*
and **this** should correspond to <emph> and <strong> or vice versa, not
<bold> and <italic>...

--david



From DavidA@ActiveState.com  Wed Mar  8 18:36:11 2000
From: DavidA@ActiveState.com (David Ascher)
Date: Wed, 8 Mar 2000 10:36:11 -0800
Subject: [Doc-SIG] Some random thoughts
In-Reply-To: <003b01bf88e0$b8562b50$f0c809c0@lslp7o.lsl.co.uk>
Message-ID: <NDBBJPNCJLKKIOBLDOMJIEHPCBAA.DavidA@ActiveState.com>

> I should point out in Eddy's defence here that the company we work for
> (although not for much longer in his case) is still using Python 1.3, in
> which his example is correct (if evil).

I knew that.  I'm just ragging him, since I think it's about as embarassing
as admitting that you're running mission-critical systems on CP/M. =)




From pf@artcom-gmbh.de  Wed Mar  8 19:14:27 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Wed, 8 Mar 2000 20:14:27 +0100 (MET)
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
In-Reply-To: <NDBBJPNCJLKKIOBLDOMJAEHPCBAA.DavidA@ActiveState.com> from David Ascher at "Mar 8, 2000 10:36: 2 am"
Message-ID: <m12Slud-000CnDC@artcom0.artcom-gmbh.de>

> > Sorry, I should have made myself clearer: genuine <tt> (typewriter style)
> > markup. I think there's a need for both.
 
David Ascher:
> Can you justify it a bit better?  IMO, <tt> is like <bold> -- it's
> presentation tagging, not content tagging.  Note that I think that *this*
> and **this** should correspond to <emph> and <strong> or vice versa, not
> <bold> and <italic>...

A <tt> (or monospaced) tag is not only pure presentation.

For some sorts of preformatted textual material the position of the 
glyphs *carry* the *content* not the glyphs itself.  
So the use of a monospaced font in any presentation of such material
is *essential* to preserve the carried content.  Examples of such material
are ASCII art diagrams like the following, which I pasted out of the doc 
string of the standard library module 'SocketServer.py':

        +-----------+        +------------------+
        | TCPServer |------->| UnixStreamServer |
        +-----------+        +------------------+
              |
              v
        +-----------+        +--------------------+
        | UDPServer |------->| UnixDatagramServer |
        +-----------+        +--------------------+

Monospaced fonts are ugly, no question.  

But we can't live completely without them for the following sorts of 
material:
   * textual diagrams like the one above (they won't die out to soon)
   * source code snippets (have been discussed here before)
   * ASCII tables like the following one:

	Directive   | Meaning
        ------------+--------------------------------------------------
	  %a        | Locale's abbreviated weekday name. 
	  %A        | Locale's full weekday name. 
	  %b        | Locale's abbreviated month name. 
	  %B        | Locale's full month name. 
	  %c        | Locale's appropriate date and time representation. 
	  %d        | Day of the month as a decimal number [01,31]. 

     and so on.

It might be possible to define some sophisticated rules, that allow
a appealing markup of tables in doc strings, which can be automatically
recognized (analysed) by a doc string parser, but that will that will become 
difficult.  

The automatic analysis of ASCII diagrams would become even more 
challenging.  So I come to the conclusion, that a clever doc string
parser should at least be able to classify certain *paragraphs* as items
containing performatted material and tag them as <tt> or monospaced
and so causing any output formatter to leave them *as is*.

Just my thoughts, Peter.
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)


From fdrake@acm.org  Wed Mar  8 19:39:25 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 8 Mar 2000 14:39:25 -0500 (EST)
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
In-Reply-To: <m12Slud-000CnDC@artcom0.artcom-gmbh.de>
References: <NDBBJPNCJLKKIOBLDOMJAEHPCBAA.DavidA@ActiveState.com>
 <m12Slud-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <14534.44141.913532.770823@weyr.cnri.reston.va.us>

Peter Funk writes:
 > A <tt> (or monospaced) tag is not only pure presentation.

  The tt font is needed for your examples, but more than just that:
it must be recognized as a complete, pre-formatted chunk.  Whitespace, 
including line endings, must also be preserved.
  You hint that you understand this, but I think this separates your
examples from general <tt> markup support.
  I don't see any need to support arbitrary specification of a tt
font in a docstring.  We just need to recognize ASCII diagrams,
tables, and code snippets.  Heck, we don't have to understand them, or 
even tell one from the other.


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From pf@artcom-gmbh.de  Thu Mar  9 07:44:45 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Thu, 9 Mar 2000 08:44:45 +0100 (MET)
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
In-Reply-To: <14534.44141.913532.770823@weyr.cnri.reston.va.us> from "Fred L. Drake, Jr." at "Mar 8, 2000  2:39:25 pm"
Message-ID: <m12Sxcj-000CnDC@artcom0.artcom-gmbh.de>

Hi!

> Peter Funk writes:
>  > A <tt> (or monospaced) tag is not only pure presentation.

Fred L. Drake, Jr.:
>   The tt font is needed for your examples, but more than just that:
> it must be recognized as a complete, pre-formatted chunk.  Whitespace, 
> including line endings, must also be preserved.

Agreed.  That was what I meant by writing "glyph position carry
content".

>   You hint that you understand this, but I think this separates your
> examples from general <tt> markup support.
>   I don't see any need to support arbitrary specification of a tt
> font in a docstring.  We just need to recognize ASCII diagrams,
> tables, and code snippets.  Heck, we don't have to understand them, or 
> even tell one from the other.

100% agreed.  

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)


From laurie@eh.org  Thu Mar  9 08:35:10 2000
From: laurie@eh.org (Laurence Tratt)
Date: Thu, 09 Mar 2000 08:35:10 +0000
Subject: [Doc-SIG] Some random thoughts
References: <NDBBJPNCJLKKIOBLDOMJAEHPCBAA.DavidA@ActiveState.com>
Message-ID: <38C7623E.87AC3F4F@eh.org>

David Ascher wrote:

>> Sorry, I should have made myself clearer: genuine <tt> (typewriter style)
>> markup. I think there's a need for both. 
> Can you justify it a bit better?  IMO, <tt> is like <bold> -- it's
> presentation tagging, not content tagging.  Note that I think that *this*
> and **this** should correspond to <emph> and <strong> or vice versa, not
> <bold> and <italic>...

Someone (Eddy or Tibs I think - I'd do a search but netscape & leafnode
don't get on in this respect) mentioned that there are instances (and gave
examples, I think) when one wants something to come out in the <code> font
but not have a guess-the-Python-identifiers scan run over it. In the same
way that I always mentally substitute italics for emph, I'd substitute
code-font-without-substitution for tt; so long as the functionality's there
in some way, it doesn't really matter what it's called.


logical-font-styles-are-probably-great-for-logicians-ly y'rs - Laurie




From laurie@eh.org  Thu Mar  9 08:39:39 2000
From: laurie@eh.org (Laurence Tratt)
Date: Thu, 09 Mar 2000 08:39:39 +0000
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
References: <m12Slud-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <38C7634B.9F1186E3@eh.org>

Peter Funk wrote:

[The infamous SocketServer diagram]
> But we can't live completely without them for the following sorts of
> material:
>    * textual diagrams like the one above (they won't die out to soon)

There're hooks in Crystal to allow one to add code in a la JavaDoc to pull
out images[0] (gifs, jpegs etc) as dictated by a doc string and add it in
the output documentation. This would, of course, require a fair bit of
consideration as to markup, but it would probably negate the need for some
ASCII diagrams!


Laurie

[0] And anything else, in fact. But images are the most obvious example



From Edward Welbourne <eddy@chaos.org.uk>  Wed Mar  8 20:10:46 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Wed, 8 Mar 2000 20:10:46 +0000 (GMT)
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
In-Reply-To: <m12Slud-000CnDC@artcom0.artcom-gmbh.de> (pf@artcom-gmbh.de)
References: <m12Slud-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <m12Smn8-00006HC@vortigen.demon.co.uk>

Peter:
> <tt> (typewriter style)
David Ascher:
> Can you justify it a bit better?  IMO, <tt> is like <bold> -- it's
Peter:
> doc string parser should at least be able to classify certain
> *paragraphs* as items containing performatted material

Peter: you make a clear case for us to include a verbatim keyword among
the Keyword:-and-indent idioms previously considered.  What you
*haven't* made a case for is an equivalent of an *in-paragraph* form,
which is what I thought you were asking for.

I don't think anyone would disagree with the need for a Verbatim: tag to
introduce preformatted text that needs a monospaced font.  I'm fairly
sure we'd all be happy with this being a separate tag from the Code: or
Example: tag (however it gets spelled).

I wouldn't have any objection to #intext(code)# markup being used as the
standard way of indicating other kinds of code than python (in so far as
these have any place in a python doc-string); names used in such a
fragment may get recognised as python identifiers, but I don't think
that's a big deal.  So this would provide an adequate means of putting
random fragments of text into \tt mode as desired.

Is there any further need for a <TT> idiom ?

	Eddy.


From pf@artcom-gmbh.de  Fri Mar 10 21:46:14 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Fri, 10 Mar 2000 22:46:14 +0100 (MET)
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
In-Reply-To: <m12Smn8-00006HC@vortigen.demon.co.uk> from Edward Welbourne at "Mar 8, 2000  8:10:46 pm"
Message-ID: <m12TXEc-000CnDC@artcom0.artcom-gmbh.de>

Hi!

[...partly false citiations not repeated here...
    jump into the thread at  
    http://www.python.org/pipermail/doc-sig/2000-March/001828.html
]
 
Edward Welbourne wrote:
> Peter: you make a clear case for us to include a verbatim keyword among
> the Keyword:-and-indent idioms previously considered.  What you
> *haven't* made a case for is an equivalent of an *in-paragraph* form,
> which is what I thought you were asking for.

Well.  I think you missunderstood me.  So I will try to explain
it again:  From my observations and personal use of doc-strings I
see no necessity for a construct to markup arbitray *in-paragraph*
code sequences, because they are not really often needed.  So I've
no objections against the idea to using #code code# for markup of
such sequences.  But I really don't care much.

What is far more often needed is to markup *in-paragraph* uses of 
identifiers, because they should act as hyperlinks to the 
particular definition/description of the identifier in 
HTML/XML output and they should be look different from the 
surrounding text in printed documentation.  I suggested the
use of the uparrow or caret ('^') character as markup symbol:
see <http://www.python.org/pipermail/doc-sig/2000-March/001817.html>

> I don't think anyone would disagree with the need for a Verbatim: tag to
> introduce preformatted text that needs a monospaced font.  I'm fairly
> sure we'd all be happy with this being a separate tag from the Code: or
> Example: tag (however it gets spelled).

Apart from Python code examples  ---which I prefer to be marked with 
the default Python prompt ('>>>') rather than some doc "keywords" 
like Example: Code: or the like--- we have three other special
kinds of paragraphs:

 1. tables (automatic recognition without a special keyword should
    be possible --- may be I can outline some code later)
 2. figures (box diagrams) automatic recognition without a special
    keyword should also be possible here.
 3. code snippets form other languages (so markup with '>>>' would
    play havoc with doctest).  Since these should be rare, the need
    for a special Verbatim: keyword to mark these paragraphs is okay.

Regards and have a nice weekend, Peter


From laurie@eh.org  Fri Mar 10 22:10:18 2000
From: laurie@eh.org (Laurence Tratt)
Date: Fri, 10 Mar 2000 22:10:18 +0000
Subject: [Doc-SIG] <tt> tagging (was Re: Some random thoughts)
References: <m12TXEc-000CnDC@artcom0.artcom-gmbh.de>
Message-ID: <38C972CA.89EAEF09@eh.org>

Peter Funk wrote:

> Well.  I think you missunderstood me.  So I will try to explain
> it again:  From my observations and personal use of doc-strings I
> see no necessity for a construct to markup arbitray *in-paragraph*
> code sequences, because they are not really often needed.  So I've
> no objections against the idea to using #code code# for markup of
> such sequences.  But I really don't care much.
> 
> What is far more often needed is to markup *in-paragraph* uses of
> identifiers

Although I'm nowhere near as worried about this as Eddy, I do think that a
reasonable amount of doc strings might use "func(args)" in a paragraph quite
legitimitely. I don't know if that means we should necessarily allow
arbitrary chunks of code via # # or not (personally I don't see it being
used much[0]), but I think we need to think carefully before not including
the func(arg) use.


Laurie

[0] Except by Eddy :)


From fdrake@acm.org  Fri Mar 17 18:50:03 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 17 Mar 2000 13:50:03 -0500 (EST)
Subject: [Doc-SIG] new formatted 1.5.2p2 docs
Message-ID: <14546.32347.289046.57744@weyr.cnri.reston.va.us>

  I've just updated the doc packages and online copy of the 1.5.2p2
documentation release.
  The packages are available at:

	ftp://ftp.python.org/pub/python/doc/.test/

and the online copy can be viewed at:

	http://www.python.org/doc/1.5.2p2/

  I haven't done nearly as much review as I'd like, and there are a
number of issues that remain to be handled, including some comments
from the members of this SIG.  I'll be spending more time on it this
weekend (especially fixing the global module index!), but I will
release next week as long as I don't break anything substantially.
Any delay beyond that and a lot of effort would be wasted!
  (Well, most of the changes will need to be merged into the 1.6
documentation, but that's not the same thing.)
  Please keep a special lookout for problems with table presentations; 
I think it's right but that code can be somewhat fragile.  ;(  Also,
the API reference has changed a lot.
  I plan to mostly work on the extending & embedding manual this
weekend, and reviewing the structure of the library reference.
  Happy bug hunting!  ;)


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From ping@lfw.org  Fri Mar 17 16:12:22 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Fri, 17 Mar 2000 10:12:22 -0600 (CST)
Subject: [Doc-SIG] Re: [Python-Dev] list.shift()
In-Reply-To: <38D2AAF2.CFBF3A2@beopen.com>
Message-ID: <Pine.LNX.4.10.10003171009150.16549-100000@server1.lfw.org>

On Fri, 17 Mar 2000, Guido van Rossum wrote:
> You can do this using list.pop(0).  I don't think the name "shift" is very
> intuitive (smells of sh and Perl :-).  Do we need a new function?

Oh -- sorry, that's my ignorance showing.  I didn't know pop()
took an argument (of course it would -- duh...).  No need to
add anything more, then, i think.  Sorry!

Fred et al. on doc-sig: it would be really good for the tutorial 
to show a queue example and a stack example in the section where
list methods are introduced.


-- ?!ng



From ping@lfw.org  Fri Mar 17 17:28:38 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Fri, 17 Mar 2000 11:28:38 -0600 (CST)
Subject: [Doc-SIG] queues and stacks for tutorial
Message-ID: <Pine.LNX.4.10.10003171108500.16707-100000@server1.lfw.org>

Would this help?

Here's a shot at a couple more sections for chapter 5
of the tutorial, where lists are introduced.

Section 5.1, "More on Lists", introduces the list methods.
It would be nice to put these methods in alphabetical order;
or, perhaps a more logical order would be

    append    # adding things
    insert
    extend

    remove    # removing things
    pop

    index     # finding things
    count

    reverse   # reordering
    sort

I recommend putting "append" first in any case because
it is used so much more often than "insert".  The
description should be changed to not forward-reference
"insert":

    append(x)
        Append an item to the list;
        a.append(x) is equivalent to a[len(a):] = [x].

We need new entries for "extend" and "pop":

    extend(l)
        Extend the list by appending all the items in
        the given list; equivalent to a[len(a):] = l.

    pop(i)
        Remove the item at the given position in the list,
        and return it.  If no index is specified, a.pop()
        pops the last item in the list.


Move 5.1.1 to 5.1.3, and add:


    5.1.1 Using Lists as Stacks

    The list methods make it very easy to use a list as a
    stack, where the last element added is the first element
    retrieved ("last-in, first-out").  To add an item to
    the top of the stack, use append(item).  To retrieve an item
    from the top of the stack, use pop().  For example:

    >>> stack = [3, 4, 5]
    >>> stack.append(6)
    >>> stack.append(7)
    >>> stack
    [3, 4, 5, 6, 7]
    >>> stack.pop()
    7
    >>> stack
    [3, 4, 5, 6]
    >>> stack.pop()
    6
    >>> stack.pop()
    5
    >>> stack
    [3, 4]


    5.1.2 Using Lists as Queues

    You can also use a list conveniently as a queue, where
    the first element added is the first element retrieved
    ("first-in, first-out").  To add an item to the back of
    the queue, use append(item).  To retrieve an item from
    the front of the queue, use pop(0).  For example:

    >>> queue = ["Eric", "John", "Michael"]
    >>> queue.append("Terry")           # Terry arrives
    >>> queue.append("Graham")          # Graham arrives
    >>> queue.pop(0)
    'Eric'
    >>> queue.pop(0)
    'John'
    >>> queue
    ['Michael', 'Terry', 'Graham']



-- ?!ng



From hfoffani@sofrecom.com.ar  Sun Mar 19 19:08:41 2000
From: hfoffani@sofrecom.com.ar (=?iso-8859-1?Q?Hern=E1n_Mart=EDnez_Foffani?=)
Date: Sun, 19 Mar 2000 16:08:41 -0300
Subject: [Doc-SIG] "lonely" < in html 1.5.2p2 docs?
Message-ID: <000701bf91d6$8a0e8720$9501010a@pez-volador>

[May be you already saw this, but it might help...]

I run the Microsoft HTML Help Compiler version 4.74.8702 on Python docs
1.5.2p2.
It complains with the warning

HHC3004: Warning: {the-page}.html : The HTML tag "<P" is not a valid HTML
tag (it does not begin with an alphanumeric character).

on the following modules:

Cmd-objects.html
examples-imp.html
module-gopherlib.html
module-mailcap.html
module-mimify.html
module-pycompile.html
module-tty.html
module-whrandom.html
pop3-example.html
subclassing-reprs.html

Apparently they contain the following (ilegal?) html code always before the
footer of the page:
...
<P>
<
<P>
<p>
...
See the lt char or tag. You can also see it with MS and Netscape browsers.

BTW, is it ok to post this things on doc-sig? I feel it is too much.


--
Hernán Martínez Foffani        hfoffani@sofrecom.com.ar
Sofrecom Argentina S.A.       www.sofrecom.com.ar          te: 54 11 43 15
11 22




From fdrake@acm.org  Mon Mar 20 15:44:21 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 20 Mar 2000 10:44:21 -0500 (EST)
Subject: [Doc-SIG] Another snapshot
Message-ID: <14550.18261.653580.803028@weyr.cnri.reston.va.us>

  I've placed another snapshot of the documentation in the test
areas.  This version incorporates Ping's recommendations for the
tutorial (list stuff) and fixes the "lonely >" problem reported by
Hern=E1n Mart=EDnez Foffani.
  It also fixes the Global Module Index; thanks to Peter Funk for not
letting me forget about that one!
  Something is broken in my email, so I've not received *anything* for=20=

three days; hopefully I'll be able to get that fixed over the next
couple of hours, so I can see all those bug reports!  ;)  I *can* see
stuff sent to Doc-SIG through the archives, so feel free to comment on=20=

specific bugs there for now.
  I will have some additional changes for the API & Extension manuals,=20=

possibly tomorrow.


  -Fred

--
Fred L. Drake, Jr.=09  <fdrake at acm.org>
Corporation for National Research Initiatives


From fdrake@acm.org  Mon Mar 20 19:10:16 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 20 Mar 2000 14:10:16 -0500 (EST)
Subject: [Doc-SIG] my mail is working...
Message-ID: <14550.30616.382965.541371@weyr.cnri.reston.va.us>

  Ok, my email is working now; feel free to report bugs to
python-docs@python.org!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From hfoffani@sofrecom.com.ar  Mon Mar 20 19:51:37 2000
From: hfoffani@sofrecom.com.ar (Hernan Martinez Foffani)
Date: Mon, 20 Mar 2000 16:51:37 -0300
Subject: [Doc-SIG] 1.5.2p2 last weekend release
Message-ID: <002001bf92a5$b41e3180$9501010a@pez-volador>

This is a multi-part message in MIME format.

------=_NextPart_000_0021_01BF928C.8ED0F980
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 8bit

The compressed HTML is not ready yet, no?
http://www.python.org/ftp/python/doc/1.5.2p2/html-1.5.2p2.zip

-H.

--
Hernán Martínez Foffani        hfoffani@sofrecom.com.ar
Sofrecom Argentina S.A.       www.sofrecom.com.ar          te: 54 11 43 15
11 22







------=_NextPart_000_0021_01BF928C.8ED0F980
Content-Type: text/html;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD W3 HTML//EN">
<HTML>
<HEAD>

<META content=3D"text/html; charset=3Diso-8859-1" =
http-equiv=3DContent-Type>
<META content=3D'"MSHTML 4.72.3616.1301"' name=3DGENERATOR>
</HEAD>
<BODY bgColor=3D#ffffff>
<DIV><SPAN class=3D980284619-20032000><FONT color=3D#000000 face=3DArial =
size=3D2>The=20
compressed HTML is not ready yet, no?</FONT></SPAN></DIV>
<DIV><FONT color=3D#000000 size=3D2><A=20
href=3D"http://www.python.org/ftp/python/doc/1.5.2p2/html-1.5.2p2.zip">ht=
tp://www.python.org/ftp/python/doc/1.5.2p2/html-1.5.2p2.zip</A></FONT></D=
IV>
<DIV><SPAN class=3D980284619-20032000><FONT color=3D#000000 face=3DArial =

size=3D2></FONT></SPAN>&nbsp;</DIV>
<DIV><SPAN class=3D980284619-20032000><FONT color=3D#000000 face=3DArial =

size=3D2>-H.</FONT></SPAN></DIV>
<DIV>&nbsp;</DIV>
<P><FONT face=3DArial size=3D1>--<BR>Hern&aacute;n Mart&iacute;nez=20
Foffani&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </FONT><A=20
href=3D"mailto:hfoffani@sofrecom.com.ar"><FONT face=3DArial=20
size=3D1>hfoffani@sofrecom.com.ar</FONT></A><FONT face=3DArial =
size=3D1><BR>Sofrecom=20
Argentina S.A.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </FONT><A=20
href=3D"http://www.sofrecom.com.ar/"><FONT face=3DArial=20
size=3D1>www.sofrecom.com.ar</FONT></A><FONT face=3DArial=20
size=3D1>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; te: 54 =
11 43 15 11=20
22<BR><BR></FONT></P>
<P>&nbsp;</P>
<DIV>&nbsp;</DIV></BODY></HTML>

------=_NextPart_000_0021_01BF928C.8ED0F980--




From fdrake@acm.org  Mon Mar 20 21:17:24 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 20 Mar 2000 16:17:24 -0500 (EST)
Subject: [Doc-SIG] 1.5.2p2 last weekend release
In-Reply-To: <002001bf92a5$b41e3180$9501010a@pez-volador>
References: <002001bf92a5$b41e3180$9501010a@pez-volador>
Message-ID: <14550.38244.806228.79829@weyr.cnri.reston.va.us>

Hernan Martinez Foffani writes:
 > The compressed HTML is not ready yet, no?
 > http://www.python.org/ftp/python/doc/1.5.2p2/html-1.5.2p2.zip


  The staging area is at:

	http://www.python.org/ftp/python/doc/.test/

  It's up to date with the CVS repository.


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From hfoffani@sofrecom.com.ar  Mon Mar 20 22:13:49 2000
From: hfoffani@sofrecom.com.ar (Hernan Martinez Foffani)
Date: Mon, 20 Mar 2000 19:13:49 -0300
Subject: [Doc-SIG] lonely <
Message-ID: <003c01bf92b9$91a0c1e0$9501010a@pez-volador>

Fred,

One "<" (in lib/subclassing-reprs.html) slipped off your hands. :)

The Help compiler shows no other errors or warnings.

FWIW,
Docs numbers of 1.5.2 (April-99):

3,912   Topics
28,858  Local links
100     Internet links
8       Graphics

Docs numbers of 1.5.2p2 (March-2K):

4,193   Topics
31,846  Local links
106     Internet links
8       Graphics



--
Hernán Martínez Foffani        hfoffani@sofrecom.com.ar
Sofrecom Argentina S.A.       www.sofrecom.com.ar          te: 54 11 43 15
11 22




From fdrake@acm.org  Tue Mar 21 05:56:24 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Tue, 21 Mar 2000 00:56:24 -0500 (EST)
Subject: [Doc-SIG] lonely <
In-Reply-To: <003c01bf92b9$91a0c1e0$9501010a@pez-volador>
References: <003c01bf92b9$91a0c1e0$9501010a@pez-volador>
Message-ID: <14551.3848.414473.151937@weyr.cnri.reston.va.us>

Hernan Martinez Foffani writes:
 > One "<" (in lib/subclassing-reprs.html) slipped off your hands. :)

  Oops!  I missed that one in your list; sorry!  I've checked the
required change into the CVS repository.

 > The Help compiler shows no other errors or warnings.

  This is news I like to hear!

 > FWIW,
 > Docs numbers of 1.5.2 (April-99):

  Wow!  I hadn't even thought of all this in those terms!
  Now, just imagine what it'll look like when we get some rich linking 
from the SGML version!  ;)


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From ping@lfw.org  Tue Mar 21 17:13:39 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Tue, 21 Mar 2000 09:13:39 -0800 (PST)
Subject: [Doc-SIG] Python documentation review (fwd)
Message-ID: <Pine.LNX.4.10.10003210913210.850-100000@skuld.lfw.org>

... in case you didn't get this the first time.


-- ?!ng

---------- Forwarded message ----------
Date: Fri, 17 Mar 2000 08:19:14 -0600 (CST)
From: Ka-Ping Yee <ping@lfw.org>
To: fdrake@acm.org
Subject: Python documentation review

Hi Fred!

I don't know if you wanted purely technical corrections or
editorial revisions, but i've tried to keep the list down
to small things.  Here we go.  I'm going to use "-" and "+"
to indicate suggested changes (before and after).

I have also marked up these changes in the text itself.  See

    http://crit.org/http://www.python.org/doc/1.5.2p2/tut/

and look for the little red marks.

Here's the tutorial.  Actually, i didn't find much.


*** http://www.python.org/doc/1.5.2p2/tut/node4.html

2.1.2 Interactive Mode

use &nbsp; to keep example prompts on one line, as in:
  - ("<tt class="samp">&gt;&gt;&gt; </tt>")
  + ("<tt class="samp">&gt;&gt;&gt;&nbsp;</tt>")
  - by default three dots ("<tt class="samp">... </tt>").
  + by default three dots ("<tt class="samp">...&nbsp;</tt>").


*** http://www.python.org/doc/1.5.2p2/tut/node5.html

3. An Informal Introduction to Python

first paragraph, same suggestion as above (see 2.1.2)

example "A value can be assigned to several variables simultaneously:"
  - >>> x = y = z = 0  # Zero x, y and z
  + &gt;&gt;&gt; x = y = z = 0  # Assign zero to x, y and z

3.1.2 Strings

example "Unlike a C string, Python strings cannot be changed."
How about adding a suggestion of what you can do here?

  + <p>However, it's easy to just create a new string containing the
  + desired result:
  +
  + <p>
  + <dl><dd><pre class="verbatim">
  + &gt;&gt;&gt; 'x' + word[1:]
  + 'xelpA'
  + &gt;&gt;&gt; 'Splat' + word[-1:]
  + 'SplatA'
  + </pre></dl>





-- ?!ng




From ping@lfw.org  Tue Mar 21 17:14:02 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Tue, 21 Mar 2000 09:14:02 -0800 (PST)
Subject: [Doc-SIG] queues and stacks for tutorial (fwd)
Message-ID: <Pine.LNX.4.10.10003210913510.850-100000@skuld.lfw.org>

...in case you didn't get this the first time.


-- ?!ng

---------- Forwarded message ----------
Date: Fri, 17 Mar 2000 11:28:38 -0600 (CST)
From: Ka-Ping Yee <ping@lfw.org>
To: doc-sig@python.org
Subject: [Doc-SIG] queues and stacks for tutorial

Would this help?

Here's a shot at a couple more sections for chapter 5
of the tutorial, where lists are introduced.

Section 5.1, "More on Lists", introduces the list methods.
It would be nice to put these methods in alphabetical order;
or, perhaps a more logical order would be

    append    # adding things
    insert
    extend

    remove    # removing things
    pop

    index     # finding things
    count

    reverse   # reordering
    sort

I recommend putting "append" first in any case because
it is used so much more often than "insert".  The
description should be changed to not forward-reference
"insert":

    append(x)
        Append an item to the list;
        a.append(x) is equivalent to a[len(a):] = [x].

We need new entries for "extend" and "pop":

    extend(l)
        Extend the list by appending all the items in
        the given list; equivalent to a[len(a):] = l.

    pop(i)
        Remove the item at the given position in the list,
        and return it.  If no index is specified, a.pop()
        pops the last item in the list.


Move 5.1.1 to 5.1.3, and add:


    5.1.1 Using Lists as Stacks

    The list methods make it very easy to use a list as a
    stack, where the last element added is the first element
    retrieved ("last-in, first-out").  To add an item to
    the top of the stack, use append(item).  To retrieve an item
    from the top of the stack, use pop().  For example:

    >>> stack = [3, 4, 5]
    >>> stack.append(6)
    >>> stack.append(7)
    >>> stack
    [3, 4, 5, 6, 7]
    >>> stack.pop()
    7
    >>> stack
    [3, 4, 5, 6]
    >>> stack.pop()
    6
    >>> stack.pop()
    5
    >>> stack
    [3, 4]


    5.1.2 Using Lists as Queues

    You can also use a list conveniently as a queue, where
    the first element added is the first element retrieved
    ("first-in, first-out").  To add an item to the back of
    the queue, use append(item).  To retrieve an item from
    the front of the queue, use pop(0).  For example:

    >>> queue = ["Eric", "John", "Michael"]
    >>> queue.append("Terry")           # Terry arrives
    >>> queue.append("Graham")          # Graham arrives
    >>> queue.pop(0)
    'Eric'
    >>> queue.pop(0)
    'John'
    >>> queue
    ['Michael', 'Terry', 'Graham']



-- ?!ng


_______________________________________________
Doc-SIG maillist  -  Doc-SIG@python.org
http://www.python.org/mailman/listinfo/doc-sig



From fdrake@acm.org  Tue Mar 21 17:38:00 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Tue, 21 Mar 2000 12:38:00 -0500 (EST)
Subject: [Doc-SIG] Python documentation review (fwd)
In-Reply-To: <Pine.LNX.4.10.10003210913210.850-100000@skuld.lfw.org>
References: <Pine.LNX.4.10.10003210913210.850-100000@skuld.lfw.org>
Message-ID: <14551.45944.995474.613311@weyr.cnri.reston.va.us>

Ka-Ping Yee writes:
 > I don't know if you wanted purely technical corrections or
 > editorial revisions, but i've tried to keep the list down

  All of the above!  ;)

 > to small things.  Here we go.  I'm going to use "-" and "+"
 > to indicate suggested changes (before and after).

  No need to change the HTML; I've got the translate back to latex
anyway.  ;)

 > I have also marked up these changes in the text itself.  See
 > 
 >     http://crit.org/http://www.python.org/doc/1.5.2p2/tut/
 > 
 > and look for the little red marks.

  This is pretty cool!

 > 2.1.2 Interactive Mode
 > 
 > use &nbsp; to keep example prompts on one line, as in:

  Ok, I can do this (which actually surprises me!).  Both places.

 > 3.1.2 Strings
 > 
 > example "Unlike a C string, Python strings cannot be changed."
 > How about adding a suggestion of what you can do here?

  Good idea; it'll be there, with your example.
  I'll check the changes in when I've got my automounts working
again... ;(
  The changes from your other message are already checked in; thanks!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From fdrake@acm.org  Tue Mar 21 22:22:13 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Tue, 21 Mar 2000 17:22:13 -0500 (EST)
Subject: [Doc-SIG] 1.5.2p2 release candidate
Message-ID: <14551.62997.572873.355208@weyr.cnri.reston.va.us>

  I've made a release candidate for the 1.5.2p2 documentation
release.  Downloadable packages are at:

	ftp://ftp.python.org/pub/python/doc/.test/

  An online copy is available at:

	http://www.python.org/doc/1.5.2p2/

  *Please* send any bug reports to python-docs@python.org as quickly
as you can!  I'll deal with as many as I can.
  Thanks!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From fdrake@acm.org  Fri Mar 24 15:55:18 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 24 Mar 2000 10:55:18 -0500 (EST)
Subject: [Doc-SIG] Work plan forthcoming
Message-ID: <14555.36838.668325.69900@weyr.cnri.reston.va.us>

  A couple of people have asked me "What's next?", so I'm going to
write up a little plan of attack and post it to the list next week.  I 
simply haven't had time to write it yet.
  Just be aware that it's coming, so you don't have to ask.  ;)


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From hernanf@my-Deja.com  Sun Mar 26 01:12:05 2000
From: hernanf@my-Deja.com (Hernan Martinez Foffani)
Date: Sat, 25 Mar 2000 17:12:05 -0800
Subject: [Doc-SIG] MS HTML Help of 1.5.2 rel March 22 docs
Message-ID: <FFGLGBIDCKGGJCAA@my-deja.com>

[posted in comp.lang.python.announce]

The latest version of Microsoft HTML Help of Python 1.5.2 release Mar 22 2000 docs is ready for download at
http://www.orgmf.com.ar/condor/pytstuff.html

And now it keeps the last size of the window opened!
(I believe that someone asked for this a year ago...:-)

Description:
As you all know, the docs of Python are distributed in a bunch of html files. With MS HTML Help file you get all the docs in 1 compressed file of 1.6MB that has a unified content tree and full text search.

Have fun,
Hernan.

---
Hernan Martinez Foffani
hernanf@my-deja.com





--== Sent via Deja.com http://www.deja.com/ ==--
Share what you know. Learn what you don't.


From fdrake@acm.org  Sun Mar 26 04:29:56 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Sat, 25 Mar 2000 23:29:56 -0500 (EST)
Subject: [Doc-SIG] MS HTML Help of 1.5.2 rel March 22 docs
In-Reply-To: <FFGLGBIDCKGGJCAA@my-deja.com>
References: <FFGLGBIDCKGGJCAA@my-deja.com>
Message-ID: <14557.37444.821571.793639@weyr.cnri.reston.va.us>

Hernan Martinez Foffani writes:
 > And now it keeps the last size of the window opened!
 > (I believe that someone asked for this a year ago...:-)

  I don't know who asked for it, but I like the feature!
  I've added a copy of the file to the FTP area at python.org as
htmlhelp-1.5.2p2.zip, and linked to both that and your site from
doc/current/download.html.
  I still need to add download size information to that page, since
that's been requested a number of time.  If anyone has a specific
suggestion about *how* that should be presented, I'd love to hear it!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From fdrake@acm.org  Sun Mar 26 04:30:48 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Sat, 25 Mar 2000 23:30:48 -0500 (EST)
Subject: [Doc-SIG] MS HTML Help of 1.5.2 rel March 22 docs
In-Reply-To: <FFGLGBIDCKGGJCAA@my-deja.com>
References: <FFGLGBIDCKGGJCAA@my-deja.com>
Message-ID: <14557.37496.551822.888471@weyr.cnri.reston.va.us>

Hernan Martinez Foffani writes:
 > The latest version of Microsoft HTML Help of Python 1.5.2 release Mar 22 2000 docs is ready for download at
 > http://www.orgmf.com.ar/condor/pytstuff.html

  Oh, and THANK YOU!  This is what makes the Python community so
great!


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From ping@lfw.org  Sun Mar 26 09:45:27 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Sun, 26 Mar 2000 01:45:27 -0800 (PST)
Subject: [Doc-SIG] library reference contents
Message-ID: <Pine.LNX.4.10.10003260135440.2741-100000@skuld.lfw.org>

The contents page of the Library Reference has a few warts:
    
  - A few section headers (e.g. operator, pprint, repr) end in
    periods that probably ought to be deleted.  (Complete list:
    3.5, 3.23, 3.24, 3.27, 3.32, 4.2, 4.3, 4.5, 5.10, 6.13, 6.15,
    7.1, 7.6, 11.11, 11.12, 11.13, 12.13, 12.14, 14.9, 14.10, 15.4.)

  - Description of 3.28 "new" doesn't make much sense: "runtime
    implementation object creation" (probably you want to
    replace "implementation" with "instance")

  - Description of 4.3 "regex" should probably say "old" or
    "deprecated".

  - Description of 6.12 "curses" has a spelling mistake:
    "Terminal independant (sic) console handling".

  - Description of 7.14 "rlcompleter" probably ought to say
    "Completion function for GNU readline".

  - Descriptions of 11.14 "SimpleHTTPServer" and 11.15
    "CGIHTTPServer" seem strange: "A Do-Something Request Handler".
    Suggest "11.14 SimpleHTTPServer -- A simple HTTP request handler"
    and "11.16 CGIHTTPServer -- A CGI-capable HTTP request handler".

Hope this helps.



-- ?!ng

"I'm not trying not to answer the question; i'm just not answering it."
    -- Lenore Snell



From hernanf@my-Deja.com  Sun Mar 26 22:01:44 2000
From: hernanf@my-Deja.com (Hernan Martinez Foffani)
Date: Sun, 26 Mar 2000 14:01:44 -0800
Subject: [Doc-SIG] MS HTML Help of 1.5.2 rel March 22 docs
Message-ID: <JPMIMCKKDNKKJCAA@my-deja.com>

On Sat, 25 Mar 2000 23:29:56   Fred L. Drake, Jr. wrote:
>  I still need to add download size information to that page, since
>that's been requested a number of time.  If anyone has a specific
>suggestion about *how* that should be presented, I'd love to hear it!

May be including a table like this in the html page?:

 DOWNLOAD THE FORMAT THAT FITS BEST TO YOU!
+-----------------------------------+------+
| Doc. Format | Page Sz. |  URL     | Size | 
+-------------+----------+----------+------+
|             |   A4     | bla4.pdf | 4 MB |
| Acrobat     +----------+----------+------+
|             |   Letter | blalt.pdf|3.9MB |
+-------------+----------+----------+------+
|             |          |          |      |
     etc.

You get the idea.
I know it's more work, but with a little python script... No, don't look at me :-)

BTW, thanks for your words.

Regards,
-Hernan




--== Sent via Deja.com http://www.deja.com/ ==--
Share what you know. Learn what you don't.


From hernanf@my-Deja.com  Sun Mar 26 23:44:09 2000
From: hernanf@my-Deja.com (Hernan Martinez Foffani)
Date: Sun, 26 Mar 2000 15:44:09 -0800
Subject: [Doc-SIG] download size
Message-ID: <GFKNFPOEKGALJCAA@my-deja.com>

On Sun, 26 Mar 2000 14:01:44 I wrote:
>
>May be including a table like this in the html 
....
>I know it's more work, but with a little python script... No, don't look at me :-)

Just to follow python community spirit:

template = "<TR><TD>%s</TD><TD>%s</TD><TD><A HREF=" + \
	"http://www.python.org/doc/current/download/" + \
 	"%s>%s</A></TD><TD>%d KB</TD></TR>"

templtitle = "<TR><TD>%s</TD><TD>%s</TD><TD>%s</TD><TD>%s</TD></TR>"

download = [
	( "Acrobat", "A4", "doc-a4.pdf",  "doc-a4.pdf", 1500 ),
	( "Acrobat", "Letter", "doc-letter.pdf", "doc-letter.pdf", 1501 ),
	( "HTLM zip", "N/A", "html.zip", "html.zip", 1122 )
]

def showtable() :
    print "<TABLE>"
    print templtitle % ( "Doc Format", "Page Size", "URL", "Size" )
    for docformat in download:
        print template % docformat
    print "</TABLE>"
    
    
BTW, it almost took me more time to sketch the table with -, | and + than to sketch the script.
You'll do better, of course.

-H.


---
Hernan Martinez Foffani
hernanf@my-deja.com



--== Sent via Deja.com http://www.deja.com/ ==--
Share what you know. Learn what you don't.


From fdrake@acm.org  Mon Mar 27 22:07:15 2000
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Mon, 27 Mar 2000 17:07:15 -0500 (EST)
Subject: [Doc-SIG] Documentation work plan
Message-ID: <14559.56211.290250.892944@weyr.cnri.reston.va.us>

  This plan doesn't deal with source-embedded documentation; I'm
hoping that someone will write software to do the extraction.  If you
want it, please write the extractor and I can write the integration
into this plan.  ;)
  I sketched this out last night while tired, and filled it out a
little in a rush this morning.  I'm open for comments.


Python Documentation Attack Plan
================================

  1.  "Long" HTML format

      This will be a package that contains an HTML version of the
      documentation formatted to be one HTML file per chapter.  This
      is primarily for the convenience of on-demand publishers
      interested in keeping their Python material up-to-date.
      Everyone is welcome to use this, however.

      This will be released this week.

  2.  Merge 1.5.2p2 patches into 1.6 development tree

      Time to review the CVS manual again!  This will be fairly
      tedious, since the 1.5.2p2 sources changed substantially more
      than I'd expected.  I'll work on this over the next few weeks
      one manual at a time.  Don't ask how many a "few" is -- I
      honestly don't know.

  3.a.  Update for 1.6

      Integrate the Unicode documentation, update the documentation
      for strings and the string module to reflect the addition of
      string methods.  Add documentation for more modules.  Complete
      the Python/C API manual.

    b.  Write DTD for SGML documentation

      Propose a specific DTD.  It will likely shift a little as the
      conversion is finallized and the first formatting is
      implemented.

  4.  Release for 1.6

      This will still be from the LaTeX sources, due to the
      accelerated release schedule for Python 1.6.

  5.a.  Wrap up conversion scripts

      Finalize the LaTeX-to-SGML conversion.

    b.  Develop SGML->HTML conversion

      Make the SGML useful.  This needs to be a very solid conversion
      since this is what most people use and be, at first, the only
      available formatting of the documents.

  6.a.  Transfer maintenance to SGML

      No more delays!

    b.  Release from SGML

      Put the HTML & SGML in people's hands without requiring CVS
      access.

  7.  Develop typeset formats from SGML

      We need at least one typeset version for old fogeys like me.
      Probably still PDF & PostScript in two paper sizes.

  8.  Release all formats from SGML

      Let them kill trees!



  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives


From ping@lfw.org  Wed Mar 29 00:14:49 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Tue, 28 Mar 2000 18:14:49 -0600 (CST)
Subject: [Doc-SIG] Nit in "urllib" library documentation
Message-ID: <Pine.LNX.4.10.10003281813280.4220-100000@server1.lfw.org>

See

    http://www.python.org/doc/1.5.2p2/lib/module-urllib.html

The last chunk of the section on "urlopen" appears to be
repeated twice:

    The urlopen() function works transparently with proxies...
    For example (the "%" is the command prompt): 
        ...
    In a Macintosh environment, urlopen() will retrieve proxy
    information from Internet Config. 

    The urlopen() function works transparently with proxies...
    For example (the "%" is the command prompt): 
        ...
    In a Macintosh environment, urlopen() will retrieve proxy
    information from Internet Config. 


-- ?!ng



From ping@lfw.org  Wed Mar 29 03:12:08 2000
From: ping@lfw.org (Ka-Ping Yee)
Date: Tue, 28 Mar 2000 21:12:08 -0600 (CST)
Subject: [Doc-SIG] Another urllib doc glitch
Message-ID: <Pine.LNX.4.10.10003282110480.4858-100000@server1.lfw.org>

Looks like some sort of TeX conversion problem -- the
"quote" and "unquote" sections don't display the tilde
characters as intended, so they look puzzling:

    Example: quote('/connolly/') yields '/%7econnolly/'.

    Example: unquote('/%7Econnolly/') yields '/connolly/'.

The examples were probably intended to read

    Example: quote('/~connolly/') yields '/%7econnolly/'.

    Example: unquote('/%7Econnolly/') yields '/~connolly/'.


-- ?!ng



From pf@artcom-gmbh.de  Thu Mar 30 06:36:57 2000
From: pf@artcom-gmbh.de (Peter Funk)
Date: Thu, 30 Mar 2000 08:36:57 +0200 (MEST)
Subject: [Doc-SIG] Where do the HOWTO .tex sources live?
Message-ID: <m12aYZd-000CpwC@artcom0.artcom-gmbh.de>

Hi!

I wonder where the .tex sources of the several HOWTO documents live.
They are obviousy not part of the Python doc source sub tree (with
the exception of the Mac lib and Fred's doc meta howto).

Regards, Peter


From akuchlin@mems-exchange.org  Thu Mar 30 17:05:45 2000
From: akuchlin@mems-exchange.org (Andrew M. Kuchling)
Date: Thu, 30 Mar 2000 12:05:45 -0500 (EST)
Subject: [Doc-SIG] Where do the HOWTO .tex sources live?
In-Reply-To: <m12aYZd-000CpwC@artcom0.artcom-gmbh.de>
References: <m12aYZd-000CpwC@artcom0.artcom-gmbh.de>
Message-ID: <14563.35177.620745.438400@amarok.cnri.reston.va.us>

Peter Funk writes:
>I wonder where the .tex sources of the several HOWTO documents live.
>They are obviousy not part of the Python doc source sub tree (with
>the exception of the Mac lib and Fred's doc meta howto).

No, they're not part of the Doc subtree; I've discussed it with Fred
in the past, but there seems no compelling reason to put them there.

-- 
A.M. Kuchling			http://starship.python.net/crew/amk/
"There is no disputing about tastes," says the old saw. In my experience there
is little else.
  -- Robertson Davies, _Marchbanks' Almanac_



From Edward Welbourne <eddy@chaos.org.uk>  Wed Mar 29 19:12:59 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Wed, 29 Mar 2000 20:12:59 +0100 (BST)
Subject: [Doc-SIG] Another urllib doc glitch
In-Reply-To: <Pine.LNX.4.10.10003282110480.4858-100000@server1.lfw.org>
 (message from Ka-Ping Yee on Tue, 28 Mar 2000 21:12:08 -0600 (CST))
References: <Pine.LNX.4.10.10003282110480.4858-100000@server1.lfw.org>
Message-ID: <m12aNtj-00000FC@vortigen.demon.co.uk>

> Looks like some sort of TeX conversion problem ...

Yes - the ~ character is the TeX `hard space' character.
This is also important to anyone documenting the __invert__ method or
otherwise mentioning the bitwise negation operator, ~

You need to use \~ in place of ~ in the TeX sources.

	Eddy.


From Edward Welbourne <eddy@chaos.org.uk>  Thu Mar 30 18:33:20 2000
From: Edward Welbourne <eddy@chaos.org.uk> (Edward Welbourne)
Date: Thu, 30 Mar 2000 19:33:20 +0100 (BST)
Subject: [Doc-SIG] Another urllib doc glitch
In-Reply-To: <m12aNtj-00000FC@vortigen.demon.co.uk> (message from Edward
 Welbourne on Wed, 29 Mar 2000 20:12:59 +0100 (BST))
References: <Pine.LNX.4.10.10003282110480.4858-100000@server1.lfw.org> <m12aNtj-00000FC@vortigen.demon.co.uk>
Message-ID: <m12ajku-00000FC@vortigen.demon.co.uk>

> You need to use \~ in place of ~ in the TeX sources.
Sorry, that should say \~{}
since \~ takes an argument (this gives it an empty one).

      Eddy.


From S.I.Reynolds@cs.bham.ac.uk  Fri Mar 31 11:52:33 2000
From: S.I.Reynolds@cs.bham.ac.uk (Stuart Reynolds)
Date: Fri, 31 Mar 2000 12:52:33 +0100
Subject: [Doc-SIG] Pythondoc installation bugs (and fixes)
Message-ID: <38E49181.1140@cs.bham.ac.uk>

Hi Guys,

I've just installed Pythondoc (0.7) on my system and there's some bugs
in the installation (this is on Solaris with python 1.5.2).
[BTW. Does anyone know how to contact Daniel Larson? His address,
Daniel.Larsson@vasteras.mail.telia.com, keeps bouncing mail back to me.] 

- The Makefile contains some illegal end of line characters that
  cause it not to work with some versions of make. To fix run,

    .../Pythondistrib/Tools/scripts/crlf.py Makefile

- Similarly, there's something wrong with the first line of the
  "pythondoc" file that crlf.py fixes,

 % ./pythondoc
 /usr/bin/env: No such file or directory
 % crlf.py ./pythondoc
 pythondoc
 % ./pythondoc
 [works]


- when the installation zip file is unzipped, some of the files it
  outputs don't have the user write permissions set (this is just
  irritating).

- the Makefile - it doesn't copy "gui.py" into the package directory. 
  
- After fixing these and then running "make test", I get

% make test
Building HTML4 output for pythondoc in /tmp/html.
pythondoc sources in the current directory will be
sh: syntax error at line 1: `(' unexpected
*** Error code 2
make: Fatal error: Command failed for target `test'


  But otherwise the program works fine. Its a top tool.

Cheers,

Stuart

PS. The web page at,
  http://starship.skyport.net/crew/danilo/pythondoc/
stills list v0.4 as the latest version. Also, the "latest version" link
at http://starship.python.net/crew/danilo/pythondoc/README.html also
points to the v0.4 page.