Add a section on using GNU gettext in ports.

Reviewed by:	pav (on freebsd-ports)

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

@@ -3720,7 +3720,7 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
 		    set to values such as 323, 40, 41, or 50.</entry>
 	        </row>
 
-	        <row>
+	        <row id="knobs-without-nls">
 		  <entry><makevar>WITHOUT_NLS</makevar></entry>
 
 		  <entry>If set, says that internationalization is not
@@ -4608,6 +4608,103 @@ PORTVERSION=   1.0</programlisting>
 	</sect2>
     </sect1>
 
+    <sect1 id="using-gettext">
+      <title>Using GNU <literal>gettext</literal></title>
+
+      <sect2>
+	<title>Basic usage</title>
+
+	<para>If your port requires <literal>gettext</literal>,
+	  just set <makevar>USE_GETTEXT</makevar> to <literal>yes</literal>,
+	  and your port will grow the dependency on <filename
+	  role="package">devel/gettext</filename>.  The value of
+	  <makevar>USE_GETTEXT</makevar> can also specify the required
+	  version of the <literal>libintl</literal> library, the basic
+	  part of <literal>gettext</literal>, but using this
+	  feature is <emphasis>strongly discouraged</emphasis>:
+	  Your port should work with just the current version of
+	  <filename role="package">devel/gettext</filename>.</para>
+
+	<para>A rather common case is a port using
+	  <literal>gettext</literal> and <command>configure</command>.
+	  Generally, GNU <command>configure</command> should be
+	  able to locate <literal>gettext</literal> automatically.
+	  If it ever fails to, hints at the location of
+	  <literal>gettext</literal> can be passed in
+	  <envar>CPPFLAGS</envar> and <envar>LDFLAGS</envar> as
+	  follows:</para>
+
+	<programlisting>USE_GETTEXT=    yes
+GNU_CONFIGURE=  yes
+CONFIGURE_ENV=  CPPFLAGS="-I${LOCALBASE}/include" \
+                LDFLAGS="-L${LOCALBASE}/lib"</programlisting>
+      </sect2>
+
+      <sect2>
+	<title>Optional usage</title>
+
+	<para>Some software products allow for disabling NLS,
+	  e.g., through passing <option>--disable-nls</option> to
+	  <command>configure</command>.  In that case, your port
+	  should use <literal>gettext</literal> conditionally,
+	  depending on the status of <link
+	  linkend="knobs-without-nls"><makevar>WITHOUT_NLS</makevar></link>.
+	  For ports of low to medium complexity, you can rely on the
+	  following idiom:</para>
+
+	<programlisting>GNU_CONFIGURE=          yes
+
+.if defined(WITHOUT_NLS)
+CONFIGURE_ARGS+=        --disable-nls
+PLIST_SUB+=             NLS="@comment "
+.else
+USE_GETTEXT=            yes
+PLIST_SUB+=             NLS=""
+.endif</programlisting>
+
+	<para>The next item on your to-do list is to arrange so that
+	  the message catalog files are included in the packing list
+	  conditionally.  The <filename>Makefile</filename> part of
+	  this task is already provided by the idiom.  It is explained
+	  in the section on <link linkend="plist-sub">advanced
+	  <filename>pkg-plist</filename> practices</link>.  In a
+	  nutshell, each occurrence of <literal>%%NLS%%</literal> in
+	  <filename>pkg-plist</filename> will be replaced by
+	  <quote><literal>@comment&nbsp;</literal></quote> if NLS is
+	  disabled, or by a null string if NLS is enabled.  Consequently,
+	  the lines prefixed by <literal>%%NLS%%</literal> will become
+	  mere comments in the final packing list if NLS is off;
+	  otherwise the prefix will be just left out.  All you need
+	  to do now is insert <literal>%%NLS%%</literal> before each
+	  path to a message catalog file in <filename>pkg-plist</filename>.
+	  For example:</para>
+
+	<programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
+%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>
+
+	<para>In high complexity cases, you may need to use more advanced
+	  techniques than the recipe given here, such as <link
+	  linkend="plist-dynamic">dynamic packing list generation</link>.</para>
+      </sect2>
+
+      <sect2>
+	<title>Handling message catalog directories</title>
+
+	<para>There is a point to note about installing message catalog
+	  files.  The target directories for them, which reside under
+	  <filename><makevar>LOCALBASE</makevar>/share/locale</filename>,
+	  should rarely be created and removed by your port.  The
+	  most popular languages have their respective directories
+	  listed in <filename>/etc/mtree/BSD.local.dist</filename>;
+	  that is, they are a part of the base system.  The directories
+	  for many other languages are governed by the <filename
+	  role="package">devel/gettext</filename> port.  You may want
+	  to consult its <filename>pkg-plist</filename> and see whether
+	  your port is going to install a message catalog file for a
+	  unique language.</para>
+      </sect2>
+    </sect1>
+
     <sect1 id="using-perl">
       <title>Using <literal>perl</literal></title>