[Bug manual/31057] New: 'How to use "gettext" in GUI programs' could mention pgettext()

[Bug manual/31057] New: 'How to use "gettext" in GUI programs' could mention pgettext()

[sebaaa1754 at gmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=31057

            Bug ID: 31057
           Summary: 'How to use "gettext" in GUI programs' could mention
                    pgettext()
           Product: glibc
           Version: 2.38
            Status: UNCONFIRMED
          Severity: normal
          Priority: P2
         Component: manual
          Assignee: unassigned at sourceware dot org
          Reporter: sebaaa1754 at gmail dot com
                CC: mtk.manpages at gmail dot com
  Target Milestone: ---

The node 'How to use "gettext" in GUI programs' details at length how to solve
the problem of translating repeated short strings in GUI application. The
solution provided is a custom function called `sgettext`.

However, gettext includes a function that is virtually identical: pgettext. As
can be seen in
https://www.gnu.org/software/gettext/manual/html_node/Contexts.html.

I think it would be nice to replace this section with pgettext in mind, or at
least mentions pgettext, which is not mentioned anywhere in the glibc manual
currently.

Here I quote the relevant section of the node from manual/locale.texi:

> One solution to this problem is to artificially extend the strings
> to make them unambiguous.  But what would the program do if no
> translation is available?  The extended string is not what should be
> printed.  So we should use a slightly modified version of the functions.
> 
> To extend the strings a uniform method should be used.  E.g., in the
> example above, the strings could be chosen as
> 
> @smallexample
> Menu|File
> Menu|Printer
> Menu|File|Open
> Menu|File|New
> Menu|Printer|Select
> Menu|Printer|Open
> Menu|Printer|Connect
> @end smallexample
> 
> Now all the strings are different and if now instead of @code{gettext}
> the following little wrapper function is used, everything works just
> fine:
> 
> @cindex sgettext
> @smallexample
>   char *
>   sgettext (const char *msgid)
>   @{
>     char *msgval = gettext (msgid);
>     if (msgval == msgid)
>       msgval = strrchr (msgid, '|') + 1;
>     return msgval;
>   @}
> @end smallexample
> 
> What this little function does is to recognize the case when no
> translation is available.  This can be done very efficiently by a
> pointer comparison since the return value is the input value.  If there
> is no translation we know that the input string is in the format we used
> for the Menu entries and therefore contains a @code{|} character.  We
> simply search for the last occurrence of this character and return a
> pointer to the character following it.  That's it!
> 
> If one now consistently uses the extended string form and replaces
> the @code{gettext} calls with calls to @code{sgettext} (this is normally
> limited to very few places in the GUI implementation) then it is
> possible to produce a program which can be internationalized.
> 
> With advanced compilers (such as GNU C) one can write the
> @code{sgettext} functions as an inline function or as a macro like this:
> 
> @cindex sgettext
> @smallexample
> #define sgettext(msgid) \
>   (@{ const char *__msgid = (msgid);            \
>      char *__msgstr = gettext (__msgid);       \
>      if (__msgval == __msgid)                  \
>        __msgval = strrchr (__msgid, '|') + 1;  \
>      __msgval; @})
> @end smallexample
> 
> The other @code{gettext} functions (@code{dgettext}, @code{dcgettext}
> and the @code{ngettext} equivalents) can and should have corresponding
> functions as well which look almost identical, except for the parameters
> and the call to the underlying function.
> 
> Now there is of course the question why such functions do not exist in
> @theglibc{}?  There are two parts of the answer to this question.
> 
> @itemize @bullet
> @item
> They are easy to write and therefore can be provided by the project they
> are used in.  This is not an answer by itself and must be seen together
> with the second part which is:
> 
> @item
> There is no way the C library can contain a version which can work
> everywhere.  The problem is the selection of the character to separate
> the prefix from the actual string in the extended string.  The
> examples above used @code{|} which is a quite good choice because it
> resembles a notation frequently used in this context and it also is a
> character not often used in message strings.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/31057] 'How to use "gettext" in GUI programs' could mention pgettext()

[schwab@linux-m68k.org]

https://sourceware.org/bugzilla/show_bug.cgi?id=31057

--- Comment #1 from Andreas Schwab <schwab@linux-m68k.org> ---
pgettext is not part of glibc.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

[Bug manual/31057] 'How to use "gettext" in GUI programs' could mention pgettext()

[sebaaa1754 at gmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=31057

--- Comment #2 from Sebastian Carlos <sebaaa1754 at gmail dot com> ---
(In reply to Andreas Schwab from comment #1)
> pgettext is not part of glibc.

Point taken.

Nevertheless, this section of the manual makes several mentions of GNU gettext.
An example would be "The ‘gettext’ approach has some advantages but also some
disadvantages.  Please see the GNU ‘gettext’ manual for a detailed discussion
of the pros and cons."

In light of that, I suggest a small mention of the GNU gettext function, given
the length to which this functionality is described in the glibc manual.

-- 
You are receiving this mail because:
You are on the CC list for the bug.