Bug 84509

Summary:

Update some items at porters handbook about Python and PORTDOCS

Product:

Documentation

Reporter:

Vsevolod Stakhov <vsevolod>

Component:

Books & Articles

Assignee:

freebsd-doc (Nobody) <doc>

Status:

Closed FIXED

Severity:

Affects Only Me

Priority:

Normal

Version:

Latest

Hardware:

Any

OS:

Any

Attachments:

Description	Flags
file.diff	none

Description Vsevolod Stakhov freebsd_committer

2005-08-03 10:50:16 UTC

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@.

Comment 1 Giorgos Keramidas freebsd_committer

2005-08-03 12:09:16 UTC

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".

Comment 2 Vsevolod Stakhov 2005-08-03 12:49:04 UTC

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

Comment 3 Giorgos Keramidas freebsd_committer

2005-08-03 13:25:05 UTC

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 :-)

Comment 4 Pav Lucistnik freebsd_committer

2005-10-11 23:10:05 UTC

State Changed
From-To: open->closed

Finished committing the last patch (python changes were already in)