Improve the Perl related sections.

Reported by:	brd
Sponsored by:	Absolight

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

@@ -1196,22 +1196,78 @@ PLIST_SUB+=		NLS="@comment "
     </example>
 
     <para>For Perl ports that install manual pages, the macro
-      <varname>PERL5_MAN3</varname> can be used
+      <literal>PERL5_MAN3</literal> and <literal>PERL5_MAN1</literal>
+      can be used
       inside <filename>pkg-plist</filename>.  For example,</para>
 
-    <programlisting>lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting>
+    <programlisting>lib/perl5/5.14/man/man1/event.1.gz
+lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting>
 
     <para>can be replaced with</para>
 
-    <programlisting>%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting>
+    <programlisting>%%PERL5_MAN1%%/event.1.gz
+%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting>
 
     <note>
-      <para>There are no <varname>PERL5_MANx</varname> macros for the
+      <para>There are no
+	<varname>PERL5_MAN<replaceable>x</replaceable></varname>
+	macros for the
 	other sections (<replaceable>x</replaceable> in
-	<literal>1</literal>, <literal>2</literal> and
+	<literal>2</literal> and
 	<literal>4</literal> to <literal>9</literal>) because those
 	get installed in the regular directories.</para>
     </note>
+
+    <example xml:id="use-perl-ex-build">
+      <title>A Port Which Only Requires Perl to Build</title>
+
+      <para>As the default USE_PERL5 value is build and run, set it
+	to:</para>
+
+      <programlisting>USES=		perl5
+USE_PERL5=	build</programlisting>
+    </example>
+
+    <example xml:id="use-perl-ex-patch">
+      <title>A Port Which Also Requires Perl to Patch</title>
+
+      <para>From time to time, using &man.sed.1; for patching is not
+	enough.  When using &man.perl.1; is easier, use:</para>
+
+      <programlisting>USES=		perl5
+USE_PERL5=	patch build run</programlisting>
+    </example>
+
+    <example xml:id="use-perl-ex-configure">
+      <title>A Perl Module Which Needs
+	<literal>ExtUtils::MakeMaker</literal> to Build</title>
+
+      <para>Most <application>Perl</application> modules come with a
+	<filename>Makefile.PL</filename> configure script.  In this
+	case, set:</para>
+
+      <programlisting>USES=		perl5
+USE_PERL5=	configure</programlisting>
+    </example>
+
+    <example xml:id="use-perl-ex-modbuild">
+      <title>A Perl Module Which Needs
+	<literal>Module::Build</literal> to Build</title>
+
+      <para>When a <application>Perl</application> module comes with a
+	<filename>Build.PL</filename> configure script, it can require
+	<application>Module::Build</application>, in which case,
+	set</para>
+
+      <programlisting>USES=		perl5
+USE_PERL5=	modbuild</programlisting>
+
+      <para>If it instead requires
+	<application>Module::Build::Tiny</application>, set</para>
+
+      <programlisting>USES=		perl5
+USE_PERL5=	modbuildtiny</programlisting>
+    </example>
   </sect1>
 
   <sect1 xml:id="using-x11">

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

@@ -2028,48 +2028,31 @@ USE_MATE=	menus:build intlhack</programlisting>
 
     <para>Possible arguments: (none)</para>
 
-    <para>Depends on <application>Perl</application>.  These variables
-      can be set:</para>
+    <para>Depends on <application>Perl</application>.  The
+      configuration is done using <varname>USE_PERL5</varname>.</para>
 
-    <itemizedlist>
-      <listitem>
-	<para><varname>PERL_VERSION</varname>: Full version of
-	  <application>Perl</application> to use, or the default if
-	  not set</para>
-      </listitem>
+    <para><varname>USE_PERL5</varname> can contain the phases in which
+      to use <application>Perl</application>, can be
+      <literal>extract</literal>, <literal>patch</literal>,
+      <literal>build</literal>, <literal>run</literal>, or
+      <literal>test</literal>.</para>
 
-      <listitem>
-	<para><varname>PERL_ARCH</varname>: Directory name of
-	  architecture dependent libraries, defaults to
-	  <filename>mach</filename></para>
-      </listitem>
+    <para><varname>USE_PERL5</varname> can also contain
+      <literal>configure</literal>,
+      <literal>modbuild</literal>, or <literal>modbuildtiny</literal>
+      when <filename>Makefile.PL</filename>,
+      <filename>Build.PL</filename>, or
+      <application>Module::Build::Tiny</application>'s flavor of
+      <filename>Build.PL</filename> is required.</para>
 
-      <listitem>
-	<para><varname>PERL_PORT</varname>: Name of the
-	  <application>Perl</application> port to be installed, the
-	  default is derived from
-	  <varname>PERL_VERSION</varname></para>
-      </listitem>
+    <para><varname>USE_PERL5</varname> defaults to <literal>build
+	run</literal>.  When using <literal>configure</literal>,
+      <literal>modbuild</literal>, or <literal>modbuildtiny</literal>,
+      <literal>build</literal> and <literal>run</literal> are
+      implied.</para>
 
-      <listitem>
-	<para><varname>SITE_PERL</varname>: Directory name for site
-	  specific <application>Perl</application> packages</para>
-      </listitem>
-
-      <listitem>
-	<para><varname>USE_PERL5</varname>: Phases in which to use
-	  <application>Perl</application>, can be
-	  <literal>extract</literal>, <literal>patch</literal>,
-	  <literal>build</literal>, <literal>run</literal>, or
-	  <literal>test</literal>.  It can also be
-	  <literal>configure</literal>, <literal>modbuild</literal>,
-	  or <literal>modbuildtiny</literal> when
-	  <filename>Makefile.PL</filename>,
-	  <filename>Build.PL</filename>, or the Module::Build::Tiny
-	  flavor of <filename>Build.PL</filename> is required.  It
-	  defaults to <literal>build run</literal>.</para>
-      </listitem>
-    </itemizedlist>
+    <para>See <xref linkend="using-perl"/> for more
+	information.</para>
   </sect1>
 
   <sect1 xml:id="uses-pgsql">