Document the internal _ and N_ macros

  -----
Tested by building glibc on x86_64-linux-gnu.


 include/libintl.h | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)
  

On 5/6/20 5:23 AM, Florian Weimer wrote:
> -----
> Tested by building glibc on x86_64-linux-gnu.
> 

Your comment indicates that N_ is deprecated, but doesn't list what we
have switched to. This doesn't follow your recommendation to Andreas,
which is to use some new macro?

I think this patch should include such a new macro, and switch all of
the N_ entries which we won't translate to that new macro, and mention
the use of the new macro in the comment below (leaving N_ for the
actual intended use).
 
>  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
>
  

* Carlos O'Donell:

> On 5/6/20 5:23 AM, Florian Weimer wrote:
>> -----
>> Tested by building glibc on x86_64-linux-gnu.
>> 
>
> Your comment indicates that N_ is deprecated, but doesn't list what we
> have switched to. This doesn't follow your recommendation to Andreas,
> which is to use some new macro?

We don't have consensus on what to do instead.  I think there is
consensus that it's deprecated, though.

> I think this patch should include such a new macro, and switch all of
> the N_ entries which we won't translate to that new macro, and mention
> the use of the new macro in the comment below (leaving N_ for the
> actual intended use).

I think we should document what we have today, so that someone who
encounters these macros is less confused by them.
  

On 5/6/20 5:23 AM, Florian Weimer wrote:
> -----
> Tested by building glibc on x86_64-linux-gnu.
> 

Please post v2 for review.
 
>  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.  */

OK.

> +# 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.  

OK up to here.

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.  */

Suggest:

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
>
  

* Carlos O'Donell:

> On 5/6/20 5:23 AM, Florian Weimer wrote:
>> -----
>> Tested by building glibc on x86_64-linux-gnu.
>> 
>
> Please post v2 for review.

>> +   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.  */
>
> Suggest:
>
> 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.

Thanks, v2 posted:

   <https://sourceware.org/pipermail/libc-alpha/2020-May/113667.html>