Update the Using Perl section.

Glanced by:	bjk
Sponsored by:	Absolight

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

@@ -905,6 +905,10 @@ PLIST_SUB+=		NLS="@comment "
     <title>Using <application>Perl</application></title>
 
     <para>If <varname>MASTER_SITES</varname> is set to
+      <literal>CPAN</literal>, the correct subdirectory should be
+      selected automatically.  If the default subdirectory is wrong,
+      <literal>CPAN/Module</literal> can be used to change it.
+      <varname>MASTER_SITES</varname> can also be set to the old
       <varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred
       value of <varname>MASTER_SITE_SUBDIR</varname> is the
       top-level hierarchy name.  For example, the recommended value
@@ -918,74 +922,21 @@ PLIST_SUB+=		NLS="@comment "
     <para>The exception to this rule is when the relevant directory
       does not exist or the distfile does not exist in that
       directory.  In such case, using author's id as
-      <varname>MASTER_SITE_SUBDIR</varname> is allowed.</para>
+      <varname>MASTER_SITE_SUBDIR</varname> is allowed.
+      The <literal>CPAN:AUTHOR</literal> macro can be used, which will
+      be translated to the hashed author directory.  (e.g.,
+      <literal>CPAN:AUTHOR</literal> will be converted to
+      <literal>authors/id/A/AU/AUTHOR</literal>.)</para>
 
-    <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
-      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>
+    <para>When a port needs <application>Perl</application> support,
+      it should use <literal>USES=perl5</literal> with the optional
+      <varname>USE_PERL5</varname> like described in <link
+	linkend="uses-perl5">the perl5 USES description</link>.</para>
 
     <table frame="none">
-      <title>Variables for Ports That Use
+      <title>Read-Only Variables for Ports That Use
 	<application>Perl</application></title>
 
-      <tgroup cols="2">
-	<thead>
-	  <row>
-	    <entry>Variable</entry>
-	    <entry>Meaning</entry>
-	  </row>
-	</thead>
-
-	<tbody>
-	  <row>
-	    <entry><varname>USE_PERL5</varname></entry>
-	    <entry>The port uses Perl 5
-	      to build and run.</entry>
-	  </row>
-
-	  <row>
-	    <entry><varname>USE_PERL5_BUILD</varname></entry>
-	    <entry>The port uses Perl 5
-	      to build.</entry>
-	  </row>
-
-	  <row>
-	    <entry><varname>USE_PERL5_RUN</varname></entry>
-	    <entry>The port uses Perl 5
-	      to run.</entry>
-	  </row>
-
-	  <row>
-	    <entry><varname>PERL</varname></entry>
-	    <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
-	      scripts.</entry>
-	  </row>
-
-	  <row>
-	    <entry><varname>PERL_CONFIGURE</varname></entry>
-	    <entry>Configure using Perl's MakeMaker.  It implies
-	      <varname>USE_PERL5</varname>.</entry>
-	  </row>
-
-	  <row>
-	    <entry><varname>PERL_MODBUILD</varname></entry>
-	    <entry>Configure, build and install using Module::Build.
-	      It implies <varname>PERL_CONFIGURE</varname>.</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-
       <tgroup cols="2">
 	<thead>
 	  <row>
@@ -995,6 +946,15 @@ PLIST_SUB+=		NLS="@comment "
 	</thead>
 
 	<tbody>
+	  <row>
+	    <entry><varname>PERL</varname></entry>
+	    <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
+	      scripts.</entry>
+	  </row>
+
 	  <row>
 	    <entry><varname>PERL_VERSION</varname></entry>
 	    <entry>The full version of Perl
@@ -1043,7 +1003,7 @@ PLIST_SUB+=		NLS="@comment "
     <note>
       <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
+	<filename>perl5.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
@@ -1057,9 +1017,7 @@ PLIST_SUB+=		NLS="@comment "
     </example>
 
     <para>For Perl ports that install manual pages, the macro
-      <varname>PERL5_MAN<replaceable>x</replaceable></varname>
-      (where <replaceable>x</replaceable> ranges from
-      <literal>1</literal> to <literal>9</literal>) can be used
+      <varname>PERL5_MAN3</varname> can be used
       inside <filename>pkg-plist</filename>.  For example,</para>
 
     <programlisting>lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting>
@@ -1067,6 +1025,14 @@ PLIST_SUB+=		NLS="@comment "
     <para>can be replaced with</para>
 
     <programlisting>%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting>
+
+    <note>
+      <para>There are no <varname>PERL5_MANx</varname> macros for the
+	other sections (<replaceable>x</replaceable> in
+	<literal>1</literal>, <literal>2</literal> and
+	<literal>4</literal> to <literal>9</literal>) because those
+	get installed in the regular directories.</para>
+    </note>
   </sect1>
 
   <sect1 xml:id="using-x11">