Update the Using Perl section. Some wording and markup corrections, and

a rewording of the note about not using ${SITE_PERL}.

Reviewed by:	jgh, crees, swills

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -5461,12 +5461,12 @@ PLIST_SUB+=		NLS="@comment "
     </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
+	<makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred value
-	of <makevar>MASTER_SITE_SUBDIR</makevar> is top-level
+	of <makevar>MASTER_SITE_SUBDIR</makevar> is the top-level
-	hierarchy name.  For example, the recommend value for
+	hierarchy name.  For example, the recommended value for
 	<literal>p5-Module-Name</literal> is
 	<literal>Module</literal>.  The top-level hierarchy can be
 	examined at <ulink
@@ -5475,56 +5475,56 @@ PLIST_SUB+=		NLS="@comment "
 	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
+      <para>All of the tunable knobs below accept either
-	<literal>YES</literal> and a version string, like
+	<literal>YES</literal> or a version string like
-	<literal>5.8.0+</literal>.  Using <literal>YES</literal> means
+	<literal>5.8.0+</literal>.  <literal>YES</literal> means
-	that the port can be used with all of the supported
+	that the port can be used with any of the supported
-	<application>Perl</application> versions.  If a port only
+	Perl versions.  If a port only
 	works with specific versions of
-	<application>Perl</application>, it can be indicated with a
+	Perl, it can be indicated with a
-	version string, specifying a minimal version (e.g.
+	version string, specifying a minimum version (e.g.,
-	<literal>5.7.3+</literal>), a maximal 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.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 @@ PLIST_SUB+=		NLS="@comment "
 	  <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
+		Perl packages go.  This value is
-		added to PLIST_SUB.</entry>
+		added to <makevar>PLIST_SUB</makevar>.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
       </table>
 
       <note>
-	<para>Ports of Perl modules, which do not have an official
+	<para>Ports of Perl modules which do not have an official
-	  website, should link <hostid>cpan.org</hostid> in the WWW
+	  website should link to <hostid>cpan.org</hostid> in the WWW
-	  line of a <filename>pkg-descr</filename> file.  The
+	  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>
+	<para>Do not use <literal>${SITE_PERL}</literal> in dependency
-	    ${SITE_PERL}</literal> as a dependency listing.  This is
+	  declarations.  Doing so assumes that
-	  problematic because it means that
+	  <filename>bsd.perl.mk</filename> has been included, which is
-	  <filename>bsd.perl.mk</filename> must be included
+	  not always true.  Ports depending on this port will have
-	  to satisfy the dependency.  Additionally, if the module's
+	  incorrect dependencies if this port's files move later in an
-	  files change, it would require changing all
+	  upgrade.  The right way to declare Perl module dependencies
-	  dependent ports.</para>
+	  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&gt;=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting>
       </example>