Date: Sun, 15 Mar 2009 16:14:36 +0100 From: Rene Ladan <rene@freebsd.org> To: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= <gabor@FreeBSD.org> Cc: Gabor Pali <pgj@FreeBSD.org>, doc@FreeBSD.org, Tom Rhodes <trhodes@FreeBSD.org>, Robert Watson <rwatson@FreeBSD.org>, Giorgos Keramidas <keramida@freebsd.org>, svn-src-head@freebsd.org, "Sean C. Farley" <scf@FreeBSD.org> Subject: Re: NLS additions to I18N chapter of developers-handbook [Was: Re: svn commit: r189765 - in head: . lib/libc lib/libc/nls] Message-ID: <49BD1B5C.4010105@freebsd.org> In-Reply-To: <49BB0DF0.3020907@FreeBSD.org> References: <200903131040.n2DAecSO061131@svn.freebsd.org> <alpine.BSF.2.00.0903131312380.61873@fledge.watson.org> <49BB0DF0.3020907@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enigD8121F0FA5AFE945036ED738 Content-Type: multipart/mixed; boundary="------------080101080707070509060703" This is a multi-part message in MIME format. --------------080101080707070509060703 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: quoted-printable G=E1bor K=F6vesd=E1n schreef: > Robert Watson escribi=F3: >> >> On Fri, 13 Mar 2009, Gabor Kovesdan wrote: >> >>> - Reenable Native Language Support in libc. This feature was=20 >>> disabled due >>> to possible breakages in the catalog handling code. Since then, t= hat >>> code has been replaced by the secure code from NetBSD but NLS in l= ibc >>> remained turned off. Tests have shown that the feature is stable = and >>> working so we can now turn it on again. >> >> Do we have a nice tutorialish document somewhere on what people=20 >> writing new command line tools or libraries should do in order to=20 >> address localization requirements, or at least, make it easier for=20 >> other people to do so? I'm afraid I, at least, live in a world=20 >> without catalogues, but a quick and practical guide to what The Right = >> Thing Is for FreeBSD would make it much easier for me to do something = >> a bit more mature. >> > I've spent some time on writing a short section on this trying to do=20 > this from a practical viewpoint. Please take a look ant tell me what do= =20 > you think: > http://kovesdan.org/files/developers-handbook/posix-nls.html >=20 > A patch can be found here: > http://kovesdan.org/patches/nls-doc.diff >=20 > (doc@ and some probable reviewers added to CC) >=20 I've reviewed the patch, a diff to it is attached. Rene --=20 http://www.rene-ladan.nl/ GPG fingerprint =3D ADBC ECCD EB5F A6B4 549F 600D 8C9E 647A E564 2BFC (s= ubkeys.pgp.net) --------------080101080707070509060703 Content-Type: text/plain; name="rene-nls-doc.diff" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline; filename="rene-nls-doc.diff" --- nls-doc.diff.orig 2009-03-15 12:53:06.000000000 +0100 +++ nls-doc.diff 2009-03-15 16:06:38.000000000 +0100 @@ -22,17 +22,17 @@ + </authorgroup> + </sect1info> + -+ <title>Localized messages with POSIX.1 Native Language Support (N= LS)</title> ++ <title>Localized Messages with POSIX.1 Native Language Support (N= LS)</title> + + <para>Beyond the basic I18N functions, like supporting various in= put + encodings or supporting national conventions, such as the different -+ decimal separators, at a higher level of I18N, we can localize the -+ messages written to the output by our program. A common way of doing -+ this is using the POSIX.1 NLS functions, which are provided as a part ++ decimal separators, at a higher level of I18N, it is possible to local= ize the ++ messages written to the output by the various programs. A common way = of doing ++ this is using the POSIX.1 NLS functions which are provided as a part + of the &os; base system.</para> + + <sect2 id=3D"nls-catalogs"> -+ <title>Organizing localized messages into catalog files</title> ++ <title>Organizing Localized Messages into Catalog Files</title> + + <para>POSIX.1 NLS is based on catalog files, which contain the + localized messages in the desired encoding. The messages are @@ -43,38 +43,38 @@ + Hungarian messages for ISO8859-2 encoding should be stored in a file= + called <filename>hu_HU.ISO8859-2</filename>.</para> + -+ <para>These catalog files are usual text files that contain the -+ numbered mesages. It is possible to write comments by starting -+ the line with a $ sign. Set boundaries are also separated by ++ <para>These catalog files are common text files that contain the ++ numbered messages. It is possible to write comments by starting ++ the line with a <literal>$</literal> sign. Set boundaries are also = separated by + special comments, where the keyword <literal>set</literal> must -+ directly follow the $ sign. The <literal>set</literal> keyword ++ directly follow the <literal>$</literal> sign. The <literal>set</li= teral> keyword + is then followed by the set number. For example:</para> + + <programlisting>$set 1</programlisting> + + <para>The actual message entries start with the message number and -+ are then followed by the localized message. The well-known -+ &man.printf.3; modifiers are accepted:</para> ++ followed by the localized message. The well-known ++ modifiers from &man.printf.3; are accepted:</para> + + <programlisting>15 "File not found: %s\n"</programlisting> + + <para>The language catalog files have to be compiled into a binary + form before they can be opened from the program. This conversion + is done with the &man.gencat.1; utility. Its first argument is the -+ filename of the compiled catalog and the further arguments are the -+ input catalogs. You can also organize the localized messages into -+ more catalog files and then process all of them with ++ filename of the compiled catalog and its further arguments are the ++ input catalogs. The localized messages can also be organized into ++ more catalog files and then all of them can be processed with + &man.gencat.1;.</para> + </sect2> + + <sect2 id=3D"nls-using"> -+ <title>Using the catalog files from the source code</title> ++ <title>Using the Catalog Files from the Source Code</title> + -+ <para>The usage of the catalog files is very simple. To use ++ <para>Using the catalog files is simple. To use + the related functions, <filename + class=3D"headerfile">nl_types.h</filename> must be included. Befo= re -+ using a catalog, you have to open it with &man.catopen.3;. -+ It has two arguments, the first one is the name of the ++ using a catalog, it has to be opened with &man.catopen.3;. ++ The function takes two arguments. The first parameter is the name o= f the + installed and compiled catalog. Usually, the name of the + program is used, such as <application>grep</application>. + This name will be used when looking for the compiled @@ -91,7 +91,7 @@ + <itemizedlist> + <listitem> + <para><literal>NL_CAT_LOCALE</literal>, which means that -+ the used catalog file will be based on the ++ the used catalog file will be based on + <envar>LC_MESSAGES</envar>.</para> + </listitem> + <listitem> @@ -100,29 +100,29 @@ + the proper catalog.</para> + </itemizedlist> + -+ <para>The &man.catopen.3; call return with a catalog identifier of -+ type <literal>nl_catd</literal>. For possible returned error -+ codes, please refer to the manual page.</para> ++ <para>The &man.catopen.3; call returns a catalog identifier of ++ type <literal>nl_catd</literal>. Please refer to the manual page fo= r a list of possible returned error ++ codes.</para> + + <para>After opening a catalog &man.catgets.3; can be used to retrieve + a message. The first parameter is the catalog identifier returned + by &man.catopen.3;, the second one is the number of the set, the -+ third one is the number of the message and the fourth one is a -+ fallback message, which will be returned if the requested message ++ third one is the number of the messages, and the fourth one is a ++ fallback message which will be returned if the requested message + cannot be retrieved from the catalog file.</para> + + <para>After using the catalog file, it must be closed by calling -+ &man.catclose.3;, which has one argument, the catalog id.</para> ++ &man.catclose.3; which has one argument, the catalog id.</para> + </sect2> + + <sect2 id=3D"nls-example"> -+ <title>A practical example</title> ++ <title>A Practical Example</title> + -+ <para>The following example will demonstrate an easy solution to ++ <para>The following example will demonstrate an easy solution on how t= o + use NLS catalogs in a flexible way.</para> + -+ <para>We need to put these lines to a common header file of -+ the program, which is included into all source files, where ++ <para>The below lines need to be put into a common header file of ++ the program which is included into all source files where + localized messages are necessary:</para> + + <programlisting> @@ -137,7 +137,7 @@ + +extern char *nlsstr[];</programlisting> + -+ <para>Then put these lines to the global declaration part of the ++ <para>Next, put these lines into the global declaration part of the + main source file:</para> + + <programlisting> @@ -147,16 +147,16 @@ +#endif + +/* -+ * Default messags to use when NLS is disabled or no catalogue ++ * Default messages to use when NLS is disabled or no catalog + * is found. + */ +char *nlsstr[] =3D { + "", +/* 1*/ "some random message", -+/* 2*/ "some another message" ++/* 2*/ "some other message" +};</programlisting> + -+ <para>And here comes the real code snippets, which open, read and ++ <para>Next come the real code snippets, which open, read, and + close the catalog:</para> + + <programlisting> @@ -176,25 +176,25 @@ + </sect2> + + <sect2 id=3D"nls-mk"> -+ <title>Making use of bsd.nls.mk</title> ++ <title>Making use of <filename>bsd.nls.mk</filename></title> + -+ <para>Using the catalog files requires few repeatable steps, ++ <para>Using the catalog files requires a few repeatable steps, + such as compiling the catalogs and installing them to the + proper location. In order to simplify this process even + more, <filename>bsd.nls.mk</filename> introduces some macros. -+ It is not needed to include <filename>bsd.nls.mk</filename> ++ It is not necessary to include <filename>bsd.nls.mk</filename> + explicitly, it is pulled in from the common Makefiles, + such as <filename>bsd.prog.mk</filename> or + <filename>bsd.lib.mk</filename>.</para> + + <para>Usually it is enough to define <makevar>NLSNAME</makevar>, -+ which should be the catalog name mentioned as the first ++ which should have the catalog name mentioned as the first + argument of &man.catopen.3; and list the catalog files in + <makevar>NLS</makevar> without their <literal>.msg</literal> + extension.</para> + + <para>For further information about <filename>bsd.nls.mk</filename>, -+ please refer to this file itself, it is short and easy to ++ please refer to the file itself, it is short and easy to + understand.</para> + </sect2> + </sect1> --------------080101080707070509060703-- --------------enigD8121F0FA5AFE945036ED738 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.11 (FreeBSD) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkm9G4gACgkQjJ5keuVkK/xy0wCgi6hdTbX/vAQjbIBYHGVBDsIY 5acAn1gZjZkzZmvUVffX8AqyT/9jPbYG =HgU1 -----END PGP SIGNATURE----- --------------enigD8121F0FA5AFE945036ED738--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?49BD1B5C.4010105>