doc: Recommend to avoid literal URLs in translatable strings.

Suggested by John Darrington <john@darrington.wattle.id.au>
in <https://lists.gnu.org/archive/html/bug-gnulib/2019-05/msg00033.html>.

* gettext-tools/doc/gettext.texi (Preparing Strings): Add recommendation against
embedded URLs. Add sub-headers.

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index f9b40441fef31a3680a30e6329b1c665b780358d..1bc1c6ad9236cb254d285b5b689008a5803ef6cc 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -2020,6 +2020,9 @@ Split at paragraphs.
 @item
 Use format strings instead of string concatenation.
 
+@item
+Use placeholders in format strings instead of embedded URLs.
+
 @item
 Avoid unusual markup and unusual control characters.
 @end itemize
@@ -2027,6 +2030,8 @@ Avoid unusual markup and unusual control characters.
 @noindent
 Let's look at some examples of these guidelines.
 
+@subheading Decent English style
+
 @cindex style
 Translatable strings should be in good English style.  If slang language
 with abbreviations and shortcuts is used, often translators will not
@@ -2054,6 +2059,8 @@ of the objects"?
 In both cases, adding more words to the message will help both the
 translator and the English speaking user.
 
+@subheading Entire sentences
+
 @cindex sentences
 Translatable strings should be entire sentences.  It is often not possible
 to translate single verbs or adjectives in a substitutable way.
@@ -2123,6 +2130,8 @@ in other places as well, you will do a favour to the translator by not
 merging the two.  (Identical messages occurring in several places are
 combined by xgettext, so the translator has to handle them once only.)
 
+@subheading Split at paragraphs
+
 @cindex paragraphs
 Translatable strings should be limited to one paragraph; don't let a
 single message be longer than ten lines.  The reason is that when the
@@ -2141,6 +2150,8 @@ such as the input options, the output options, and the informative
 output options.  This will help every user to find the option he is
 looking for.
 
+@subheading No string concatenation
+
 @cindex string concatenation
 @cindex concatenation of strings
 Hardcoded string concatenation is sometimes used to construct English
@@ -2241,6 +2252,39 @@ Console.WriteLine(
     String.Format("Replace @{0@} with @{1@}?", object1, object2));
 @end example
 
+@subheading No embedded URLs
+
+It is good to not embed URLs in translatable strings, for several reasons:
+@itemize @bullet
+@item
+It avoids possible mistakes during copy and paste.
+@item
+Translators cannot translate the URLs or, by mistake, use the URLs from
+other packages that are present in their compendium.
+@item
+When the URLs change, translators don't need to revisit the translation
+of the string.
+@end itemize
+
+The same holds for email addresses.
+
+So, you would change
+
+@example
+fputs (_("GNU GPL version 3 <https://gnu.org/licenses/gpl.html>\n"),
+       stream);
+@end example
+
+@noindent
+to
+
+@example
+fprintf (stream, _("GNU GPL version 3 <%s>\n"),
+         "https://gnu.org/licenses/gpl.html");
+@end example
+
+@subheading No unusual markup
+
 @cindex markup
 @cindex control characters
 Unusual markup or control characters should not be used in translatable