Porter's Handbook Perl section update
Warren Block
wblock at wonkity.com
Wed May 23 20:25:18 UTC 2012
On Wed, 23 May 2012, Chris Rees wrote:
> On 23 May 2012 18:11, Warren Block <wblock at wonkity.com> wrote:
>> The second note in the Using perl section of the Porter's Handbook was
>> unclear to me:
>>
>> Note: It is recommended to avoid using ${SITE_PERL} as a dependency
>> listing. This is problematic because it means that bsd.perl.mk must be
>> included to satisfy the dependency. Additionally, if the module's files
>> change, it would require changing all dependent ports.
>>
>> After some talking with jgh@, I've suggested this:
>>
>> Do not use ${SITE_PERL} in dependency declarations. Doing so
>> assumes that bsd.perl.mk has been included, which is not always true.
>> Ports depending on this port will have incorrect dependencies if this
>> port's files move later in an upgrade. The right way to declare Perl
>> module dependencies is shown in the example below.
>>
>> The second sentence is a little weak, but overall this makes much more
>> sense, to me at least. If this looks okay, I'd like to update the Porter's
>> Handbook.
>
> [adding perl@]
>
> Please!
(Taking that as "please go ahead" rather than "please go away".)
The attached diff replaces that note, cleans up some use of commas and
minor wording, and removes <literal> tags around "Perl" when talking
about the language rather than the specific interpreter.
Capitalization is also changed as in
http://learn.perl.org/faq/perlfaq1.html#Whats-the-difference-between-perl-and-Perl-
I tried this with <application> tags around every instance of Perl, and
reading it was like listening to someone who Pronounces Capitals. One
use of <application> in the title seems adequate.
Feedback welcome. Thanks!
-------------- next part --------------
Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
===================================================================
--- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml (revision 38876)
+++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml (working copy)
@@ -5461,11 +5461,11 @@
</sect1>
<sect1 id="using-perl">
- <title>Using <literal>perl</literal></title>
+ <title>Using <application>Perl</application></title>
<para>If <makevar>MASTER_SITES</makevar> is set to
- <makevar>MASTER_SITE_PERL_CPAN</makevar>, then preferred value
- of <makevar>MASTER_SITE_SUBDIR</makevar> is top-level
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred value
+ of <makevar>MASTER_SITE_SUBDIR</makevar> is the top-level
hierarchy name. For example, the recommend value for
<literal>p5-Module-Name</literal> is
<literal>Module</literal>. The top-level hierarchy can be
@@ -5475,56 +5475,56 @@
changes.</para>
<para>The exception to this rule is when the relevant directory
- does not exist or the distfile does not exist in the
+ does not exist or the distfile does not exist in that
directory. In such case, using author's id as
<makevar>MASTER_SITE_SUBDIR</makevar> is allowed.</para>
- <para>All of the tunable knobs below accept both
- <literal>YES</literal> and a version string, like
- <literal>5.8.0+</literal>. Using <literal>YES</literal> means
- that the port can be used with all of the supported
- <application>Perl</application> versions. If a port only
+ <para>All of the tunable knobs below accept either
+ <literal>YES</literal> or a version string like
+ <literal>5.8.0+</literal>. <literal>YES</literal> means
+ that the port can be used with any of the supported
+ Perl versions. If a port only
works with specific versions of
- <application>Perl</application>, it can be indicated with a
- version string, specifying a minimal version (e.g.
- <literal>5.7.3+</literal>), a maximal version (e.g.
- <literal>5.8.0-</literal>) or an exact version (e.g.
+ Perl, it can be indicated with a
+ version string, specifying a minimum version (e.g.,
+ <literal>5.7.3+</literal>), a maximum version (e.g.,
+ <literal>5.8.0-</literal>) or an exact version (e.g.,
<literal>5.8.3</literal>).</para>
<table frame="none">
<title>Variables for Ports That Use
- <literal>perl</literal></title>
+ <application>Perl</application></title>
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
- <entry>Means</entry>
+ <entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><makevar>USE_PERL5</makevar></entry>
- <entry>Says that the port uses <literal>perl 5</literal>
+ <entry>The port uses Perl 5
to build and run.</entry>
</row>
<row>
<entry><makevar>USE_PERL5_BUILD</makevar></entry>
- <entry>Says that the port uses <literal>perl 5</literal>
+ <entry>The port uses Perl 5
to build.</entry>
</row>
<row>
<entry><makevar>USE_PERL5_RUN</makevar></entry>
- <entry>Says that the port uses <literal>perl 5</literal>
+ <entry>The port uses Perl 5
to run.</entry>
</row>
<row>
<entry><makevar>PERL</makevar></entry>
- <entry>The full path of <literal>perl 5</literal>,
+ <entry>The full path of the Perl 5 interpreter,
either in the system or installed from a port, but
without the version number. Use this if you need to
replace <quote><literal>#!</literal></quote>lines in
@@ -5555,60 +5555,61 @@
<tbody>
<row>
<entry><makevar>PERL_VERSION</makevar></entry>
- <entry>The full version of <literal>perl</literal>
+ <entry>The full version of Perl
installed (e.g., <literal>5.8.9</literal>).</entry>
</row>
<row>
<entry><makevar>PERL_LEVEL</makevar></entry>
- <entry>The installed <literal>perl</literal> version as
+ <entry>The installed Perl version as
an integer of the form <literal>MNNNPP</literal>
(e.g., <literal>500809</literal>).</entry>
</row>
<row>
<entry><makevar>PERL_ARCH</makevar></entry>
- <entry>Where <literal>perl</literal> stores architecture
+ <entry>Where Perl stores architecture
dependent libraries. Defaults to
<literal>${ARCH}-freebsd</literal>.</entry>
</row>
<row>
<entry><makevar>PERL_PORT</makevar></entry>
- <entry>Name of the <literal>perl</literal> port that is
+ <entry>Name of the Perl port that is
installed (e.g., <literal>perl5</literal>).</entry>
</row>
<row>
<entry><makevar>SITE_PERL</makevar></entry>
<entry>Directory name where site specific
- <literal>perl</literal> packages go. This value is
- added to PLIST_SUB.</entry>
+ Perl packages go. This value is
+ added to <makevar>PLIST_SUB</makevar>.</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
- <para>Ports of Perl modules, which do not have an official
- website, should link <hostid>cpan.org</hostid> in the WWW
- line of a <filename>pkg-descr</filename> file. The
+ <para>Ports of Perl modules which do not have an official
+ website should link to <hostid>cpan.org</hostid> in the WWW
+ line of <filename>pkg-descr</filename>. The
preferred URL form is
<literal>http://search.cpan.org/dist/Module-Name/</literal>
(including the trailing slash).</para>
</note>
+
<note>
- <para>It is recommended to avoid using <literal>
- ${SITE_PERL}</literal> as a dependency listing. This is
- problematic because it means that
- <filename>bsd.perl.mk</filename> must be included
- to satisfy the dependency. Additionally, if the module's
- files change, it would require changing all
- dependent ports.</para>
+ <para>Do not use <literal>${SITE_PERL}</literal> in dependency
+ declarations. Doing so assumes that
+ <filename>bsd.perl.mk</filename> has been included, which is
+ not always true. Ports depending on this port will have
+ incorrect dependencies if this port's files move later in an
+ upgrade. The right way to declare Perl module dependencies
+ is shown in the example below.</para>
</note>
<example id="use-perl-dependency-example">
- <title>PERL Dependency Example</title>
+ <title>Perl Dependency Example</title>
<programlisting>p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting>
</example>
More information about the freebsd-perl
mailing list