lib/propername.h

   1 /* Localization of proper names.  -*- coding: utf-8 -*-
   2    Copyright (C) 2006, 2008-2020 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' module does exactly this. Plus, for languages that use
  49    a different writing system than the Latin alphabet, it allows a translator
  50    to write the name using that different writing system. In that case the
  51    output will look like this:
  52       <translated name> (<original name in English>)
  53
  54    To use the 'propername' module requires three simple steps:
  55
  56      1) Add it to the list of gnulib modules to import,
  57
  58      2) Change the arguments of version_etc(),
  59
  60           from "Paul Eggert"
  61           to   proper_name ("Paul Eggert")
  62
  63           from "Torbjorn Granlund"
  64           to   proper_name_utf8 ("Torbjorn Granlund", "Torbj\303\266rn Granlund")
  65
  66           from "F. Pinard"
  67           to   proper_name_utf8 ("Franc,ois Pinard", "Fran\303\247ois Pinard")
  68
  69         (Optionally, here you can also add / * TRANSLATORS: ... * / comments
  70         explaining how the name is written or pronounced.)
  71
  72      3) If you are using GNU gettext version 0.16.1 or older, in po/Makevars,
  73         in the definition of the XGETTEXT_OPTIONS variable, add:
  74
  75            --keyword='proper_name:1,"This is a proper name. See the gettext manual, section Names."'
  76            --keyword='proper_name_utf8:1,"This is a proper name. See the gettext manual, section Names."'
  77
  78         This specifies automatic comments for the translator. (Requires
  79         xgettext >= 0.15. The double-quotes inside the quoted string are on
  80         purpose: they are part of the --keyword argument syntax.)
  81  */
  82
  83 #ifndef _PROPERNAME_H
  84 #define _PROPERNAME_H
  85
  86
  87 #ifdef __cplusplus
  88 extern "C" {
  89 #endif
  90
  91 /* Return the localization of NAME.  NAME is written in ASCII.  */
  92 extern const char * proper_name (const char *name) /* NOT attribute const */;
  93
  94 /* Return the localization of a name whose original writing is not ASCII.
  95    NAME_UTF8 is the real name, written in UTF-8 with octal or hexadecimal
  96    escape sequences.  NAME_ASCII is a fallback written only with ASCII
  97    characters.  */
  98 extern const char * proper_name_utf8 (const char *name_ascii,
  99                                       const char *name_utf8);
 100
 101 #ifdef __cplusplus
 102 }
 103 #endif
 104
 105
 106 #endif /* _PROPERNAME_H */