Date: Wed, 3 Aug 2005 11:10:16 GMT From: Giorgos Keramidas <keramida@freebsd.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/84509: Update some items at porters handbook about Python and PORTDOCS Message-ID: <200508031110.j73BAG0S097632@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/84509; it has been noted by GNATS. 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".
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508031110.j73BAG0S097632>