From vsevolod@highsecure.ru  Wed Aug  3 09:41:33 2005
Return-Path: <vsevolod@highsecure.ru>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 0C4EE16A41F
	for <freebsd-gnats-submit@freebsd.org>; Wed,  3 Aug 2005 09:41:33 +0000 (GMT)
	(envelope-from vsevolod@highsecure.ru)
Received: from waterwall.inec.ru (waterwall.inec.ru [213.148.3.225])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 6FFA243D53
	for <freebsd-gnats-submit@freebsd.org>; Wed,  3 Aug 2005 09:41:31 +0000 (GMT)
	(envelope-from vsevolod@highsecure.ru)
Received: from waterwall.inec.ru (root@localhost)
  by waterwall.inec.ru (8.13.1/8.12.6) with SMTP id j739h9Lg057516
    for <freebsd-gnats-submit@freebsd.org>; Wed, 3 Aug 2005 13:43:09 +0400 (MSD)
Received: from core (postbox.inec.ru [213.148.3.226])
  by waterwall.inec.ru (8.13.1/8.12.6) with ESMTP id j739h8Jn057511
    for <FreeBSD-gnats-submit@freebsd.org>; Wed, 3 Aug 2005 13:43:08 +0400 (MSD)
Received: from [213.219.249.64] (helo=spray.anyhost.ru)
	by core with esmtp (Exim 4.51 (FreeBSD))
	id 1E0FkB-00002F-0X
	for FreeBSD-gnats-submit@freebsd.org; Wed, 03 Aug 2005 13:40:59 +0400
Received: from cebka by spray.anyhost.ru with local (Exim 4.52 (FreeBSD))
	id 1E0Fkf-000GgJ-Le
	for FreeBSD-gnats-submit@freebsd.org; Wed, 03 Aug 2005 13:41:29 +0400
Message-Id: <E1E0Fkf-000GgJ-Le@spray.anyhost.ru>
Date: Wed, 03 Aug 2005 13:41:29 +0400
From: Vsevolod Stakhov <vsevolod@freebsd.org>
Sender: Vsevolod Stakhov <vsevolod@highsecure.ru>
Reply-To: Vsevolod Stakhov <vsevolod@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Update some items at porters handbook about Python and PORTDOCS 
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>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:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Wed Aug 03 09:50:16 GMT 2005
>Closed-Date:    Tue Oct 11 22:10:23 GMT 2005
>Last-Modified:  Tue Oct 11 22:10:23 GMT 2005
>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@.
>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:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Vsevolod Stakhov <vsevolod@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/84509: Update some items at porters handbook about Python and	PORTDOCS
Date: Wed, 3 Aug 2005 14:09:16 +0300

 On 2005-08-03 13:41, Vsevolod Stakhov <vsevolod@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:
 
 	Version ranges can also be specified, by separating two version
 	numbers with a dash, e.g.: <literal>2.1-2.3</literal>
 
 >  	      <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>
 
 "This override" is wrong.  The sentence is too short for my taste too.
 I'd prefer something more verbose (and less confusing/complicated):
 
 	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><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>
 
 I think a comma is missing after "tree" in the first added sentence, the
 syntax seems a bit strange, and there's a typo in "ussually".  How about?
 
 	<entry>Location of the site-packages tree, relative to the
 	  installation path of Python (usually <makevar>LOCALBASE</makevar>).
 	  The <makevar>PYTHON_SITELIBDIR</makevar> variable can be very
 	  useful when installing Python modules.</entry>
 
 > +	    <row>
 > +	      <entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry>
 > +	      <entry>Location of the site-packages tree relative to
 > +	      	<makevar>PREFIX</makevar>.
 
 When editing the SGML docs in an editor like vi(1), vim or Emacs,
 movement by paragraphs is cool to have.  Adding an extra empty line
 between <entry> elements is probably a good idea.
 
 I'd also prefer something very similar to the above, but slightly different:
 
 	The location of the site-packages tree, relative to
 	<makevar>PREFIX</makevar>
 
 A few questions I have though, since I'm not familiar with the Ports
 system enough to find out by myself, are:
 
 	- Does this have to be a relative path?
 
 	- Can it also specify an absolute path?
 
 	- If it does point to an absolute path, does everything still
 	  work as expected?
 
 > +	      	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>
 
 Since you're touching this part, I'd also like the "Default value:" to
 be written as a full sentence, or at least separated in a paragraph of
 its own.  It's much better to read one of:
 
 	1 % Blah foo far.  The default value of WITH_X11 is "YES".
 
 	2 % Blah foo bar.
 	2 %
 	2 % Default value: YES
 
 than what we have now.
 
 > +	    <row>
 > +	      <entry><makevar>PYTHON_CMD</makevar></entry>
 > +	      <entry>Python interpreter command line including version
 > +	      number.</entry>
 
 Missing comma after "command line".
 

From: Vsevolod Stakhov <vsevolod@highsecure.ru>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: Vsevolod Stakhov <vsevolod@freebsd.org>, bug-followup@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@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
 

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

 On 2005-08-03 15:49, Vsevolod Stakhov <vsevolod@highsecure.ru> wrote:
 >On Wed, Aug 03, 2005 at 02:09:16PM +0300, Giorgos Keramidas wrote:
 >>On 2005-08-03 13:41, Vsevolod Stakhov <vsevolod@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,
 
 Cool!  That was super-fast, thanks.  The patch builds fine, and it looks
 fine, so feel free to commit it and close the PR
 
 > I'll try to improve my English grammar and style.
 
 I may have been a little more picky than necessary.  Sorry for that; it
 wasn't meant as a personal comment towards your English grammar and/or
 style.  If I have offended you and you do attend EuroBSDCon 2005, please
 let me buy you a drink or two :-)
 
State-Changed-From-To: open->closed 
State-Changed-By: pav 
State-Changed-When: Tue Oct 11 22:10:05 GMT 2005 
State-Changed-Why:  
Finished committing the last patch (python changes were already in) 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84509 
>Unformatted:
