From patchwork Wed May 6 09:23:37 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 38922 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 5CB653938C00; Wed, 6 May 2020 09:23:42 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from albireo.enyo.de (albireo.enyo.de [37.24.231.21]) by sourceware.org (Postfix) with ESMTPS id 17DB1389367C for ; Wed, 6 May 2020 09:23:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 17DB1389367C Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=deneb.enyo.de Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=fw@deneb.enyo.de Received: from [172.17.203.2] (helo=deneb.enyo.de) by albireo.enyo.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) id 1jWGHC-00079M-2f for libc-alpha@sourceware.org; Wed, 06 May 2020 09:23:38 +0000 Received: from fw by deneb.enyo.de with local (Exim 4.92) (envelope-from ) id 1jWGHC-0003DT-0A for libc-alpha@sourceware.org; Wed, 06 May 2020 11:23:38 +0200 From: Florian Weimer To: libc-alpha@sourceware.org Subject: [PATCH] Document the internal _ and N_ macros Date: Wed, 06 May 2020 11:23:37 +0200 Message-ID: <87r1vxfmcm.fsf@mid.deneb.enyo.de> MIME-Version: 1.0 X-Spam-Status: No, score=-13.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, KAM_DMARC_STATUS, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" ----- Tested by building glibc on x86_64-linux-gnu. include/libintl.h | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/include/libintl.h b/include/libintl.h index 9a11367ec6..4b0a0e8674 100644 --- a/include/libintl.h +++ b/include/libintl.h @@ -37,17 +37,34 @@ 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. This usage is + deprecated because using N_ for strings which are not translated + after all creates unnecessary work for the translation team: glibc + does not currently use those translations, and that may never + change. */ # 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