Update section about proper names.

2 files changed, 46 insertions, 19 deletions

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 5b11039..a75aa53 100644
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,10 @@
+2008-05-18  Bruno Haible  <bruno@clisp.org>
+
+	* gettext.texi (Names): Recommend the gnulib module 'propername'.
+	Don't mention the translation project's whoiswho.pot any more. Don't
+	say that Emacs does not support UTF-8 well.
+	Reported by Brian Kemp <brian.kemp@gmail.com>.
+
 2008-05-06  Bruno Haible  <bruno@clisp.org>
 
 	* gettext.texi (Plural forms): Explain why the number argument must be
diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index f584b42..39bedc4 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -2642,7 +2642,8 @@ read the script the name is originally written in.
 
 As a programmer, you should therefore make sure that names are marked
 for translation, with a special comment telling the translators that it
-is a proper name and how to pronounce it.  Like this:
+is a proper name and how to pronounce it.  In its simple form, it looks
+like this:
 
 @example
 @group
@@ -2656,16 +2657,48 @@ printf (_("Written by %s.\n"),
 @end group
 @end example
 
+@noindent
+The GNU gnulib library offers a module @samp{propername}
+(@url{http://www.gnu.org/software/gnulib/MODULES.html#module=propername})
+which takes care to automatically append the original name, in parentheses,
+to the translated name.  For names that cannot be written in ASCII, it
+also frees the translator from the task of entering the appropriate non-ASCII
+characters if no script change is needed.  In this more comfortable form,
+it looks like this:
+
+@example
+@group
+printf (_("Written by %s and %s.\n"),
+        proper_name ("Ulrich Drepper"),
+        /* TRANSLATORS: This is a proper name.  See the gettext
+           manual, section Names.  Note this is actually a non-ASCII
+           name: The first name is (with Unicode escapes)
+           "Fran\u00e7ois" or (with HTML entities) "Fran&ccedil;ois".
+           Pronunciation is like "fraa-swa pee-nar".  */
+        proper_name_utf8 ("Francois Pinard", "Fran\303\247ois Pinard"));
+@end group
+@end example
+
+@noindent
+You can also write the original name directly in Unicode (rather than with
+Unicode escapes or HTML entities) and denote the pronunciation using the
+International Phonetic Alphabet (see
+@url{http://www.wikipedia.org/wiki/International_Phonetic_Alphabet}).
+
 As a translator, you should use some care when translating names, because
-it is frustrating if people see their names mutilated or distorted.  If
-your language uses the Latin script, all you need to do is to reproduce
+it is frustrating if people see their names mutilated or distorted.
+
+If your language uses the Latin script, all you need to do is to reproduce
 the name as perfectly as you can within the usual character set of your
 language.  In this particular case, this means to provide a translation
 containing the c-cedilla character.  If your language uses a different
 script and the people speaking it don't usually read Latin words, it means
-transliteration; but you should still give, in parentheses, the original
-writing of the name -- for the sake of the people that do read the Latin
-script.  Here is an example, using Greek as the target script:
+transliteration.  If the programmer used the simple case, you should still
+give, in parentheses, the original writing of the name -- for the sake of
+the people that do read the Latin script.  If the programmer used the
+@samp{propername} module mentioned above, you don't need to give the original
+writing of the name in parentheses, because the program will already do so.
+Here is an example, using Greek as the target script:
 
 @example
 @group
@@ -2683,19 +2716,6 @@ msgstr "\phi\rho\alpha\sigma\omicron\alpha \pi\iota\nu\alpha\rho"
 Because translation of names is such a sensitive domain, it is a good
 idea to test your translation before submitting it.
 
-The translation project @url{http://sourceforge.net/projects/translation}
-has set up a POT file and translation domain consisting of program author
-names, with better facilities for the translator than those presented here.
-Namely, there the original name is written directly in Unicode (rather
-than with Unicode escapes or HTML entities), and the pronunciation is
-denoted using the International Phonetic Alphabet (see
-@url{http://www.wikipedia.org/wiki/International_Phonetic_Alphabet}).
-
-However, we don't recommend this approach for all POT files in all packages,
-because this would force translators to use PO files in UTF-8 encoding,
-which is - in the current state of software (as of 2003) - a major hassle
-for translators using GNU Emacs or XEmacs with po-mode.
-
 @node Libraries,  , Names, Sources
 @section Preparing Library Sources