Date: Mon, 21 Aug 2006 11:10:36 +0400 From: Yar Tikhiy <yar@comp.chem.msu.su> To: freebsd-ports@freebsd.org Subject: A section on gettext for the Porter's Handbook Message-ID: <20060821071036.GA44406@comp.chem.msu.su>
next in thread | raw e-mail | index | archive | help
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 </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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060821071036.GA44406>