pkg/50648: Clarifications for the pkgsrc guide concerning Python packaging

[dhgutteridge%sympatico.ca@localhost]

>Number:         50648
>Category:       pkg
>Synopsis:       Clarifications for the pkgsrc guide concerning Python packaging
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Jan 11 18:05:00 +0000 2016
>Originator:     David H. Gutteridge
>Release:        current
>Organization:
>Environment:
>Description:
In 10.1.3 "Python modules and programs" of the pkgsrc guide, there are
a couple of misleading or incomplete statements. Right now, it says
"If the packaged software is a Python module, include
'../../lang/python/extension.mk'." Then further on, it discusses the
distinction between distutils.mk and egg.mk. In fact, both of those
make file components pull in extension.mk themselves. Ordinarily,
including extension.mk directly is not only unnecessary, but possibly
troublesome, since it can lead to plist-python.awk being called twice,
which breaks packaging. I think the guide should clarify that
extension.mk is only required directly if the package cannot make use
of one of distutils.mk or egg.mk.

Separately, it might be worth mentioning that Python packages that use
setuptools are supported via egg.mk. There are various references to
Python eggs, but no mention of setuptools itself. (And that both
distutils and setuptools use scripts normally named "setup.py".)

I can supply suggested changes if desired. I'm not sure if there are
extra wrinkles I'm not familiar with, though, this is all new to me.

>How-To-Repeat:
Read the guide and compare with sample packages.
>Fix: