1  /* Localization of proper names.  -*- coding: utf-8 -*-
       2     Copyright (C) 2006, 2008-2023 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 two 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  
      73  #ifndef _PROPERNAME_H
      74  #define _PROPERNAME_H
      75  
      76  
      77  #ifdef __cplusplus
      78  extern "C" {
      79  #endif
      80  
      81  /* Return the localization of NAME.  NAME is written in ASCII.  */
      82  extern const char * proper_name (const char *name) /* NOT attribute const */;
      83  
      84  /* Return the localization of a name whose original writing is not ASCII.
      85     NAME_UTF8 is the real name, written in UTF-8 with octal or hexadecimal
      86     escape sequences.  NAME_ASCII is a fallback written only with ASCII
      87     characters.  */
      88  extern const char * proper_name_utf8 (const char *name_ascii,
      89                                        const char *name_utf8);
      90  
      91  #ifdef __cplusplus
      92  }
      93  #endif
      94  
      95  
      96  #endif /* _PROPERNAME_H */