From tony@lsl.co.uk  Thu Jan  4 10:57:27 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 4 Jan 2001 10:57:27 -0000
Subject: [Doc-SIG] Sad news, cause for delay
Message-ID: <005f01c0763d$2038f460$f05aa8c0@lslp7o.int.lsl.co.uk>

I was hoping to have a significant release of docutils either just
before Christmas (planning to have several hours to work on it on Friday
22nd, after colleagues had all departed work) or just after (again,
expecting to get some time to put aside for it over the break).

Unfortunately, my father became seriously ill just before Christmas, and
all plans were put on hold. He went into hospital for further tests
before New Year, and died Wednesday (yesterday) morning. Basically, he
had pancreatic cancer, which is classically caught late and about which
there's not much one can do. He was only 62, and he and my mother were
looking forwards to their retirement (with plans to live on a
narrowboat, amongst other things).

I'm not entirely sure when I'll get back to docutils work - although
strangely enough playing with the software in my head was sometimes a
useful distraction whilst otherwise sadly engaged.

In the past, I've never quite seen why people dedicate things (software,
books, etc.) to people, but I think now I understand, and you may find
that David Ascher's "paragraph tags" get extended to include a
"Dedicated-To" keyword...

Sadly,
	Tibs

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



From fdrake@acm.org  Fri Jan  5 15:07:21 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Fri, 5 Jan 2001 10:07:21 -0500 (EST)
Subject: [Doc-SIG] forwarded message from Nik Clayton
Message-ID: <14933.58153.975687.519404@cj42289-a.reston1.va.home.com>

--pmuMWX3gms
Content-Type: text/plain; charset=us-ascii
Content-Description: message body and .signature
Content-Transfer-Encoding: 7bit


  This might be interesting for anyone in the area...


  -Fred

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


--pmuMWX3gms
Content-Type: message/rfc822
Content-Description: forwarded message
Content-Transfer-Encoding: 7bit

Return-Path: <docbook-errors@lists.oasis-open.org>
Received: from mh8-sfba.mail.home.com ([24.0.95.237])
          by mail.rdc1.md.home.com (InterMail vM.4.01.03.00 201-229-121)
          with ESMTP
          id <20010105133304.BEDL10139.mail.rdc1.md.home.com@mh8-sfba.mail.home.com>
          for <fdrake01@mail.reston1.va.home.com>;
          Fri, 5 Jan 2001 05:33:04 -0800
Received: from mx8-sfba.mail.home.com (mx8-sfba.mail.home.com [24.0.95.233])
	by mh8-sfba.mail.home.com (8.9.3/8.9.0) with ESMTP id FAA24423
	for <fdrake01@home.com>; Fri, 5 Jan 2001 05:33:03 -0800 (PST)
Received: from mail.acm.org (mail.acm.org [199.222.69.4])
	by mx8-sfba.mail.home.com (8.11.1/8.11.1) with ESMTP id f05DX3P29157
	for <fdrake01@home.com>; Fri, 5 Jan 2001 05:33:03 -0800 (PST)
Received: from cnri.reston.va.us (ns.CNRI.Reston.VA.US [132.151.1.1])
	by mail.acm.org (8.9.3/8.9.3) with ESMTP id IAA57350
	for <fdrake@acm.org>; Fri, 5 Jan 2001 08:31:37 -0500
Received: from one.elistx.com (one.elistx.com [209.116.252.130])
	by cnri.reston.va.us (8.9.1a/8.9.1) with ESMTP id IAA24674
	for <fdrake@cnri.reston.va.us>; Fri, 5 Jan 2001 08:31:36 -0500 (EST)
