From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2178) id 0F2F838930C9; Wed, 6 May 2020 15:36:06 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0F2F838930C9 Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: Florian Weimer To: glibc-cvs@sourceware.org Subject: [glibc] Document the internal _ and N_ macros X-Act-Checkin: glibc X-Git-Author: Florian Weimer X-Git-Refname: refs/heads/master X-Git-Oldrev: 898f3793164c0e811b28a37827f4bedce334066f X-Git-Newrev: d69c3a9e75a5cc592f658e1a2f7e8c7f1e023d11 Message-Id: <20200506153606.0F2F838930C9@sourceware.org> Date: Wed, 6 May 2020 15:36:06 +0000 (GMT) X-BeenThere: glibc-cvs@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Glibc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 06 May 2020 15:36:06 -0000 https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=d69c3a9e75a5cc592f658e1a2f7e8c7f1e023d11 commit d69c3a9e75a5cc592f658e1a2f7e8c7f1e023d11 Author: Florian Weimer Date: Wed May 6 17:35:21 2020 +0200 Document the internal _ and N_ macros Reviewed-by: Carlos O'Donell Diff: --- include/libintl.h | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/include/libintl.h b/include/libintl.h index 9a11367ec6..3d63b7abbd 100644 --- a/include/libintl.h +++ b/include/libintl.h @@ -37,17 +37,33 @@ extern char *__bind_textdomain_codeset (const char *__domainname, extern const char _libc_intl_domainname[]; libc_hidden_proto (_libc_intl_domainname) -/* Define the macros `_' and `N_' for conveniently marking translatable - strings in the libc source code. We have to make sure we get the - correct definitions so we undefine the macros first. */ +/* _ marks its argument, a string literal, for translation, and + performs translation at run time if the LC_MESSAGES locale category + has been set. The MSGID argument is extracted, added to the + translation database, and eventually submitted to the translation + team for processing. New translations are periodically + incorporated into the glibc source tree as part of translation + updates. */ +# undef _ +# define _(msgid) __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) + +/* N_ marks its argument, a string literal, for translation, so that + it is extracted and added to the translation database (similar to + the _ macro above). It does not translate the string at run time. + The first, primary use case for N_ is a context in which a string + literal is required, such as an initializer. Translation will + happen later, for example using the __gettext function. + The second, historic, use case involves strings which may be + translated in a future version of the library, but cannot be + translated in current releases due to some technical limitation + (e.g., gettext not being available in the dynamic loader). No + translation at run time happens in such cases. In the future, this + historic usage of N_ may become deprecated. Strings which are not + translated create unnecessary work for the translation team. We + continue to use N_ because it helps mark translatable strings. */ # undef N_ # define N_(msgid) msgid -# undef _ -/* This is defined as an optimizing macro, so use it. */ -# define _(msgid) \ - __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) - # endif /* !_ISOMAC */ #endif