[PATCH] intl: Clarify the role and the contents of locale.alias.

[Bruno Haible]

* intl/localealias.c: Explain the form and the purpose of the locale.alias file.
* intl/locale.alias: Don't state that this file is obsolete. Instead, two groups
of entries are obsolete, for different reasons.
---
 intl/locale.alias  | 18 +++++++++++-------
 intl/localealias.c | 25 +++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/intl/locale.alias b/intl/locale.alias
index 8904983a59..471da95f32 100644
--- a/intl/locale.alias
+++ b/intl/locale.alias
@@ -19,12 +19,10 @@
 #	/usr/lib/X11/locale/locale.alias
 # A single line contains two fields: an alias and a substitution value.
 # All entries are case independent.
+# Lines that start with '#' are comment lines.
 
-# Note: This file is obsolete and is kept around for the time being for
-# backward compatibility.  Nobody should rely on the names defined here.
-# Locales should always be specified by their full name.
-
-# Note: This file used to contain the following lines:
+# Note: This file should only contain ASCII characters.  It used to
+# contain the following lines:
 #	bokmaal		nb_NO.ISO-8859-1
 #	franc,ais	fr_FR.ISO-8859-1
 # except that the "aa" was actually the byte '\0xE5' (the Latin-1
@@ -35,6 +33,9 @@
 # which broke applications in UTF-8 locales.  See:
 # https://sourceware.org/bugzilla/show_bug.cgi?id=18412
 
+# The following entries are obsolete.  They date back to 1996-2000, when
+# it was not customary to use real locale names.  Locales should nowadays
+# always be specified by their full name.
 bokmal		nb_NO.ISO-8859-1
 catalan		ca_ES.ISO-8859-1
 croatian	hr_HR.ISO-8859-2
@@ -65,8 +66,6 @@ korean		ko_KR.eucKR
 korean.euc 	ko_KR.eucKR
 ko_KR		ko_KR.eucKR
 lithuanian      lt_LT.ISO-8859-13
-no_NO		nb_NO.ISO-8859-1
-no_NO.ISO-8859-1 nb_NO.ISO-8859-1
 norwegian       nb_NO.ISO-8859-1
 nynorsk		nn_NO.ISO-8859-1
 polish          pl_PL.ISO-8859-2
@@ -80,3 +79,8 @@ spanish         es_ES.ISO-8859-1
 swedish         sv_SE.ISO-8859-1
 thai		th_TH.TIS-620
 turkish         tr_TR.ISO-8859-9
+
+# The following entries are obsolete.  They date back to the transition
+# from the ISO 639 language code 'no' to 'nb', in 2003.
+no_NO		nb_NO.ISO-8859-1
+no_NO.ISO-8859-1 nb_NO.ISO-8859-1
diff --git a/intl/localealias.c b/intl/localealias.c
index ea4f48b594..cab4ce44ef 100644
--- a/intl/localealias.c
+++ b/intl/localealias.c
@@ -14,6 +14,31 @@
    You should have received a copy of the GNU Lesser General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
 
+/* Locale aliases can be specified in the file $(localedir)/locale.alias.
+   It consists of lines of the form
+     <alias> <real-locale-name>
+   Lines that start with '#' are comment lines.
+
+   The main purpose of locale aliases is allow a seamless transition when
+   a locale is replaced by another one, and the users still want to use
+   the old locale name in their .profile scripts and elsewhere.
+   This typically happens when
+   (a) The ISO 639 language code of a language changes.  For example,
+       around 2003, the no_NO locale was withdrawn in favour of two
+       separate locales nb_NO and nn_NO.  Users in Norway could have
+       used the alias
+         no_NO.UTF-8 nb_NO.UTF-8
+       or
+         no_NO.UTF-8 nn_NO.UTF-8
+       depending on the language they speak.
+   (b) The ISO 3166 country code of a territory changes.  For example,
+       users in South Sudan saw their ISO 3166 country code change from
+       SD to SS in 2011, and their locale name changed from ar_SD.UTF-8
+       to ar_SS.UTF-8 in 2013 accordingly.  During the transition, they
+       may have used the alias
+         ar_SD.UTF-8 ar_SS.UTF-8
+ */
+
 /* Tell glibc's <string.h> to provide a prototype for mempcpy().
    This must come before <config.h> because <config.h> may include
    <features.h>, and once <features.h> has been included, it's too late.  */
-- 
2.34.1