Received: from CONVERSION-DAEMON.eListX.com by eListX.com (PMDF V6.0-24 #44856)
 id <0G6O00F01YMP2I@eListX.com> for fdrake@cnri.reston.va.us; Fri,
 05 Jan 2001 08:25:39 -0500 (EST)
Received: from ELIST-DAEMON.eListX.com by eListX.com (PMDF V6.0-24 #44856)
 id <0G6O00F04YMO2E@eListX.com>
 (original mail from nik@nothing-going-on.demon.co.uk); Fri,
 05 Jan 2001 08:25:37 -0500 (EST)
Received: from CONVERSION-DAEMON.eListX.com by eListX.com (PMDF V6.0-24 #44856)
 id <0G6O00F01YMO2C@eListX.com> for docbook@elist.lists.oasis-open.org
 (ORCPT docbook@lists.oasis-open.org); Fri, 05 Jan 2001 08:25:36 -0500 (EST)
Received: from DIRECTORY-DAEMON.eListX.com by eListX.com (PMDF V6.0-24 #44856)
 id <0G6O00F01YMN2B@eListX.com> for docbook@elist.lists.oasis-open.org
 (ORCPT docbook@lists.oasis-open.org); Fri, 05 Jan 2001 08:25:35 -0500 (EST)
Received: from nothing-going-on.demon.co.uk ([194.128.198.234])
 by eListX.com (PMDF V6.0-24 #44856) with ESMTP id <0G6O00E29YMMSE@eListX.com>
 for docbook@lists.oasis-open.org; Fri, 05 Jan 2001 08:25:35 -0500 (EST)
Received: (from nik@localhost)	by nothing-going-on.demon.co.uk (8.11.0/8.11.0)
 id f05DOeZ10582; Fri, 05 Jan 2001 13:24:40 +0000 (envelope-from nik)
Reply-to: nik@freebsd.org
Message-id: <20010105132440.A10407@canyon.nothing-going-on.org>
Organization: Nik at home, where there's nothing going on
MIME-version: 1.0
Content-type: text/plain
Content-disposition: inline
User-Agent: Mutt/1.2.5i
List-Owner: <mailto:docbook-help@lists.oasis-open.org>
List-Post: <mailto:docbook@lists.oasis-open.org>
List-Subscribe: <mailto:docbook-request@lists.oasis-open.org?body=subscribe>
List-Unsubscribe: <mailto:docbook-request@lists.oasis-open.org?body=unsubscribe>
List-Archive: <http://lists.oasis-open.org/archives/docbook>
List-Help: <http://lists.oasis-open.org/doc/email-manage.html>,
 <mailto:docbook-request@lists.oasis-open.org?body=help>
From: Nik Clayton <nik@nothing-going-on.demon.co.uk>
To: docbook@lists.oasis-open.org, doc@freebsd.org, docs@gnome.org,
        kde-doc-english@max.tat.physik.uni-tuebingen.de, oswg-discuss@oswg.org,
        feedback@linuxdoc.org
Subject: DOCBOOK: Speaking on DocBook at NordU2001, 12-16 Feb
Date: Fri, 05 Jan 2001 13:24:40 +0000

Folks,

[ I've sent this to several mailing lists where I think (and hope) it's
  appropriate.  Reply-to: points back to me, as I don't think discussion
  is likely to be appropriate for most of the lists.  As far as I'm
  aware, all the lists I've posted to are appropriate for DocBook
  related material, my apologies if I've included one that isn't.
  
  For those lists I'm foreign to, I'm the FreeBSD Documentation Project
  Manager, where we've been using DocBook and related technologies for
  the past 2 to 3 years. ]

I'm going to be speaking at the 3rd EurOpen/Usenix Conference in
Stockholm, Sweden, on Feb 15th at 13:00.  The topic is

    DocBook for Free Software Projects

I would be delighted to meet with other DocBook users, particularly
those from non-FreeBSD related projects.  I suspect there are a lot of
issues that we're all solving in similar ways, and I'm anxious to avoid
excessive reinvention of the wheel if we can avoid it.

The topic scope is rather broad, and I've only got 35 minutes or so, so
this will be an overview of DocBook and its benefits, rather than an
indepth look at all the ins and outs of writing and formatting DocBook.
I'm happy to go through more detailed topics before or after my
presentation as necessary.

More information about the conference can be found at:

    http://www.nordu.org/NordU2001/

N
-- 
Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
Telephone line, $24.95 a month.  Software, free.  USENET transmission,
hundreds if not thousands of dollars.  Thinking before posting, priceless.
Somethings in life you can't buy.  For everything else, there's MasterCard.
  -- Graham Reed, in the Scary Devil Monastery

--pmuMWX3gms--



From Juergen Hermann" <jh@web.de  Fri Jan  5 17:11:17 2001
From: Juergen Hermann" <jh@web.de (Juergen Hermann)
Date: Fri, 05 Jan 2001 18:11:17 +0100
Subject: [Doc-SIG] Regex diffs between 1.5 and 2.0
Message-ID: <m14EaNy-005G1YC@smtp.web.de>

Hi!

I recently ran into the problem that "?<!" and "?<=3D" is new in Python =

2.0 (1.5.2 emits "bad character" on the "<"). Could those differences 
be documented in section 4.2.1, like for other features (i.e. "new in 
Python 2.0").

Bye, J=FCrgen




From fdrake@acm.org  Tue Jan  9 22:58:49 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Tue, 9 Jan 2001 17:58:49 -0500 (EST)
Subject: [Doc-SIG] Updated development documentation
Message-ID: <14939.38825.218757.535010@cj42289-a.reston1.va.home.com>

  I've just updated the development version of the documentation, but
am not sure the automated notice got sent.
  This version contains a wide variety of smaller updates, plus added
documentation on the fpectl and xreadlines modules.


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


  -Fred

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



From ping@lfw.org  Thu Jan 11 16:36:36 2001
From: ping@lfw.org (Ka-Ping Yee)
Date: Thu, 11 Jan 2001 08:36:36 -0800 (PST)
Subject: [Doc-SIG] pydoc.py (show docs both inside and outside of Python)
Message-ID: <Pine.LNX.4.10.10101110803400.5846-100000@skuld.kingmanhall.org>

I'm pleased to announce a reasonable first pass at a documentation
utility for interactive use.  "pydoc" is usable in three ways:

1.  At the shell prompt, "pydoc <name>" displays documentation
    on <name>, very much like "man".

2.  At the shell prompt, "pydoc -k <keyword>" lists modules whose
    one-line descriptions mention the keyword, like "man -k".

3.  Within Python, "from pydoc import help" provides a "help"
    function to display documentation at the interpreter prompt.

All of them use sys.path in order to guarantee that the documentation
you see matches the modules you get.

To try "pydoc", download:

    http://www.lfw.org/python/pydoc.py
    http://www.lfw.org/python/htmldoc.py
    http://www.lfw.org/python/textdoc.py
    http://www.lfw.org/python/inspect.py

I would very much appreciate your feedback, especially from testing
on non-Unix platforms.  Thank you!

I've pasted some examples from my shell below (when you actually
run pydoc, the output is piped through "less", "more", or a pager
implemented in Python, depending on what is available).



-- ?!ng

"If I have seen farther than others, it is because I was standing on a
really big heap of midgets."
    -- K. Eric Drexler



skuld[1268]% pydoc -k mail
mailbox - Classes to handle Unix style, MMDF style, and MH style mailboxes.
mailcap - Mailcap file handling.  See RFC 1524.
mimify - Mimification and unmimification of mail messages.
test.test_mailbox - (no description)

skuld[1269]% pydoc -k text
textdoc - Generate text documentation from live Python objects.
collab - Routines for collaboration, especially group editing of text documents.
gettext - Internationalization and localization support.
test.test_gettext - (no description)
curses.textpad - Simple textbox editing widget with Emacs-like keybindings.
distutils.text_file - text_file
ScrolledText - (no description)

skuld[1270]% pydoc -k html
htmldoc - Generate HTML documentation from live Python objects.
htmlentitydefs - HTML character entity references.
htmllib - HTML 2.0 parser.

skuld[1271]% pydoc md5

Python Library Documentation: built-in module md5

NAME
    md5

FILE
    (built-in)

DESCRIPTION
    This module implements the interface to RSA's MD5 message digest
    algorithm (see also Internet RFC 1321). Its use is quite
    straightforward: use the new() to create an md5 object. You can now
    feed this object with arbitrary strings using the update() method, and
    at any point you can ask it for the digest (a strong kind of 128-bit
    checksum, a.k.a. ``fingerprint'') of the contatenation of the strings
    fed to it so far using the digest() method.
    
    Functions:
    
    new([arg]) -- return a new md5 object, initialized with arg if provided
    md5([arg]) -- DEPRECATED, same as new, but for compatibility
    
    Special Objects:
    
    MD5Type -- type object for md5 objects

FUNCTIONS
    md5(no arg info)
        new([arg]) -> md5 object
        
        Return a new md5 object. If arg is present, the method call update(arg)
        is made.
    
    new(no arg info)
        new([arg]) -> md5 object
        
        Return a new md5 object. If arg is present, the method call update(arg)
        is made.

skuld[1272]% pydoc types

Python Library Documentation: module types

NAME
    types

FILE
    /home/ping/sw/Python-1.5.2/Lib/types.py

DESCRIPTION
    # Define names for all type symbols known in the standard interpreter.
    # Types that are part of optional modules (e.g. array) are not listed.

skuld[1273]% pydoc abs

Python Library Documentation: built-in function abs

abs (no arg info)
    abs(number) -> number
    
    Return the absolute value of the argument.

skuld[1274]% pydoc repr             

Python Library Documentation: built-in function repr

repr (no arg info)
    repr(object) -> string
    
    Return the canonical string representation of the object.
    For most object types, eval(repr(object)) == object.


Python Library Documentation: module repr

NAME
    repr - # Redo the `...` (representation) but with limits on most sizes.

FILE
    /home/ping/sw/Python-1.5.2/Lib/repr.py

CLASSES
    Repr
    
    class Repr
        __init__(self)
        
        repr(self, x)
        
        repr1(self, x, level)
        
        repr_dictionary(self, x, level)
        
        repr_instance(self, x, level)
        
        repr_list(self, x, level)
        
        repr_long_int(self, x, level)
        
        repr_string(self, x, level)
        
        repr_tuple(self, x, level)

FUNCTIONS
    repr(no arg info)

skuld[1275]% pydoc re.MatchObject

Python Library Documentation: class MatchObject in re

class MatchObject
    __init__(self, re, string, pos, endpos, regs)
    
    end(self, g=0)
        Return the end of the substring matched by group g
    
    group(self, *groups)
        Return one or more groups of the match
    
    groupdict(self, default=None)
        Return a dictionary containing all named subgroups of the match
    
    groups(self, default=None)
        Return a tuple containing all subgroups of the match object
    
    span(self, g=0)
        Return (start, end) of the substring matched by group g
    
    start(self, g=0)
        Return the start of the substring matched by group g

skuld[1276]% pydoc xml    

Python Library Documentation: package xml

NAME
    xml - Core XML support for Python.

FILE
    /home/ping/dev/python/dist/src/Lib/xml/__init__.py

DESCRIPTION
    This package contains three sub-packages:
    
    dom -- The W3C Document Object Model.  This supports DOM Level 1 +
           Namespaces.
    
    parsers -- Python wrappers for XML parsers (currently only supports Expat).
    
    sax -- The Simple API for XML, developed by XML-Dev, led by David
           Megginson and ported to Python by Lars Marius Garshol.  This
           supports the SAX 2 API.

VERSION
    1.8

skuld[1277]% pydoc lovelyspam
no Python documentation found for lovelyspam

skuld[1278]% python
Python 1.5.2 (#1, Dec 12 2000, 02:25:44)  [GCC egcs-2.91.66 19990314/Linux (egcs- on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>>          
>>> from pydoc import help
>>> help(int)
Help on built-in function int:

int (no arg info)
    int(x) -> integer
    
    Convert a string or number to an integer, if possible.
    A floating point argument will be truncated towards zero.

>>> help("urlparse.urljoin")
Help on function urljoin in module urlparse:

urljoin(base, url, allow_fragments=1)
    # Join a base URL and a possibly relative URL to form an absolute
    # interpretation of the latter.
>>> import random
>>> help(random.generator)
Help on class generator in module random:

class generator(whrandom.whrandom)
    Random generator class.
    
    __init__(self, a=None)
        Constructor.  Seed from current time or hashable value.
    
    seed(self, a=None)
        Seed the generator from current time or hashable value.
>>> 




From jack@oratrix.nl  Fri Jan 12 09:57:27 2001
From: jack@oratrix.nl (Jack Jansen)
Date: Fri, 12 Jan 2001 10:57:27 +0100
Subject: [Doc-SIG] Re: [Python-Dev] pydoc.py (show docs both inside and outside of
 Python)
In-Reply-To: Message by Ka-Ping Yee <ping@lfw.org> ,
 Thu, 11 Jan 2001 08:36:36 -0800 (PST) , <Pine.LNX.4.10.10101110803400.5846-100000@skuld.kingmanhall.org>
Message-ID: <20010112095727.C56D13BD8B0@snelboot.oratrix.nl>

> I'm pleased to announce a reasonable first pass at a documentation
> utility for interactive use.  "pydoc" is usable in three ways:
[...]
> I would very much appreciate your feedback, especially from testing
> on non-Unix platforms.  Thank you!

Wow, I'm impressed!

To make it run on the mac I had to add tests for the existence of os.system 
only. (So all statements "if os.system(...) > 0:" got to be "if hasattr(os, 
"system") and os.system(...) > 0:").

There are however various other niceties that could be added to make it more 
useful, can this be put into the repository or something?
--
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 guido@python.org  Fri Jan 12 14:27:43 2001
From: guido@python.org (Guido van Rossum)
Date: Fri, 12 Jan 2001 09:27:43 -0500
Subject: [Doc-SIG] Re: [Python-Dev] pydoc.py (show docs both inside and outside of Python)
In-Reply-To: Your message of "Fri, 12 Jan 2001 10:57:27 +0100."
 <20010112095727.C56D13BD8B0@snelboot.oratrix.nl>
References: <20010112095727.C56D13BD8B0@snelboot.oratrix.nl>
Message-ID: <200101121427.JAA20034@cj20424-a.reston1.va.home.com>

> There are however various other niceties that could be added to make it more 
> useful, can this be put into the repository or something?

Ping, do you think you could check this in into the nondist tree?
nondist/sandbox/help would seem a good name (next to Paul's
nondist/sandbox/doctools).

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


From tony@lsl.co.uk  Mon Jan 15 14:18:36 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Mon, 15 Jan 2001 14:18:36 -0000
Subject: [Doc-SIG] pydoc.py (show docs both inside and outside of Python)
In-Reply-To: <Pine.LNX.4.10.10101110803400.5846-100000@skuld.kingmanhall.org>
Message-ID: <002801c07efe$0c728a80$f05aa8c0@lslp7o.int.lsl.co.uk>

<fx: jumps up and down in glee>

Neat stuff. Ka-Ping Yee strikes again. And it works with Python 1.5.2.

<fx: more of the same>

Running on NT (4.00.1381) in an "MS-DOS" window, using Python 1.5.2
installed in the effbot manner, it works, with the slight strangeness
that if I do:

	python pydoc.py <name>

I get the documentation for <name> OK, but it is preceded with a line
claiming that:

	The system cannot find the path specified.

I don't have the time to pursue this at the moment - it's possibly an
artefact of our system?

(one minor "prettiness" hack - those of us who have been tainted by
Emacs Lisp programming tend to start module documentation off with a
line of the form:

	<name>.py -- information about the module

which, when pydoc'ed, results in a NAME line which starts with <name>
twice...
Of course, if I'm the only person doing this, I'll just have to, well,
stop...)

A request - a "-f" switch to allow the user to specify a particular
Python file (i.e., something not on the PYTHONPATH).

Tibs

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



From ping@lfw.org  Mon Jan 15 20:10:10 2001
From: ping@lfw.org (Ka-Ping Yee)
Date: Mon, 15 Jan 2001 12:10:10 -0800 (PST)
Subject: [Python-Dev] RE: [Doc-SIG] pydoc.py (show docs both inside and
 outside of Python)
In-Reply-To: <002801c07efe$0c728a80$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <Pine.LNX.4.10.10101151155270.5846-100000@skuld.kingmanhall.org>

On Mon, 15 Jan 2001, Tony J Ibbs (Tibs) wrote:
> I get the documentation for <name> OK, but it is preceded with a line
> claiming that:
> 
> 	The system cannot find the path specified.

Thanks for the NT testing.  That's funny -- i put in a special case
for Windows to avoid messages like the above a couple of days ago.
How recently did you download pydoc.py?  Does your copy contain:

    if hasattr(sys, 'winver'):
        return lambda text: tempfilepager(text, 'more')

?

> 	<name>.py -- information about the module
> 
> which, when pydoc'ed, results in a NAME line which starts with <name>
> twice...
> Of course, if I'm the only person doing this, I'll just have to, well,
> stop...)

I think i'm going to ask you to stop, unless Guido prefers
otherwise.  Guido, do you have a style pronouncement for module
docstrings?

> A request - a "-f" switch to allow the user to specify a particular
> Python file (i.e., something not on the PYTHONPATH).

Yes, it's on my to-do list.

So you can see what i'm up to, here's my current to-do list:

    make boldness optional (only if using more/less?  only Unix?)
    document a .py file given on the command line
  + webserver in background
    help should have a repr
    write a better htmlrepr (\n should look special, max length limit, etc.)
    generate docs from lib HTML
    generate HTML index from precis and __path__ and package contents list
    have help(...) produce a directory of available things to ask for help on
    curses.wrapper is broken: both function and package
    respect package __all__
    coherent answer to .py vs .pyc: do we show .pyc?
    fix getcomments() bug: last two lines stuck together
  + grey out shadowed modules/packages
    refactor .py/.pyc/.module.so/.module.so.1 listers in htmldoc, textdoc
    skip __main__ module
  + index built-in modules too
    Windows and Mac testing
    default to HTTP mode on GUI platforms?  (win, mac)

The ones marked with + i consider done.  Feel free to comment on
or suggest priorities for the others; in particular, what do you
think of the last one?  The idea is that double-clicking on
pydoc.py in Windows or MacOS could launch the server and then open
the localhost URL using webbrowser.py to display the documentation
index.  Should it do this by default?


-- ?!ng



From guido@python.org  Mon Jan 15 20:41:25 2001
From: guido@python.org (Guido van Rossum)
Date: Mon, 15 Jan 2001 15:41:25 -0500
Subject: [Python-Dev] RE: [Doc-SIG] pydoc.py (show docs both inside and outside of Python)
In-Reply-To: Your message of "Mon, 15 Jan 2001 12:10:10 PST."
 <Pine.LNX.4.10.10101151155270.5846-100000@skuld.kingmanhall.org>
References: <Pine.LNX.4.10.10101151155270.5846-100000@skuld.kingmanhall.org>
Message-ID: <200101152041.PAA32298@cj20424-a.reston1.va.home.com>

> > 	<name>.py -- information about the module
> > 
> > which, when pydoc'ed, results in a NAME line which starts with <name>
> > twice...
> > Of course, if I'm the only person doing this, I'll just have to, well,
> > stop...)
> 
> I think i'm going to ask you to stop, unless Guido prefers
> otherwise.  Guido, do you have a style pronouncement for module
> docstrings?

I'm with Ping.  None of the examples in the style guide start the
docstring with the function name.  Almost none of the standard library
modules start their module docstring with the module name (codecs is
an exception, but I didn't write it :-).

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


From tony@lsl.co.uk  Tue Jan 16 09:47:01 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 16 Jan 2001 09:47:01 -0000
Subject: [Python-Dev] RE: [Doc-SIG] pydoc.py (show docs both inside and
 outside of Python)
In-Reply-To: <200101152041.PAA32298@cj20424-a.reston1.va.home.com>
Message-ID: <003901c07fa1$46e10c70$f05aa8c0@lslp7o.int.lsl.co.uk>

In the context of my starting doc strings in an Emacs Lisp manner,
Ka-Ping Yee said:
> I think i'm going to ask you to stop, unless Guido prefers
> otherwise.  Guido, do you have a style pronouncement for module
> docstrings?

and since Guido replied
> I'm with Ping.  None of the examples in the style guide start the
> docstring with the function name.  Almost none of the standard library
> modules start their module docstring with the module name (codecs is
> an exception, but I didn't write it :-).

I shall indeed stop (of course, my habit started before we HAD
documentation tools, and if we're going to browse things with pydoc, et
al, then there's no need for it. To be honest, it's the answer I
expected.

Oh dear, another item for my TO DO list (i.e., remove the offending
nits). Still, if it's only me it's hardly high impact!

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Which is safer, driving or cycling?
Cycling - it's harder to kill people with a bike...
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)



From tony@lsl.co.uk  Tue Jan 16 10:13:31 2001
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Tue, 16 Jan 2001 10:13:31 -0000
Subject: [Python-Dev] RE: [Doc-SIG] pydoc.py (show docs both inside and
 outside of Python)
In-Reply-To: <Pine.LNX.4.10.10101151155270.5846-100000@skuld.kingmanhall.org>
Message-ID: <003a01c07fa4$fa0883c0$f05aa8c0@lslp7o.int.lsl.co.uk>

I mentioned a "spurious"
>	The system cannot find the path specified.

on NT, and Ka-Ping Yee said:
> Thanks for the NT testing.  That's funny -- i put in a special case
> for Windows to avoid messages like the above a couple of days ago.
> How recently did you download pydoc.py?  Does your copy contain:
>
>     if hasattr(sys, 'winver'):
>         return lambda text: tempfilepager(text, 'more')

Hmm. I downloaded it when I read the email message announcing it, which
was yesterday some time. But it doesn't look like the lines you mention
are there - I'll try re-downloading...

...I've redownloaded the files from http://www.lfw.org/python/pydoc.py,
etc., and done a grep for hasattr within them. There's no check such as
the one you mention, so I guess it's "download impedance".

> So you can see what i'm up to, here's my current to-do list:
>
>     make boldness optional (only if using more/less?  only Unix?)

probably sensible. By the way, I don't get boldness on the NT box - any
chance (he says, not intending to help *at all* in doing it!) of it
happening there as well? (or would that depend on what curses support is
built into the Python?)

>     document a .py file given on the command line

also allow for a directory module (i.e., something with __init__.py in
it) given on the command line?

>     write a better htmlrepr (\n should look special, max
>     length limit, etc.)

yes, but these things can always get better - the fact it's working
allows for improoooovement down the line.

>     generate HTML index from precis and __path__ and package

a neat idea - definitely Good Stuff!

>     contents list

well, I always do these, so I'm for this one as well

>     have help(...) produce a directory of available things to
>     ask for help on

bouncy fun!

>     Windows and Mac testing

I'm running Windows 98 with Python 1.5.2 at home, and will willingly try
it out on that (after all, it's not a very big download) - although it
might sometimes take a day or two to get round to it (for instance, I
haven't yet done so!). But I suspect I shan't be a very demanding
user...

>     default to HTTP mode on GUI platforms?  (win, mac)
>
> The ones marked with + i consider done.  Feel free to comment on
> or suggest priorities for the others; in particular, what do you
> think of the last one?  The idea is that double-clicking on
> pydoc.py in Windows or MacOS could launch the server and then open
> the localhost URL using webbrowser.py to display the documentation
> index.  Should it do this by default?

I'll leave that to better designers than myself (although if one is to
*have* a double click action, that seems sensible to me).

(looks up webbrowser.py - ah, a 2.0 module). Personally, I'd also like
to have the option of having a "mini-browser" supported directly,
perhaps in Tkinter, so I don't need to start up a whole web browser. But
again I may be odd in that wish (I can't remember what IDLE does).

Oh - that also means "integrate into IDLE" presumably goes on at least a
WishList as well...

Other ideas:
* command line switch to *output* HTML to a file (i.e., documentation
generation) (presumably something like "-o <name>.html", where the
"html" indicates the output format - an alternative being "txt"
* if I ever finish the docutils effort (I should be getting back to it
soon) then use that to format the texts (this would mean I need not
worry about the "frontend" to docutils too much, since pydoc is already
doing so much). Or maybe the docutils tool should be importing pydoc...

Tibs (must do some (paid) work now!)

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




From ping@lfw.org  Tue Jan 16 10:39:37 2001
From: ping@lfw.org (Ka-Ping Yee)
Date: Tue, 16 Jan 2001 02:39:37 -0800 (PST)
Subject: [Doc-SIG] pydoc.py (show docs both inside and outside of Python)
In-Reply-To: <003a01c07fa4$fa0883c0$f05aa8c0@lslp7o.int.lsl.co.uk>
Message-ID: <Pine.LNX.4.10.10101160237480.5846-100000@skuld.kingmanhall.org>

On Tue, 16 Jan 2001, Tony J Ibbs (Tibs) wrote:
> Hmm. I downloaded it when I read the email message announcing it, which
> was yesterday some time. But it doesn't look like the lines you mention
> are there - I'll try re-downloading...
> 
> ...I've redownloaded the files from http://www.lfw.org/python/pydoc.py,
> etc., and done a grep for hasattr within them. There's no check such as
> the one you mention, so I guess it's "download impedance".

Very sorry!  I stopped uploading the files to http://www.lfw.org/python
once i started checking them in with CVS.  Kind of forgot about it, i
guess.  Please download again, and if you have time, test again; sorry
for the trouble.

> Other ideas:
> * command line switch to *output* HTML to a file (i.e., documentation
> generation) (presumably something like "-o <name>.html", where the
> "html" indicates the output format - an alternative being "txt"

Oh yeah, good point.  htmldoc.py actually does this if you run it by
itself at the moment.  Good to provide a single point of entry though.


-- ?!ng



From Tom.Fetherston@marconi.com  Wed Jan 17 19:27:47 2001
From: Tom.Fetherston@marconi.com (Fetherston, Tom)
Date: Wed, 17 Jan 2001 14:27:47 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <1DE644007776D3119FAC00204840ECF4029EDC05@whq-msgusr-03.pit.comms.marconi.com>

Hi,

I sent the folowing to the Pythonmac-sig, this might be a better place.:
----------------------------------------------------------------------------
-------------------------
Hi,

Not exactly an html list, but believe it or not this involves Python.  I
cam accross a program that would provide keyword look-ups into the Python
Html doc.  It came in too parts, a python program to parse the url's in the
genindex.html file (in the ref sub directory), it created a dictionary
(keyword : url), then it pickled that dictionary.

I updated it to use the 're' module and to handle the 2.0 doc's, instead of
pickling the dictionary, I have it write out a .tcl file, which when
sourced, provide a Tcl equivalent of the dictionary.  The second part of
this system was a elisp function to initiated a lookup from within emacs.

Noe, I changed this so command-double clicking a keyword in Alpha sends an
AppleEvent to a browser containg the Url.  Most of the urls contain
fragments (e.g. #12h-110) after the filename that are supposed to position
the relevant section in the browser for viewing, however, only Netscape
seems to accept this correctly.  ICab and IE just open the file at the top.
This is also what they do if you click the hyperlink in the index file.

!) Am I stuck with specifying Netscape as the only browser to use?

2) What is this fragment specifying?  My Html 4 ref book does not list this
kind of fragment, is it purely a Netscape extension?

Tom
---------------------------------
I got this as a reply:
-----------------------

hi-

I'm not convinced that I am really following you, but maybe this will 
help a little anyway. Generally, a url ending with # followed by a 
string is supposed to seek a named anchor, so #12h-110 would look for 
<a name="12h-110> in the target document. This works pretty much the 
same from one browser to another, so I don't think that's what's 
going on here. Another possibility is that this syntax is somehow 
being used to call the find() javascript function that is supported 
by Netscape but the last time I checked, was not supported by IE and 
probably isn't supported by iCab. This basically just triggers the 
find menu command, fills in the search string, and does the seek 
transparently once the entire target document is loaded.

So, that's my best guess and if it's correct, there's not much you 
can do but go in and hack together something in javascript that would 
trap for IE and maybe try to use textRange or something to emulate 
the find function.

Richard Gordon
--------------------

Is this right?  Seems more likely to be based on line numbers.  It does seem

to be specific to Netscape, why aren't the fragments consistent with more 
browsers?

Tom



From ping@lfw.org  Wed Jan 17 19:39:36 2001
From: ping@lfw.org (Ka-Ping Yee)
Date: Wed, 17 Jan 2001 11:39:36 -0800 (PST)
Subject: [Doc-SIG] Doc html Index only works with netscape
In-Reply-To: <1DE644007776D3119FAC00204840ECF4029EDC05@whq-msgusr-03.pit.comms.marconi.com>
Message-ID: <Pine.LNX.4.10.10101171137140.949-100000@skuld.kingmanhall.org>

On Wed, 17 Jan 2001, Fetherston, Tom wrote:
> Noe, I changed this so command-double clicking a keyword in Alpha sends an
> AppleEvent to a browser containg the Url.  Most of the urls contain
> fragments (e.g. #12h-110) after the filename that are supposed to position
> the relevant section in the browser for viewing, however, only Netscape
> seems to accept this correctly.  ICab and IE just open the file at the top.
> This is also what they do if you click the hyperlink in the index file.

The fact that they also behave this way when you click directly,
as opposed to sending an AppleEvent, tells me that this is a more
general browser issue rather than a Mac-specific or a Python-specific
thing.  I think there's a problem with your fragment syntax, but i
can't tell anything further without seeing your HTML file.  Can you
provide the URL so we can look at it?


-- ?!ng



From Tom.Fetherston@marconi.com  Wed Jan 17 19:58:30 2001
From: Tom.Fetherston@marconi.com (Fetherston, Tom)
Date: Wed, 17 Jan 2001 14:58:30 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <1DE644007776D3119FAC00204840ECF4029EDC06@whq-msgusr-03.pit.comms.marconi.com>

The urls are just those in the "C:\Python20\Doc\ref\genindex.html" file, I'm
just collecting them in the Tcl equivalent of a Dictionary of list, with the

python terms as the keys.  On both Mac and Pc, netscape translates the
fragment
into a properly positioned page with respect to the looked up term, while
Internet 
Explorer just opens each page with it's top showing.

It seems that this type of fragment (which I don't understand, and can't
find in
Html reference books) only works in Netscape.

I note that the Window download of Python has the Doc type set to netscape
docs.

Tom
doc-sig@python.org
-----Original Message-----
From: Ka-Ping Yee [mailto:ping@lfw.org]
Sent: Wednesday, January 17, 2001 2:40 PM
To: Fetherston, Tom
Cc: 'doc-sig@python.org'
Subject: Re: [Doc-SIG] Doc html Index only works with netscape


On Wed, 17 Jan 2001, Fetherston, Tom wrote:
> Noe, I changed this so command-double clicking a keyword in Alpha sends an
> AppleEvent to a browser containg the Url.  Most of the urls contain
> fragments (e.g. #12h-110) after the filename that are supposed to position
> the relevant section in the browser for viewing, however, only Netscape
> seems to accept this correctly.  ICab and IE just open the file at the
top.
> This is also what they do if you click the hyperlink in the index file.

The fact that they also behave this way when you click directly,
as opposed to sending an AppleEvent, tells me that this is a more
general browser issue rather than a Mac-specific or a Python-specific
thing.  I think there's a problem with your fragment syntax, but i
can't tell anything further without seeing your HTML file.  Can you
provide the URL so we can look at it?


-- ?!ng


From fdrake@acm.org  Wed Jan 17 20:52:50 2001
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 17 Jan 2001 15:52:50 -0500 (EST)
Subject: [Doc-SIG] Doc html Index only works with netscape
In-Reply-To: <1DE644007776D3119FAC00204840ECF4029EDC06@whq-msgusr-03.pit.comms.marconi.com>
References: <1DE644007776D3119FAC00204840ECF4029EDC06@whq-msgusr-03.pit.comms.marconi.com>
Message-ID: <14950.1570.216413.358695@cj42289-a.reston1.va.home.com>

Fetherston, Tom writes:
 > It seems that this type of fragment (which I don't understand, and can't
 > find in Html reference books) only works in Netscape.

  I'm confused by what you mean "this type of fragment" -- there's
nothing special going on here.  The first character is a lower case
"L", not the digit "1", in case that's hard to tell.

 > I note that the Window download of Python has the Doc type set to netscape
 > docs.

  This must be a Mac-specific thing; I don't know what this is about.
Do MSIE and Netscape use different file types for HTML documents on
the Mac?  (Well, I *do* remember that there are file type codes on the
Mac, I just don't know what Netscape and MSIE have to do with that.)


  -Fred

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



From Tom.Fetherston@marconi.com  Wed Jan 17 21:23:50 2001
From: Tom.Fetherston@marconi.com (Fetherston, Tom)
Date: Wed, 17 Jan 2001 16:23:50 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <1DE644007776D3119FAC00204840ECF4029EDC08@whq-msgusr-03.pit.comms.marconi.com>

file:///C:/Python20/Doc/ref/types.html#l2h-80
This is the resolved link for the "sequence object" under the 
entry for "Sequence".  Now types.html has an entry talking about
Sequences, so I assume the fragment "#l2h-80" is supposed to bring
that area into view.
This is the html source at that jpoint:

<P>
</DD>
</DL> 
<P>
</DD>
<DT><STRONG>Sequences</STRONG></DT>
<DD>These represent finite ordered sets indexed by natural numbers.
The built-in function <tt class="function">len()</tt> returns the
number of items of a sequence.
When the length of a sequence is <var>n</var>, the
index set contains the numbers 0, 1, ..., <var>n</var>-1.  Item
<var>i</var> of sequence <var>a</var> is selected by
<code><var>a</var>[<var>i</var>]</code>.

I'm unclear how "#l2h-80" refers to this point.  As Richard Gordon pointed
out,
fragments usually point to named anchor, and there isn't one here.

-----Original Message-----
From: Fred L. Drake, Jr. [mailto:fdrake@acm.org]
Sent: Wednesday, January 17, 2001 3:53 PM
To: Fetherston, Tom
Cc: Doc-SIG List
Subject: RE: [Doc-SIG] Doc html Index only works with netscape



Fetherston, Tom writes:
 > It seems that this type of fragment (which I don't understand, and can't
 > find in Html reference books) only works in Netscape.

  I'm confused by what you mean "this type of fragment" -- there's
nothing special going on here.  The first character is a lower case
"L", not the digit "1", in case that's hard to tell.

 > I note that the Window download of Python has the Doc type set to
netscape
 > docs.

  This must be a Mac-specific thing; I don't know what this is about.
Do MSIE and Netscape use different file types for HTML documents on
the Mac?  (Well, I *do* remember that there are file type codes on the
Mac, I just don't know what Netscape and MSIE have to do with that.)


  -Fred

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


From dgoodger@atsautomation.com  Thu Jan 18 22:12:26 2001
From: dgoodger@atsautomation.com (Goodger, David)
Date: Thu, 18 Jan 2001 17:12:26 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <B4A8F5EFA7E4D41184A00003470D35DEBB0E98@INTERGATE>

It seems that the anchors (<a name='l2h-80'>-type tags) are missing from
part(s) the 2.0 documentation. At least ref/types.html has discrepancies:
the anchors exist in the 1.5.2 docs, but not in the 2.0 docs. A quick check
of the online docs reveals that ... they're missing
(http://www.python.org/doc/current/ref/types.html). The latest 2.1 alpha
version does have anchors
(http://python.sourceforge.net/devel-docs/ref/types.html).

I seem to recall a message about this problem (that it was "finally
resolved! yay!") some time ago.

David Goodger (@work)
Systems Administrator & Programmer, Advanced Systems
Automation Tooling Systems Inc., Automation Systems Division
direct: (519) 653-4483 ext. 7121    fax: (519) 650-6695
e-mail: dgoodger@atsautomation.com


From Tom.Fetherston@marconi.com  Fri Jan 19 13:31:52 2001
From: Tom.Fetherston@marconi.com (Fetherston, Tom)
Date: Fri, 19 Jan 2001 08:31:52 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <1DE644007776D3119FAC00204840ECF4029EDC11@whq-msgusr-03.pit.comms.marconi.com>

Ah, that explains it, is this available gzip'ed somewhere?

What is the hoped for release date?

Tom
doc-sig@python.org
-----Original Message-----
From: Goodger, David [mailto:dgoodger@atsautomation.com]
Sent: Thursday, January 18, 2001 5:12 PM
To: Fred L. Drake, Jr.; Fetherston, Tom
Cc: Doc-SIG List
Subject: RE: [Doc-SIG] Doc html Index only works with netscape


It seems that the anchors (<a name='l2h-80'>-type tags) are missing from
part(s) the 2.0 documentation. At least ref/types.html has discrepancies:
the anchors exist in the 1.5.2 docs, but not in the 2.0 docs. A quick check
of the online docs reveals that ... they're missing
(http://www.python.org/doc/current/ref/types.html). The latest 2.1 alpha
version does have anchors
(http://python.sourceforge.net/devel-docs/ref/types.html).

I seem to recall a message about this problem (that it was "finally
resolved! yay!") some time ago.

David Goodger (@work)
Systems Administrator & Programmer, Advanced Systems
Automation Tooling Systems Inc., Automation Systems Division
direct: (519) 653-4483 ext. 7121    fax: (519) 650-6695
e-mail: dgoodger@atsautomation.com


From dgoodger@atsautomation.com  Fri Jan 19 17:44:56 2001
From: dgoodger@atsautomation.com (Goodger, David)
Date: Fri, 19 Jan 2001 12:44:56 -0500
Subject: [Doc-SIG] Doc html Index only works with netscape
Message-ID: <B4A8F5EFA7E4D41184A00003470D35DEBB1004@INTERGATE>

> Ah, that explains it, is this available gzip'ed somewhere?
> 
> What is the hoped for release date?

I understand that 2.1 alpha 1 is due out in a few days (21st?), but may slip
due to quality control. The docs should be available at the same time. I
don't know if there's any archive of the current working docs though.

/Dave