From dfcfa4f3c3ba1ba9a61f253f0fe2eb7bf83b587e Mon Sep 17 00:00:00 2001
From: Norman Walsh <ndw@nwalsh.com>
Date: Wed, 12 Jun 2024 17:41:06 +0100
Subject: [PATCH] Add a note about how xs:language codes are defined

---
 src/main/xml/bibliography.xml          | 26 +++++++++++++++++++-------
 steps/src/main/xml/references.xml      |  3 +++
 steps/src/main/xml/steps/text-sort.xml | 20 ++++++++++++++------
 3 files changed, 36 insertions(+), 13 deletions(-)

diff --git a/src/main/xml/bibliography.xml b/src/main/xml/bibliography.xml
index 120f716..a1aa5d9 100644
--- a/src/main/xml/bibliography.xml
+++ b/src/main/xml/bibliography.xml
@@ -263,6 +263,18 @@ Multipurpose Internet Mail Extensions (MIME) Part Two: Media
 Types</citetitle>. N. Freed, N. Borenstein, editors. Internet
 Engineering Task Force. November, 1996.</bibliomixed>
 
+<bibliomixed xml:id="rfc4646"><abbrev>RFC 4646</abbrev>
+<citetitle xlink:href="http://www.ietf.org/rfc/rfc4646.txt">RFC 4646:
+Tags for Identifying Languages</citetitle>.
+A. Phillips and M. Davis, editors.
+Internet Engineering Task Force. September, 2006.</bibliomixed>
+
+<bibliomixed xml:id="rfc4647"><abbrev>RFC 4647</abbrev>
+<citetitle xlink:href="http://www.ietf.org/rfc/rfc4647.txt">RFC 4647:
+Matching of Language Tags</citetitle>.
+A. Phillips and M. Davis, editors.
+Internet Engineering Task Force. September, 2006.</bibliomixed>
+
 <bibliomixed xml:id="rfc2119"><abbrev>RFC 2119</abbrev>
 <citetitle xlink:href="https://doi.org/10.17487/RFC2119"
 >Key words for use in RFCs to Indicate Requirement Levels</citetitle>.
@@ -271,13 +283,13 @@ Network Working Group, IETF,
 Mar 1997.
 </bibliomixed>
 
-<bibliomixed xml:id="rfc2396"><abbrev>RFC 2396</abbrev>
-<citetitle xlink:href="https://doi.org/10.17487/RFC2396"
->Uniform Resource Identifiers (URI): Generic Syntax</citetitle>.
-T. Berners-Lee, R. Fielding, and L. Masinter.
-Network Working Group, IETF,
-Aug 1998.
-</bibliomixed>
+<bibliomixed xml:id="bcp47"><abbrev>BCP 47</abbrev>
+Best Current Practices 47. Concatenation of RFC 4646: Tags for Identifying
+Languages, ed. A. Phillips and M. Davis, September 2006,
+http://www.ietf.org/rfc/bcp/bcp47.txt, and RFC 4647: Matching of Language Tags,
+ed. A Phillips and M. Davis, September 2006,
+http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
+Internet Engineering Task Force (IETF). September, 2006.</bibliomixed>
 
 <bibliomixed xml:id="rfc2616"><abbrev>RFC 2616</abbrev>
 <citetitle xlink:href="https://doi.org/10.17487/RFC2616">RFC 2616:
diff --git a/steps/src/main/xml/references.xml b/steps/src/main/xml/references.xml
index 24a7b14..dc3708b 100644
--- a/steps/src/main/xml/references.xml
+++ b/steps/src/main/xml/references.xml
@@ -20,6 +20,9 @@
     <bibliomixed xml:id="rfc2119"/>
     <bibliomixed xml:id="rfc2617"/>
     <bibliomixed xml:id="rfc3986"/>
+    <bibliomixed xml:id="rfc4646"/>
+    <bibliomixed xml:id="rfc4647"/>
+    <bibliomixed xml:id="bcp47"/>
     <bibliomixed xml:id="bib.uuid"/>
     <bibliomixed xml:id="bib.sha"/>
     <bibliomixed xml:id="bib.crc"/>
diff --git a/steps/src/main/xml/steps/text-sort.xml b/steps/src/main/xml/steps/text-sort.xml
index 556eaa2..8de922c 100644
--- a/steps/src/main/xml/steps/text-sort.xml
+++ b/steps/src/main/xml/steps/text-sort.xml
@@ -42,12 +42,20 @@
         lower-case letters. Its value <rfc2119>must</rfc2119> be one of <code>upper-first</code> or
           <code>lower-first</code>. The default is language-dependent.</para>
     </listitem>
-    <listitem>
-      <para>The <option>lang</option> option defines the language whose collating conventions are to be used. The
-        default depends on the processing environment. Its value must be a valid language code (e.g.
-        <code>en-EN</code>).</para>
-    </listitem>
-     <listitem>
+
+<listitem>
+<para>The <option>lang</option> option defines the language whose collating
+conventions are to be used.
+The <code>xs:language</code> data type represents natural language identifiers
+as defined by <biblioref linkend="bcp47"/> (currently
+represented by <biblioref linkend="rfc4646"/> and <biblioref linkend="rfc4647"/>
+or its successor(s).)
+The default depends on the processing environment.
+Its value must be a valid language code (e.g. <code>en-EN</code>).
+</para>
+</listitem>
+
+<listitem>
       <para>The <option>collation</option> option identifies how strings are to be compared with each other. Its value
         must be a valid collation URI. The only collation XProc processors <rfc2119>must</rfc2119> support is the
         Unicode Codepoint Collation <link xlink:href="http://www.w3.org/2005/xpath-functions/collation/codepoint/"