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

[Vsevolod Stakhov]

The following reply was made to PR docs/84509; it has been noted by GNATS.

From: Vsevolod Stakhov <vsevolod at highsecure.ru>
To: Giorgos Keramidas <keramida at freebsd.org>
Cc: Vsevolod Stakhov <vsevolod at freebsd.org>, bug-followup at freebsd.org
Subject: Re: docs/84509: Update some items at porters handbook about Python and	PORTDOCS
Date: Wed, 3 Aug 2005 15:49:04 +0400

 On Wed, Aug 03, 2005 at 02:09:16PM +0300, Giorgos Keramidas wrote:
 > On 2005-08-03 13:41, Vsevolod Stakhov <vsevolod at freebsd.org> wrote:
 > >  	      <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>
 > 
 > No, please.  The syntax of the new sentence is horrible.  Perhaps
 > something like this would be ok:
 
 Ok, thanks a lot, I've prepared modified version of this patch. Sorry,
 I'll try to improve my English grammar and style.
 
 
 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 11:46:21 -0000
 @@ -5071,7 +5071,9 @@
  	      <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>.
 +		Version ranges can also be specified, by separating two version
 +		numbers with a dash, e.g.: <literal>2.1-2.3</literal></entry>
  	    </row>
  
  	    <row>
 @@ -5079,7 +5081,11 @@
  
  	      <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 overrides the 
 +		<maketarget>do-build</maketarget> and 
 +		<maketarget>do-install</maketarget> targets
 +		and may also override <maketarget>do-configure</maketarget> if
 +		<makevar>GNU_CONFIGURE</makevar> is not defined.</entry>
  	    </row>
  
  	    <row>
 @@ -5093,23 +5099,41 @@
  	    <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, that contains
 +		installation path of Python (usually <makevar>LOCALBASE</makevar>).
 +		The <makevar>PYTHON_SITELIBDIR</makevar> variable can be very
 +	 	useful when installing Python modules.</entry>
 +	    </row>
 +	    
 +	    <row>
 +	      <entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry>
 +	      
 +	      <entry>The PREFIX-clean variant of PYTHON_SITELIBDIR.
 +	      	Always use
  		<literal>%%PYTHON_SITELIBDIR%%</literal> in
 -		<filename>pkg-plist</filename> when possible.  Default value:
 -		<literal>lib/python2.4/site-packages</literal></entry>
 +		<filename>pkg-plist</filename> when possible. The default value of
 +		<literal>%%PYTHON_SITELIBDIR%%</literal> is
 +		<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 +8735,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