Improve the Perl related sections.

Reported by:	brd
Sponsored by:	Absolight

1 files changed, 61 insertions, 5 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
index 8b77817d89..819d2f85b1 100644
--- a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ b/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">