Clarify python *.mk usage.

Addresses PR 50648 by David H. Gutteridge.

1 files changed, 19 insertions, 18 deletions

diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index 6533cd0bf1a..7bb6babffe2 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.19 2015/04/14 11:21:05 wiz Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.20 2016/01/12 12:03:39 wiz Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -145,9 +145,24 @@ PYTHON_VERSIONS_INCOMPATIBLE=       27
 </programlisting></para>
 
 <para>
-If the packaged software is a Python module, include
-<quote><filename>../../lang/python/extension.mk</filename></quote>.
-In this case, the package directory should be called
+If the packaged software is a Python module, include one of
+<filename>../../lang/python/egg.mk</filename>,
+<filename>../../lang/python/distutils.mk</filename>, or
+<filename>../../lang/python/extension.mk</filename>.</para>
+
+<para>Most Python packages use either <quote>distutils</quote> or
+easy-setup/setuptools (<quote>eggs</quote>).
+if the packaged software is using setuptools, you only need
+to include <quote><filename>../../lang/python/egg.mk</filename></quote>.
+Otherwise, if the software uses <quote>distutils</quote>, include 
+<quote><filename>../../lang/python/distutils.mk</filename></quote>.
+so pkgsrc will use this framework.
+<quote>distutils</quote> uses a script called <filename>setup.py</filename>,
+if the <quote>distutils</quote> driver is not called
+<filename>setup.py</filename>, set the <varname>PYSETUP</varname> variable
+to the name of the script.</para>
+
+<para>Either way, the package directory should be called
 <quote>py-software</quote> and <varname>PKGNAME</varname> should be set to
 <quote>${PYPKGPREFIX}-${DISTNAME}</quote>, e.g.
 <programlisting>
@@ -165,20 +180,6 @@ For example:
 REPLACE_PYTHON=   *.py
 </programlisting></para>
 
-<para>Most Python packages use either <quote>distutils</quote> or
-easy-setup (<quote>eggs</quote>).
-If the software uses <quote>distutils</quote>, include 
-<quote><filename>../../lang/python/distutils.mk</filename></quote>.
-so pkgsrc will use this framework.
-<quote>distutils</quote> uses a script called <filename>setup.py</filename>,
-if the <quote>distutils</quote> driver is not called
-<filename>setup.py</filename>, set the <varname>PYSETUP</varname> variable
-to the name of the script.</para>
-
-<para>Otherwise, if the packaged software is egg-aware, you only need
-to include
-<quote><filename>../../lang/python/egg.mk</filename></quote>.</para>
-
 <para>Some Python modules have separate distributions for Python-2.x
 and Python-3.x support. In pkgsrc this is handled by the
 <filename>versioned_dependencies.mk</filename> file. Set