From owner-freebsd-doc@FreeBSD.ORG Sun Mar 15 15:37:14 2009 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 79576106564A for ; Sun, 15 Mar 2009 15:37:14 +0000 (UTC) (envelope-from r.c.ladan@gmail.com) Received: from nf-out-0910.google.com (nf-out-0910.google.com [64.233.182.188]) by mx1.freebsd.org (Postfix) with ESMTP id C87F88FC12 for ; Sun, 15 Mar 2009 15:37:13 +0000 (UTC) (envelope-from r.c.ladan@gmail.com) Received: by nf-out-0910.google.com with SMTP id d21so918841nfb.33 for ; Sun, 15 Mar 2009 08:37:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:sender:message-id:date:from :organization:user-agent:mime-version:to:cc:subject:references :in-reply-to:x-enigmail-version:content-type; bh=g+cJYwhacELgDyPpGSGXSoHhrygMKGhmQvwOK3vEuLM=; b=hHTSCA1QXM1JWZ0a3oR/px2SALJpLICTp/gLIgn7/KwstN8oKnObzaaCZd8kFcG4Ym 01uuL13fIT9Y8+bPR2xZ4VJ/xo9nM+pSRg4ezP1XN012DYbHu2q3cyaYP+huxjzJ9tJk pBPl8dyyFsek+4VpamuwtlCbtoWv4JEWbG6wQ= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=sender:message-id:date:from:organization:user-agent:mime-version:to :cc:subject:references:in-reply-to:x-enigmail-version:content-type; b=cUvRiylPzrQQkpne/5PdYBnIF2pwl/ZmBDj1ksikjypJwSqYQcj5LcuON1zjCdkAnF nWC7JAEwtxKa27+wNCQoEgnJVgVO6ScqVAJPHyo9YLdBmEgRWLPJj9jplYnOsqVdtp0I WmkhnuaXmZEnXfjbxlVhnJhDeCqaje4uemEHA= Received: by 10.216.51.82 with SMTP id a60mr1468481wec.108.1237130122354; Sun, 15 Mar 2009 08:15:22 -0700 (PDT) Received: from self.rene-ladan.nl ([77.163.174.49]) by mx.google.com with ESMTPS id 1sm7693723nfv.30.2009.03.15.08.15.21 (version=TLSv1/SSLv3 cipher=RC4-MD5); Sun, 15 Mar 2009 08:15:21 -0700 (PDT) Sender: Rene Ladan Message-ID: <49BD1B5C.4010105@freebsd.org> Date: Sun, 15 Mar 2009 16:14:36 +0100 From: Rene Ladan Organization: The FreeBSD Project User-Agent: Thunderbird 2.0.0.19 (X11/20090111) MIME-Version: 1.0 To: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= References: <200903131040.n2DAecSO061131@svn.freebsd.org> <49BB0DF0.3020907@FreeBSD.org> In-Reply-To: <49BB0DF0.3020907@FreeBSD.org> X-Enigmail-Version: 0.95.6 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="------------enigD8121F0FA5AFE945036ED738" Cc: Gabor Pali , doc@FreeBSD.org, Tom Rhodes , Robert Watson , Giorgos Keramidas , svn-src-head@freebsd.org, "Sean C. Farley" Subject: Re: NLS additions to I18N chapter of developers-handbook [Was: Re: svn commit: r189765 - in head: . lib/libc lib/libc/nls] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 15 Mar 2009 15:37:14 -0000 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 @@ + + + -+ Localized messages with POSIX.1 Native Language Support (N= LS) ++ Localized Messages with POSIX.1 Native Language Support (N= LS) + + 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. + + -+ Organizing localized messages into catalog files ++ Organizing Localized Messages into Catalog Files + + 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 hu_HU.ISO8859-2. + -+ 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 ++ These catalog files are common text files that contain the ++ numbered messages. It is possible to write comments by starting ++ the line with a $ sign. Set boundaries are also = separated by + special comments, where the keyword set must -+ directly follow the $ sign. The set keyword ++ directly follow the $ sign. The set keyword + is then followed by the set number. For example: + + $set 1 + + 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: ++ followed by the localized message. The well-known ++ modifiers from &man.printf.3; are accepted: + + 15 "File not found: %s\n" + + 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;. + + + -+ Using the catalog files from the source code ++ Using the Catalog Files from the Source Code + -+ The usage of the catalog files is very simple. To use ++ Using the catalog files is simple. To use + the related functions, nl_types.h 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 grep. + This name will be used when looking for the compiled @@ -91,7 +91,7 @@ + + + NL_CAT_LOCALE, which means that -+ the used catalog file will be based on the ++ the used catalog file will be based on + LC_MESSAGES. + + @@ -100,29 +100,29 @@ + the proper catalog. + + -+ The &man.catopen.3; call return with a catalog identifier of -+ type nl_catd. For possible returned error -+ codes, please refer to the manual page. ++ The &man.catopen.3; call returns a catalog identifier of ++ type nl_catd. Please refer to the manual page fo= r a list of possible returned error ++ codes. + + 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. + + After using the catalog file, it must be closed by calling -+ &man.catclose.3;, which has one argument, the catalog id. ++ &man.catclose.3; which has one argument, the catalog id. + + + -+ A practical example ++ A Practical Example + -+ The following example will demonstrate an easy solution to ++ The following example will demonstrate an easy solution on how t= o + use NLS catalogs in a flexible way. + -+ We need to put these lines to a common header file of -+ the program, which is included into all source files, where ++ 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: + + @@ -137,7 +137,7 @@ + +extern char *nlsstr[]; + -+ Then put these lines to the global declaration part of the ++ Next, put these lines into the global declaration part of the + main source file: + + @@ -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" +}; + -+ And here comes the real code snippets, which open, read and ++ Next come the real code snippets, which open, read, and + close the catalog: + + @@ -176,25 +176,25 @@ + + + -+ Making use of bsd.nls.mk ++ Making use of <filename>bsd.nls.mk</filename> + -+ Using the catalog files requires few repeatable steps, ++ 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, bsd.nls.mk introduces some macros. -+ It is not needed to include bsd.nls.mk ++ It is not necessary to include bsd.nls.mk + explicitly, it is pulled in from the common Makefiles, + such as bsd.prog.mk or + bsd.lib.mk. + + Usually it is enough to define NLSNAME, -+ 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 + NLS without their .msg + extension. + + For further information about bsd.nls.mk, -+ 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. + + --------------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--