docs/84509: Update some items at porters handbook about Python and PORTDOCS

[Vsevolod Stakhov]

>Number:         84509
>Category:       docs
>Synopsis:       Update some items at porters handbook about Python and PORTDOCS
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 03 09:50:16 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Vsevolod Stakhov
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
>Environment:
>Description:
Some variables of bsd.python.mk can be described more than it is now.
Also PORTDOCS variable can be defined even if NOPORTDOCS defined - 
files from PORTDOCS would just not be installed in that case.
Python related changes were reviewed by pav at .
>How-To-Repeat:
>Fix:

Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.596
diff -u -r1.596 book.sgml
--- book.sgml	25 Jul 2005 13:31:09 -0000	1.596
+++ book.sgml	3 Aug 2005 07:41:37 -0000
@@ -5071,7 +5071,8 @@
 	      <entry><makevar>USE_PYTHON</makevar></entry>
 
 	      <entry>The port needs Python.  Minimal required version can be
-		specified with values such as <literal>2.3+</literal>.</entry>
+		specified with values such as <literal>2.3+</literal>.
+		Also versions range can be specified: <literal>2.1-2.3</literal></entry>
 	    </row>
 
 	    <row>
@@ -5079,7 +5080,9 @@
 
 	      <entry>Use Python distutils for configuring, compiling and
 		installing.  This is required when the port comes with
-		<filename>setup.py</filename>.</entry>
+		<filename>setup.py</filename>. This override targets:
+		do-configure (if <makevar>GNU_CONFIGURE</makevar> is not
+		defined), do-build and do-install.</entry>
 	    </row>
 
 	    <row>
@@ -5093,23 +5096,38 @@
 	    <row>
 	      <entry><makevar>PYTHON_SITELIBDIR</makevar></entry>
 
-	      <entry>Location of the site-packages tree. Useful when installing
-		Python modules.  Always use
+	      <entry>Location of the site-packages tree relative to python
+	      	installation path (ussually <makevar>LOCALBASE</makevar>). 
+	      	Useful when installing Python modules.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry>
+	      <entry>Location of the site-packages tree relative to 
+	      	<makevar>PREFIX</makevar>.
+	      	Always use
 		<literal>%%PYTHON_SITELIBDIR%%</literal> in
 		<filename>pkg-plist</filename> when possible.  Default value:
-		<literal>lib/python2.4/site-packages</literal></entry>
+		<literal>lib/python%%PYTHON_VERSION%%/site-packages</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>PYTHON_CMD</makevar></entry>
+	      <entry>Python interpreter command line including version
+	      number.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>PYNUMERIC</makevar></entry>
 
-	      <entry>Add dependency on numeric extension.</entry>
+	      <entry>Dependency line for numeric extension.</entry>
 	    </row>
 
 	    <row>
 	      <entry><makevar>PYXML</makevar></entry>
 
-	      <entry>Add dependency on XML extension.</entry>
+	      <entry>Dependency line for XML extension (not needed for
+	      Python 2.0 and higher as it is also in base distribution).</entry>
 	    </row>
 
 	    <row>
@@ -8711,16 +8729,16 @@
 	  If a directory is listed in <makevar>PORTDOCS</makevar>
 	  or matched by a glob pattern from this variable,
 	  the entire subtree of contained files and directories will be
-	  registered in the final packing list.  <makevar>PORTDOCS</makevar>
-	  should not be set if <makevar>NOPORTDOCS</makevar> is in
-	  effect.  Installing the documentation at <makevar>PORTDOCS</makevar>
+	  registered in the final packing list. If <makevar>NOPORTDOCS</makevar>
+	  is defined then files and directories listed in 
+	  <makevar>PORTDOCS</makevar> would not be installed and neither
+	  would be added to port packing list.
+	  Installing the documentation at <makevar>PORTDOCS</makevar>
 	  as shown above remains up to the port itself.
 	  A typical example of utilizing <makevar>PORTDOCS</makevar>
 	  looks as follows:</para>
 
-        <programlisting>.if !defined(NOPORTDOCS)
-        PORTDOCS=       *
-.endif</programlisting>
+        <programlisting>PORTDOCS=       README.* ChangeLog docs/*</programlisting>
 
 	<note>
 	  <para>You can also use the <filename>pkg-message</filename> file to

>Release-Note:
>Audit-Trail:
>Unformatted: