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

[Giorgos Keramidas]

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

From: Giorgos Keramidas <keramida at freebsd.org>
To: Vsevolod Stakhov <vsevolod at freebsd.org>
Cc: bug-followup at 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 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:
 
 	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".