[Distutils] Internal documentation for egg formats now available

[Phillip J. Eby]

To satisfy requests on Python-Dev, I've just added some internal 
"developer's" documentation to setuptools.  You don't need to read it 
unless you are working on setuptools itself, want to assist in 
troubleshooting a problem with your installation, or want to understand how 
setuptools may affect your packaging of libraries that use it (i.e., you're 
building RPMs or debs or what-have-you for packages that use setuptools, or 
any Python 2.5 package).

The docs can be found at 
http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt 
(source text), or http://peak.telecommunity.com/DevCenter/EggFormats 
(HTML-formatted version).

Included are summary descriptions of the formats of all of the standard 
metadata produced by setuptools, along with pointers to the existing 
manuals that describe the syntax used for representing requirements, entry 
points, etc. as text.  The .egg, .egg-info, and .egg-link formats and 
layouts are also specified, along with the filename syntax used to embed 
project/version/Python version/platform metadata.  Last, but not least, 
there are detailed explanations of how resources (such as C extensions) are 
extracted on-the-fly and cached, how C extensions get imported from 
zipfiles, and how EasyInstall works around the limitations of Python's 
default sys.path initialization.

Please remember, however, that a lot of this stuff is purely internal 
details and subject to change.  Most of the information is also available 
to you directly via the "pkg_resources" API, so you probably don't care 
about the actual file formats in such cases anyway.