Mailman 3 Re: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54 - Distutils-SIG

newer
compilation error

Re: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

older
distutils reference documentation...

Fred L. Drake, Jr.

13 May 2003 13 May '03

5:55 p.m.

Anthony Baxter writes:

...

It's probably worth noting that the reference manual I'm writing (see the sandbox) and the existing two Distutils docs need to interact in some way. I'm not sure what that is yet, though...

I see two possibilities, and have a fairly strong preference for one: 1. Include it in the "Distributing Python Modules" document. This makes a lot of sense, since the most common users of this documentation will be people trying to make distutils do the right thing for their package. This is also not unreasonable for people trying to extend distutils to support additional compilers, binary packages, and the like. 2. Distutils could have a chapter in the Library Reference. This isn't unreasonable, it just doesn't have anything else to recommend it. Clearly, I prefer option 1. ;-) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

Show replies by date

Anthony Baxter

13 May 13 May

11:53 p.m.

New subject: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

>>> "Fred L. Drake, Jr." wrote
>   1. Include it in the "Distributing Python Modules" document.  This
>      makes a lot of sense, since the most common users of this
>      documentation will be people trying to make distutils do the
>      right thing for their package.  This is also not unreasonable for
>      people trying to extend distutils to support additional
>      compilers, binary packages, and the like.

The problem is (for me) distinguishing between "Installing" and 
"Distributing". I'm not sure why there's two separate documents.

>   2. Distutils could have a chapter in the Library Reference.  This
>      isn't unreasonable, it just doesn't have anything else to
>      recommend it.
> 
> Clearly, I prefer option 1.  ;-)

There should probably be a bit more in the library ref about distutils -
there's a bunch of useful material in the package, and it'd be a shame
for people to re-invent the wheel again and again because they don't know
it's there. For instance, the Compiler support could easily be used by
some of the Python-based build tools. 

Anthony
-- 
Anthony Baxter        
It's never too late to have a happy childhood.

Fred L. Drake, Jr.

14 May 14 May

1:25 a.m.

New subject: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

[I've removed python-checkins from the list of recipients.] Anthony Baxter writes:

...

The problem is (for me) distinguishing between "Installing" and "Distributing". I'm not sure why there's two separate documents.

Greg and I talked about these documents a fair bit when they were first being developed, so I think I'm fairly safe in describing our intentions of the time. "Installing" should be accessible without any knowledge of the Python language. This is for system administrators who need to know how software is installed and managed on their systems. "Distributing" is for people who write setup.py scripts or otherwise work with distutils from Python. This is very specifically for people more knowledgable regarding Python and the specific software packaged using the distutils.

...

There should probably be a bit more in the library ref about distutils - there's a bunch of useful material in the package, and it'd be a shame for people to re-invent the wheel again and again because they don't know it's there. For instance, the Compiler support could easily be used by some of the Python-based build tools.

That's a possibility, and not without merit. Given the general difficulty people have in locating information about distutils, I'm not inclined to point to still more places. Would perhaps a somewhat more elaborate description in the distutils section of the library reference, with interesting index entries, be sufficient to drive people to the right places within the distutils-specific documents? -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

Anthony Baxter

3:29 a.m.

New subject: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

...

...
...
"Fred L. Drake, Jr." wrote "Installing" should be accessible without any knowledge of the Python language. This is for system administrators who need to know how software is installed and managed on their systems.

"Distributing" is for people who write setup.py scripts or otherwise work with distutils from Python. This is very specifically for people more knowledgable regarding Python and the specific software packaged using the distutils.

Ah, ok. That makes more sense. Ok, so most of the documentation goes into "Distributing". It may be that some ground that's covered in Installing also ends up (in a reduced form) in Distributing, with references to the appropriate place in the Installing documnent.

...

...
There should probably be a bit more in the library ref about distutils -

That's a possibility, and not without merit. Given the general difficulty people have in locating information about distutils, I'm not inclined to point to still more places. Would perhaps a somewhat more elaborate description in the distutils section of the library reference, with interesting index entries, be sufficient to drive people to the right places within the distutils-specific documents?

Yeah - I'd like there to at least be a basic description of the major chunks of distutils functionality (Compiler, Extension, Command, dependencies and the like) in the libref -- with pointers to the fuller reference materials in the Distributing doco... While having more places for documentation isn't a great thing, neither is having the docs in a separate document that's not obviously available. :) But for now, I'm working on just getting libref-like exhaustive documentation of all the modules, functions, methods and classes. Once that's done, massaging it into a couple of documents should be relatively painless (well, compared to the effort to document it all). Not sure if I'll get this done in time for 2.3... Hope to. Anthony -- Anthony Baxter It's never too late to have a happy childhood.

Andrew Kuchling

10:17 a.m.

New subject: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

On Wed, May 14, 2003 at 01:23:43AM -0400, Fred L. Drake, Jr. wrote:

...

"Installing" should be accessible without any knowledge of the Python language. This is for system administrators who need to know how software is installed and managed on their systems.

"Installing" is also fairly close to complete, I think. The only remaining XXX comments in it are for MacOS-related things. "Distributing" is pretty incomplete, though. --amk

7652

Age (days ago)

7653

Last active (days ago)

List overview

Download

4 comments

3 participants

participants (3)

Andrew Kuchling
Anthony Baxter
Fred L. Drake, Jr.

Re: [Python-checkins] python/dist/src/Doc/dist dist.tex,1.53,1.54

Fred L. Drake, Jr.

Anthony Baxter

Fred L. Drake, Jr.

Anthony Baxter

Andrew Kuchling

tags

participants (3)