A section on gettext for the Porter's Handbook

[Yar Tikhiy]

Hi all,

I hoped I had learned something about using gettext in ports,
and felt I should write down a summary.  Here's what came out
of that -- a proposed section for the Porter's Handbook.  Its
HTML rendering is available there:

http://people.freebsd.org/~yar/porters-handbook/using-gettext.html

Remarks and corrections are welcome.  Thanks!

-- 
Yar

Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.745
diff -u -r1.745 book.sgml
--- book.sgml	8 Aug 2006 13:15:32 -0000	1.745
+++ book.sgml	21 Aug 2006 06:50:19 -0000
@@ -3720,7 +3720,7 @@
 		    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,102 @@
 	</sect2>
     </sect1>
 
+    <sect1 id="using-gettext">
+      <title>Using GNU <literal>gettext</literal></title>
+
+      <sect2>
+	<title>Basic usage</title>
+
+	<para>If your port requires GNU <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 GNU <literal>gettext</literal>; but using this
+	  feature is discouraged because your port should work with
+	  the current version of <filename
+	  role="package">devel/gettext</filename>.</para>
+
+	<para>A rather common case is a port using both GNU
+	  <literal>gettext</literal> and GNU <command>configure</command>.
+	  The latter needs a hint at the path to the
+	  <literal>libintl</literal> library, which is usually found in
+	  <filename><makevar>LOCALBASE</makevar>/lib</filename>.  The
+	  hint can be passed to <command>configure</command> in
+	  <envar>LDFLAGS</envar> as follows:</para>
+
+	<programlisting>USE_GETTEXT=    yes
+GNU_CONFIGURE=  yes
+CONFIGURE_ENV=  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 GNU <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
+CONFIGURE_ENV=          LDFLAGS="-L${LOCALBASE}/lib"
+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>