[Python-Dev] Searching Python docs (Was: Python sidebar for Mozilla/Netscape)

[Tim Peters]

[Tim]
>> If Fred volunteers to produce .chm files in time for a release,
>> I'll ship 'em.  Don't hold your breath <wink>.
>> our-support-for-the-windows-distro-is-bug-driven-ly y'rs  - tim

[John Machin]
> Tim's tag-line might explain it all to me if I could nut
> outexactly what he meant.

I mean that if you look at any change to the PLabs Windows installer checked
in since I started doing it, it's in response to a bug, or to a change in
the structure of Python components (files moving around, getting added,
getting removed).  IIRC, the only exception (== "new feature" not addressing
a use problem) was to add an "Edit with IDLE" context menu entry for .py
files, requested by Guido.

> However, blundering on in blissful ignorance of the logistics,
> legalities, real-politik, etc:
>
> Premises:
> (1) .chm format is better for the windows distro than the .html format

I prefer HTML myself, but I confess I rarely need to *search* for things in
the docs (and when I do, I grep over the raw .tex files -- not a realistic
option for my sisters <wink>).

> (2) [not sure why Tim used the plural "files"] One big .chm file
> is better than multiple smaller ones -- e.g. will find
> PyArg_BuildValue() without the punter needing to know whether it's
> in the the E&E manual or in the C API manual :-)

Sure.  Packing over 1,000 HTML files into the installer bloats it too (it
uses zip format, and doesn't appear to exploit opportunities for x-file
compression).

> (3) A script can be developed [Hernan presumably has at least the
> foundation for this] to create the .chm file from the .html files
> so that producing the .chm file at release time requires neither
> volunteer nor conscript intervention ...

Possibly, but the idea that a new software process involving many megabytes
of data won't create new time sinks isn't credible to me.  Fred takes pride
in the appearance of his docs, so won't want to let small points slide
either.

> And some afterthoughts on Tim's tagline, which in my ignorance I
> interpreted as indicative  of a somewhat reactive attitude to the win32
> distro [I'd be utterly delighted to be corrected if I'm wrong]:

All work on the Windows installer comes out of "bug fixing" time or out of
my sleep.  It's not purely reactive, but there are no development plans for
it, and, e.g., I doubt PLabs will ever produce an MSI installer.
ActiveState's installers have been better for some time already, and I
expect the gap to widen.  All the work PLabs can do here is charity work
(either my volunteer time, or Zope Corp indirectly donating the value of my
salary) -- we don't get a penny out of this.

> (1) Judging from the traffic on c.l.py,  Python seems to have reached
> the point in a language's life cycle where it is attracting many novice
> users.

My inbox is a better judge of that <wink>.  It sure is.

> My guess is that most of those will be using the win32 distribution.

Seems likely.

> Many of them will no doubt refuse to RTFM, but for those who will,
> providing them with the docs in .chm format (and actively promoting it)
> might cut down on the "support cost" of the traffic on c.l.py.

Perhaps ActiveState could address that from experience.

> (2) In two application development shops with which I am engaged,
> the main application runs on a large Unix box, but the developers' and
> DBAs' workstations are  Windows (2000) PCs -- is this atypical?

Don't know.

> I am evangelising Python to them -- while certainly not critical,
> better doc formats, positive attitude to win32 distro, etc etc
> wouldn't hurt.

I'm committed to producing a working Win32 installer for the core Python
distribution.  PLabs can't afford to commit to more than that unless someone
steps up to fund it, or volunteers to do new work.  I have a sterling
attitude toward peace in the Middle East too <wink>.