lib/propername.h

   1 /* Localization of proper names.  -*- coding: utf-8 -*-
   2    Copyright (C) 2006, 2008-2025 Free Software Foundation, Inc.
   3    Written by Bruno Haible <bruno@clisp.org>, 2006.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation, either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 /* INTRODUCTION
  19
  20    What do
  21
  22       Torbjörn Granlund    (coreutils)
  23       François Pinard      (coreutils)
  24       Danilo Šegan         (gettext)
  25
  26    have in common?
  27
  28    A non-ASCII name. This causes trouble in the --version output. The simple
  29    "solution" unfortunately mutilates the name.
  30
  31      $ du --version | grep Granlund
  32      Écrit par Torbjorn Granlund, David MacKenzie, Paul Eggert et Jim Meyering.
  33
  34      $ ptx --version | grep Pinard
  35      Écrit par F. Pinard.
  36
  37    What is desirable, is to print the full name if the output character set
  38    allows it, and the ASCIIfied name only as a fallback.
  39
  40      $ recode-sr-latin --version
  41      ...
  42      Written by Danilo Šegan and Bruno Haible.
  43
  44      $ LC_ALL=C recode-sr-latin --version
  45      ...
  46      Written by Danilo Segan and Bruno Haible.
  47
  48    The 'propername' and 'propername-lite' modules do this. Plus, for
  49    languages that do not use the Latin alphabet, they allow a translator
  50    to write the name using that different writing system. In that case the
  51    propername and propername_utf8 output will look like this:
  52       <translated name> (<original name in English>)
  53    whereas the propername_lite output will just be the translated name
  54    if available, otherwise the original name (in UTF-8 if possible and
  55    in ASCII if not).
  56
  57    To use the 'propername' module requires two simple steps:
  58
  59      1) Add it to the list of gnulib modules to import,
  60
  61      2) Change the arguments of version_etc(),
  62
  63           from "Paul Eggert"
  64           to   proper_name ("Paul Eggert")
  65
  66           from "Torbjorn Granlund"
  67           to   proper_name_utf8 ("Torbjorn Granlund", "Torbj\303\266rn Granlund")
  68           or   proper_name_lite ("Torbjorn Granlund", "Torbj\303\266rn Granlund")
  69
  70           from "F. Pinard"
  71           to   proper_name_utf8 ("Franc,ois Pinard", "Fran\303\247ois Pinard")
  72           or   proper_name_lite ("Franc,ois Pinard", "Fran\303\247ois Pinard")
  73
  74         In source code, the second argument of proper_name_lite and
  75         proper_name_utf8 should use octal escapes, not UTF-8 - e.g.,
  76         "Fran\303\247ois Pinard", not "François Pinard".  Doing it
  77         this way can avoid mishandling non-ASCII characters if the
  78         source is recoded to non-UTF-8, or if the compiler does not
  79         treat UTF-8 as-is in character string contents.
  80
  81         (Optionally, here you can also add / * TRANSLATORS: ... * / comments
  82         explaining how the name is written or pronounced.)
  83
  84    Here is an example in context.
  85
  86               char const *author_names[2] = {
  87                 / * TRANSLATORS: This is the proper name "Danilo Šegan".
  88                     In the original Cyrillic it is "Данило Шеган".  * /
  89                 proper_name_utf8 ("Danilo Segan", "Danilo \305\240egan"),
  90                 proper_name ("Bruno Haible")
  91               };
  92
  93    Differences between proper_name_utf8 and proper_name_lite:
  94    * proper_name_lite uses the localization provided by the translator.
  95      If there is no localization, it uses the name with Unicode characters
  96      only in UTF-8 locales, otherwise it uses the original name in English.
  97    * proper_name_utf8 is more elaborate:
  98      - It uses the name with Unicode characters also when the locale encoding
  99        is not UTF-8 but contains the necessary characters (e.g. ISO-8859-x or
 100        GB18030).
 101      - If there is a localization, it produces a better result when the
 102        translator has given a poor localization.
 103  */
 104
 105 #ifndef _PROPERNAME_H
 106 #define _PROPERNAME_H
 107
 108
 109 #ifdef __cplusplus
 110 extern "C" {
 111 #endif
 112
 113 /* Return the localization of NAME.  NAME is written in ASCII.  */
 114 extern const char * proper_name (const char *name) /* NOT attribute const */;
 115
 116 /* Return the localization of a name whose original writing is not ASCII.
 117    NAME_UTF8 is the real name, written in UTF-8 with octal or hexadecimal
 118    escape sequences.  NAME_ASCII is a fallback written only with ASCII
 119    characters.  */
 120 extern const char * proper_name_utf8 (const char *name_ascii,
 121                                       const char *name_utf8);
 122
 123 /* Return the localization of the name spelled NAME_ASCII in ASCII,
 124    and NAME_UTF8 in UTF-8.  This function needs less infrastructure
 125    than proper_name and proper_name_utf8.  */
 126 extern const char *proper_name_lite (const char *name_ascii,
 127                                      const char *name_utf8);
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif
 132
 133
 134 #endif /* _PROPERNAME_H */