From 16b11fcf00d3117ffae5831f4dc0c30cb11efbef Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Fri, 5 May 2023 15:50:31 -0600
Subject: [PATCH 1/9] correct file name spelling

---
 ...ubequent.txt => disambiguate_YearSuffixWithEtAlSubsequent.txt} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename processor-tests/humans/{disambiguate_YearSuffixWithEtAlSubequent.txt => disambiguate_YearSuffixWithEtAlSubsequent.txt} (100%)

diff --git a/processor-tests/humans/disambiguate_YearSuffixWithEtAlSubequent.txt b/processor-tests/humans/disambiguate_YearSuffixWithEtAlSubsequent.txt
similarity index 100%
rename from processor-tests/humans/disambiguate_YearSuffixWithEtAlSubequent.txt
rename to processor-tests/humans/disambiguate_YearSuffixWithEtAlSubsequent.txt

From bf2eaead0665fe1a7b390ba8154e99ab3b9c2944 Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Thu, 25 May 2023 08:58:51 -0600
Subject: [PATCH 2/9] add disambiguation year suffixes according to reference
 sort order

---
 .../humans/disambiguate_YearSuffixAndSort.txt            | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/processor-tests/humans/disambiguate_YearSuffixAndSort.txt b/processor-tests/humans/disambiguate_YearSuffixAndSort.txt
index 9ec031a..5fe2a54 100644
--- a/processor-tests/humans/disambiguate_YearSuffixAndSort.txt
+++ b/processor-tests/humans/disambiguate_YearSuffixAndSort.txt
@@ -3,6 +3,14 @@ citation
 <<===== MODE =====<<
 
 
+>>===== DESCRIPTION =====>>
+Per the CSL specification, with the add-year-suffix disambiguation method, "the assignment of
+year-suffixes follows the order of the bibliographies entries."
+
+https://docs.citationstyles.org/en/stable/specification.html#disambiguation
+<<===== DESCRIPTION =====<<
+
+
 >>===== CITATION-ITEMS =====>>
 [
     [
@@ -49,6 +57,7 @@ citation
 ]
 <<===== CITATION-ITEMS =====<<
 
+
 >>===== RESULT =====>>
 1990m!; 1990l!; 1990k!; 1990j!; 1990i!; 1990h!; 1990g!; 1990f!; 1990e!; 1990d!; 1990c!; 1990b!; 1990a!
 <<===== RESULT =====<<

From d062420bf5bb33b0704f8e002ac3a6e5180c0cdf Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Sun, 11 Jun 2023 11:41:20 -0600
Subject: [PATCH 3/9] Rename tests to match contents

These test were modified in the past so they no longer match their names
---
 ...graphyCitationNumberAscendingSecondary.txt | 127 +++++++++++++++++
 ...raphyCitationNumberDescendingSecondary.txt | 129 ++++++------------
 ...ationNumberDescendingViaCompositeMacro.txt |  78 -----------
 3 files changed, 167 insertions(+), 167 deletions(-)
 create mode 100644 processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
 delete mode 100644 processor-tests/humans/sort_BibliographyCitationNumberDescendingViaCompositeMacro.txt

diff --git a/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt b/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
new file mode 100644
index 0000000..1a9cc71
--- /dev/null
+++ b/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
@@ -0,0 +1,127 @@
+>>==== MODE ====>>
+bibliography
+<<==== MODE ====<<
+
+>>==== RESULT ====>>
+<div class="csl-bib-body">
+  <div class="csl-entry">[1] Book 001</div>
+  <div class="csl-entry">[2] Book 002</div>
+  <div class="csl-entry">[3] Book 003</div>
+  <div class="csl-entry">[4] Book 004</div>
+  <div class="csl-entry">[5] Book 005</div>
+  <div class="csl-entry">[6] Book 006</div>
+  <div class="csl-entry">[7] Book 007</div>
+  <div class="csl-entry">[8] Book 008</div>
+</div>
+<<==== RESULT ====<<
+
+>>==== CITATION-ITEMS ====>>
+[
+    [
+        {
+            "id": "ITEM-1"
+        },
+        {
+            "id": "ITEM-2"
+        },
+        {
+            "id": "ITEM-3"
+        },
+        {
+            "id": "ITEM-4"
+        },
+        {
+            "id": "ITEM-5"
+        },
+        {
+            "id": "ITEM-6"
+        },
+        {
+            "id": "ITEM-7"
+        },
+        {
+            "id": "ITEM-8"
+        }
+    ]
+]
+<<==== CITATION-ITEMS ====<<
+
+>>==== CSL ====>>
+<style 
+      xmlns="http://purl.org/net/xbiblio/csl"
+      class="note"
+      version="1.0">
+  <info>
+    <id />
+    <title />
+    <updated>2009-08-10T04:49:00+09:00</updated>
+  </info>
+  <citation>
+    <layout>
+      <text value="bogus"/>
+    </layout>
+  </citation>
+  <bibliography>
+    <sort>
+      <key variable="title"/>
+      <key variable="citation-number" sort="ascending"/>
+    </sort>
+    <layout>
+      <text variable="citation-number" prefix="[" suffix="] "/>
+      <text variable="title" />
+    </layout>
+  </bibliography>
+</style>
+<<==== CSL ====<<
+
+>>==== INPUT ====>>
+[
+  {
+    "id": "ITEM-1",
+    "title": "Book 001",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-2",
+    "title": "Book 003",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-3",
+    "title": "Book 004",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-4",
+    "title": "Book 006",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-5",
+    "title": "Book 002",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-6",
+    "title": "Book 005",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-7",
+    "title": "Book 007",
+    "type": "book"
+  },
+  {
+    "id": "ITEM-8",
+    "title": "Book 008",
+    "type": "book"
+  }
+]
+<<==== INPUT ====<<
+
+
+
+>>===== VERSION =====>>
+1.0
+<<===== VERSION =====<<
+
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt b/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
index 1a9cc71..0aaa209 100644
--- a/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
+++ b/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
@@ -1,52 +1,20 @@
->>==== MODE ====>>
+>>===== MODE =====>>
 bibliography
-<<==== MODE ====<<
+<<===== MODE =====<<
 
->>==== RESULT ====>>
+
+
+>>===== RESULT =====>>
 <div class="csl-bib-body">
-  <div class="csl-entry">[1] Book 001</div>
-  <div class="csl-entry">[2] Book 002</div>
-  <div class="csl-entry">[3] Book 003</div>
-  <div class="csl-entry">[4] Book 004</div>
-  <div class="csl-entry">[5] Book 005</div>
-  <div class="csl-entry">[6] Book 006</div>
-  <div class="csl-entry">[7] Book 007</div>
-  <div class="csl-entry">[8] Book 008</div>
+  <div class="csl-entry">[4] Aaaa</div>
+  <div class="csl-entry">[3] Bbbb</div>
+  <div class="csl-entry">[2] Xxxx</div>
+  <div class="csl-entry">[1] Zzzz</div>
 </div>
-<<==== RESULT ====<<
+<<===== RESULT =====<<
 
->>==== CITATION-ITEMS ====>>
-[
-    [
-        {
-            "id": "ITEM-1"
-        },
-        {
-            "id": "ITEM-2"
-        },
-        {
-            "id": "ITEM-3"
-        },
-        {
-            "id": "ITEM-4"
-        },
-        {
-            "id": "ITEM-5"
-        },
-        {
-            "id": "ITEM-6"
-        },
-        {
-            "id": "ITEM-7"
-        },
-        {
-            "id": "ITEM-8"
-        }
-    ]
-]
-<<==== CITATION-ITEMS ====<<
 
->>==== CSL ====>>
+>>===== CSL =====>>
 <style 
       xmlns="http://purl.org/net/xbiblio/csl"
       class="note"
@@ -56,6 +24,9 @@ bibliography
     <title />
     <updated>2009-08-10T04:49:00+09:00</updated>
   </info>
+  <macro name="citation-number">
+    <text variable="citation-number"/>
+  </macro>
   <citation>
     <layout>
       <text value="bogus"/>
@@ -63,8 +34,8 @@ bibliography
   </citation>
   <bibliography>
     <sort>
-      <key variable="title"/>
-      <key variable="citation-number" sort="ascending"/>
+      <key variable="title" sort="ascending"/>
+      <key variable="citation-number" sort="descending"/>
     </sort>
     <layout>
       <text variable="citation-number" prefix="[" suffix="] "/>
@@ -72,53 +43,33 @@ bibliography
     </layout>
   </bibliography>
 </style>
-<<==== CSL ====<<
+<<===== CSL =====<<
+
 
->>==== INPUT ====>>
+>>===== INPUT =====>>
 [
-  {
-    "id": "ITEM-1",
-    "title": "Book 001",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-2",
-    "title": "Book 003",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-3",
-    "title": "Book 004",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-4",
-    "title": "Book 006",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-5",
-    "title": "Book 002",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-6",
-    "title": "Book 005",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-7",
-    "title": "Book 007",
-    "type": "book"
-  },
-  {
-    "id": "ITEM-8",
-    "title": "Book 008",
-    "type": "book"
-  }
+    {
+        "id": "item-1",
+        "title": "Aaaa",
+        "type": "book"
+    },
+    {
+        "id": "item-3",
+        "title": "Bbbb",
+        "type": "book"
+    },
+    {
+        "id": "item-4",
+        "title": "Zzzz",
+        "type": "book"
+    },
+    {
+        "id": "item-5",
+        "title": "Xxxx",
+        "type": "book"
+    }
 ]
-<<==== INPUT ====<<
-
+<<===== INPUT =====<<
 
 
 >>===== VERSION =====>>
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaCompositeMacro.txt b/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaCompositeMacro.txt
deleted file mode 100644
index 0aaa209..0000000
--- a/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaCompositeMacro.txt
+++ /dev/null
@@ -1,78 +0,0 @@
->>===== MODE =====>>
-bibliography
-<<===== MODE =====<<
-
-
-
->>===== RESULT =====>>
-<div class="csl-bib-body">
-  <div class="csl-entry">[4] Aaaa</div>
-  <div class="csl-entry">[3] Bbbb</div>
-  <div class="csl-entry">[2] Xxxx</div>
-  <div class="csl-entry">[1] Zzzz</div>
-</div>
-<<===== RESULT =====<<
-
-
->>===== CSL =====>>
-<style 
-      xmlns="http://purl.org/net/xbiblio/csl"
-      class="note"
-      version="1.0">
-  <info>
-    <id />
-    <title />
-    <updated>2009-08-10T04:49:00+09:00</updated>
-  </info>
-  <macro name="citation-number">
-    <text variable="citation-number"/>
-  </macro>
-  <citation>
-    <layout>
-      <text value="bogus"/>
-    </layout>
-  </citation>
-  <bibliography>
-    <sort>
-      <key variable="title" sort="ascending"/>
-      <key variable="citation-number" sort="descending"/>
-    </sort>
-    <layout>
-      <text variable="citation-number" prefix="[" suffix="] "/>
-      <text variable="title" />
-    </layout>
-  </bibliography>
-</style>
-<<===== CSL =====<<
-
-
->>===== INPUT =====>>
-[
-    {
-        "id": "item-1",
-        "title": "Aaaa",
-        "type": "book"
-    },
-    {
-        "id": "item-3",
-        "title": "Bbbb",
-        "type": "book"
-    },
-    {
-        "id": "item-4",
-        "title": "Zzzz",
-        "type": "book"
-    },
-    {
-        "id": "item-5",
-        "title": "Xxxx",
-        "type": "book"
-    }
-]
-<<===== INPUT =====<<
-
-
->>===== VERSION =====>>
-1.0
-<<===== VERSION =====<<
-

From 02dab6c1f7d5c6bc0d4b871afbc9475f1c65da2a Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Sun, 11 Jun 2023 19:08:53 -0600
Subject: [PATCH 4/9] add citation-number description with help links

---
 ...sort_BibliographyCitationNumberAscendingSecondary.txt | 9 +++++++++
 .../humans/sort_BibliographyCitationNumberDescending.txt | 8 ++++++++
 ...ort_BibliographyCitationNumberDescendingSecondary.txt | 8 ++++++++
 ...sort_BibliographyCitationNumberDescendingViaMacro.txt | 8 ++++++++
 ...itationNumberPrimaryAscendingViaMacroBibliography.txt | 9 +++++++++
 ...rt_CitationNumberPrimaryAscendingViaMacroCitation.txt | 9 +++++++++
 ...tionNumberPrimaryAscendingViaVariableBibliography.txt | 9 +++++++++
 ...CitationNumberPrimaryAscendingViaVariableCitation.txt | 9 +++++++++
 ...tationNumberPrimaryDescendingViaMacroBibliography.txt | 9 +++++++++
 ...t_CitationNumberPrimaryDescendingViaMacroCitation.txt | 9 +++++++++
 ...ionNumberPrimaryDescendingViaVariableBibliography.txt | 9 +++++++++
 ...itationNumberPrimaryDescendingViaVariableCitation.txt | 9 +++++++++
 ...ationNumberSecondaryAscendingViaMacroBibliography.txt | 9 +++++++++
 ..._CitationNumberSecondaryAscendingViaMacroCitation.txt | 9 +++++++++
 ...onNumberSecondaryAscendingViaVariableBibliography.txt | 9 +++++++++
 ...tationNumberSecondaryAscendingViaVariableCitation.txt | 9 +++++++++
 16 files changed, 141 insertions(+)

diff --git a/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt b/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
index 1a9cc71..572b484 100644
--- a/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
+++ b/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
@@ -2,6 +2,14 @@
 bibliography
 <<==== MODE ====<<
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
 >>==== RESULT ====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Book 001</div>
@@ -15,6 +23,7 @@ bibliography
 </div>
 <<==== RESULT ====<<
 
+
 >>==== CITATION-ITEMS ====>>
 [
     [
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescending.txt b/processor-tests/humans/sort_BibliographyCitationNumberDescending.txt
index e45024a..08177aa 100644
--- a/processor-tests/humans/sort_BibliographyCitationNumberDescending.txt
+++ b/processor-tests/humans/sort_BibliographyCitationNumberDescending.txt
@@ -2,6 +2,14 @@
 bibliography
 <<==== MODE ====<<
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
 >>==== RESULT ====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Book 008</div>
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt b/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
index 0aaa209..c56d1e3 100644
--- a/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
+++ b/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
@@ -3,6 +3,14 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
 
 >>===== RESULT =====>>
 <div class="csl-bib-body">
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt b/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt
index b7a1fc8..4c36c5c 100644
--- a/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt
+++ b/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt
@@ -3,6 +3,14 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
 
 >>===== RESULT =====>>
 <div class="csl-bib-body">
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroBibliography.txt b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroBibliography.txt
index b68c585..7242ca6 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Aaaa (first-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroCitation.txt b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroCitation.txt
index ce194be..6109dac 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaMacroCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 >>[0] [1] Aaaa (first-cited); [2] Bbbb (second-cited); [3] Zzzz (third-cited); [4] Xxxx (fourth-cited)
 <<===== RESULT =====<<
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableBibliography.txt b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableBibliography.txt
index 752b609..ab5345f 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Aaaa (first-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableCitation.txt b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableCitation.txt
index 7e403d3..fde4bb2 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryAscendingViaVariableCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 >>[0] [1] Aaaa (first-cited); [2] Bbbb (second-cited); [3] Zzzz (third-cited); [4] Xxxx (fourth-cited)
 <<===== RESULT =====<<
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
index eca205a..85d421d 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[4] Xxxx (fourth-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
index d3b04b5..7824f3b 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 >>[0] [1] Aaaa (first-cited); [2] Bbbb (second-cited); [3] Zzzz (third-cited); [4] Xxxx (fourth-cited)
 <<===== RESULT =====<<
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
index 97e6ad3..f771fbe 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[4] Xxxx (fourth-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
index 1fb4f85..1048e6e 100644
--- a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 >>[0] [1] Aaaa (first-cited); [2] Bbbb (second-cited); [3] Zzzz (third-cited); [4] Xxxx (fourth-cited)
 <<===== RESULT =====<<
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
index c29c870..2bfbe88 100644
--- a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Zzzz (third-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
index 4a5db6e..be198d5 100644
--- a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 [1] Zzzz (third-cited); [2] Xxxx (fourth-cited); [3] Bbbb (second-cited); [4] Aaaa (first-cited)
 <<===== RESULT =====<<
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
index 7c9f43c..2e6c74e 100644
--- a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
+++ b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
@@ -3,6 +3,15 @@ bibliography
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 <div class="csl-bib-body">
   <div class="csl-entry">[1] Zzzz (third-cited)</div>
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
index c608179..bda79e4 100644
--- a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
+++ b/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
@@ -3,6 +3,15 @@ citation
 <<===== MODE =====<<
 
 
+>>==== DESCRIPTION ====>>
+Sorting on and rendering citation-numbers is accomplished with specialized logic that isn't fully
+documented in the specification. Please see the links below for an explanation.
+
+https://github.com/citation-style-language/test-suite/issues/62
+https://forums.zotero.org/discussion/71443/reverse-number-bibliography
+<<==== DESCRIPTION ====<<
+
+
 >>===== RESULT =====>>
 >>[0] [1] Zzzz (third-cited); [2] Xxxx (fourth-cited); [3] Bbbb (second-cited); [4] Aaaa (first-cited)
 <<===== RESULT =====<<

From ce7736a6474cc7b56555c501ff3d3bfe8149c029 Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Mon, 12 Jun 2023 10:13:54 -0600
Subject: [PATCH 5/9] stub README

---
 processor-tests/humans/off-spec/README.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 processor-tests/humans/off-spec/README.md

diff --git a/processor-tests/humans/off-spec/README.md b/processor-tests/humans/off-spec/README.md
new file mode 100644
index 0000000..e69de29

From f55061d807e45b79a7b677922cdbc8027e8da13e Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Tue, 13 Jun 2023 12:07:53 -0600
Subject: [PATCH 6/9] initial README for off-spec tests

---
 processor-tests/humans/off-spec/README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/processor-tests/humans/off-spec/README.md b/processor-tests/humans/off-spec/README.md
index e69de29..094ed04 100644
--- a/processor-tests/humans/off-spec/README.md
+++ b/processor-tests/humans/off-spec/README.md
@@ -0,0 +1,10 @@
+Tests in this folder expect behaviors that aren't defined in the [CSL Specification](https://docs.citationstyles.org/en/stable/specification.html). Each such test
+should include a `DESCRIPTION` block describing its particular deviation.
+
+The specific disposition of these tests varies. For example, they may expect behavior that
+
+- should be added to a future version of the specification
+- is useful but implemented in a way that needs to be re-worked before it can be added to the specification
+- is specific to an internal process of [citeproc-js](https://github.com/Juris-M/citeproc-js) and so may belong among [its local tests](https://github.com/Juris-M/citeproc-js/tree/master/fixtures/local)
+
+CSL Processor authors and testers may omit tests in this folder if their purpose is simply to implement the specification. They may, however, find these tests useful if they also want to match the behavior of existing tools or software written according to these additional tests.
\ No newline at end of file

From 1ef83bb0a7ca7cf03328bb56c86caed3eda982d3 Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Wed, 14 Jun 2023 13:49:33 -0600
Subject: [PATCH 7/9] initial citation-number test moves to off-spec

---
 .vscode/settings.json                                       | 6 ++++++
 .../sort_BibliographyCitationNumberAscendingSecondary.txt   | 0
 .../sort_BibliographyCitationNumberDescending.txt           | 0
 .../sort_BibliographyCitationNumberDescendingSecondary.txt  | 0
 .../sort_BibliographyCitationNumberDescendingViaMacro.txt   | 0
 ..._CitationNumberPrimaryDescendingViaMacroBibliography.txt | 0
 ...sort_CitationNumberPrimaryDescendingViaMacroCitation.txt | 0
 ...tationNumberPrimaryDescendingViaVariableBibliography.txt | 0
 ...t_CitationNumberPrimaryDescendingViaVariableCitation.txt | 0
 ...CitationNumberSecondaryAscendingViaMacroBibliography.txt | 0
 ...ort_CitationNumberSecondaryAscendingViaMacroCitation.txt | 0
 ...ationNumberSecondaryAscendingViaVariableBibliography.txt | 0
 ..._CitationNumberSecondaryAscendingViaVariableCitation.txt | 0
 processor-tests/humans/punctuation_FrenchOrthography.txt    | 3 +++
 14 files changed, 9 insertions(+)
 create mode 100644 .vscode/settings.json
 rename processor-tests/humans/{ => off-spec}/sort_BibliographyCitationNumberAscendingSecondary.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_BibliographyCitationNumberDescending.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_BibliographyCitationNumberDescendingSecondary.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_BibliographyCitationNumberDescendingViaMacro.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt (100%)
 rename processor-tests/humans/{ => off-spec}/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt (100%)

diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..3f7a962
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,6 @@
+{
+   "[python]": {
+      "editor.defaultFormatter": "ms-python.black-formatter"
+   },
+   "python.formatting.provider": "none"
+}
\ No newline at end of file
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt b/processor-tests/humans/off-spec/sort_BibliographyCitationNumberAscendingSecondary.txt
similarity index 100%
rename from processor-tests/humans/sort_BibliographyCitationNumberAscendingSecondary.txt
rename to processor-tests/humans/off-spec/sort_BibliographyCitationNumberAscendingSecondary.txt
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescending.txt b/processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescending.txt
similarity index 100%
rename from processor-tests/humans/sort_BibliographyCitationNumberDescending.txt
rename to processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescending.txt
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt b/processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescendingSecondary.txt
similarity index 100%
rename from processor-tests/humans/sort_BibliographyCitationNumberDescendingSecondary.txt
rename to processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescendingSecondary.txt
diff --git a/processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt b/processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescendingViaMacro.txt
similarity index 100%
rename from processor-tests/humans/sort_BibliographyCitationNumberDescendingViaMacro.txt
rename to processor-tests/humans/off-spec/sort_BibliographyCitationNumberDescendingViaMacro.txt
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt b/processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaMacroBibliography.txt
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt b/processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaMacroCitation.txt
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt b/processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaVariableBibliography.txt
diff --git a/processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt b/processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberPrimaryDescendingViaVariableCitation.txt
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt b/processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaMacroBibliography.txt
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt b/processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaMacroCitation.txt
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt b/processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaVariableBibliography.txt
diff --git a/processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt b/processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
similarity index 100%
rename from processor-tests/humans/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
rename to processor-tests/humans/off-spec/sort_CitationNumberSecondaryAscendingViaVariableCitation.txt
diff --git a/processor-tests/humans/punctuation_FrenchOrthography.txt b/processor-tests/humans/punctuation_FrenchOrthography.txt
index 8a23388..c78f739 100644
--- a/processor-tests/humans/punctuation_FrenchOrthography.txt
+++ b/processor-tests/humans/punctuation_FrenchOrthography.txt
@@ -3,6 +3,7 @@ citation
 <<===== MODE =====<<
 
 
+>>===== DESCRIPTION =====>>
 It may not be immediately apparent, but the spaces immediately
 inside the double angle quotes below are half-width no-break
 spaces ("narrow no-break space").
@@ -10,6 +11,8 @@ spaces ("narrow no-break space").
 See http://en.wikipedia.org/wiki/Space_(punctuation)#Breaking_and_non-breaking_spaces
 and http://forums.zotero.org/discussion/4933/localized-quotes/#Comment_88384
 for details.
+<<===== DESCRIPTION =====<<
+
 
 >>===== RESULT =====>>
 His « Anonymous » Life

From 0f82099f2cb90aafa0bf673fbaf7a34641654c26 Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Wed, 14 Jun 2023 13:50:40 -0600
Subject: [PATCH 8/9] remove vscode settings and add to .gitignore

---
 .gitignore            | 1 +
 .vscode/settings.json | 6 ------
 2 files changed, 1 insertion(+), 6 deletions(-)
 create mode 100644 .gitignore
 delete mode 100644 .vscode/settings.json

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..600d2d3
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.vscode
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
deleted file mode 100644
index 3f7a962..0000000
--- a/.vscode/settings.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
-   "[python]": {
-      "editor.defaultFormatter": "ms-python.black-formatter"
-   },
-   "python.formatting.provider": "none"
-}
\ No newline at end of file

From ea947cffe0cc1a2bb0b171e33d0be545d88a78ef Mon Sep 17 00:00:00 2001
From: Jason Abbott <jason@toba.io>
Date: Sun, 18 Jun 2023 14:20:01 -0600
Subject: [PATCH 9/9] handle empty bibliography dates

---
 processor-tests/humans/date_SortEmptyDatesBibliography.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/processor-tests/humans/date_SortEmptyDatesBibliography.txt b/processor-tests/humans/date_SortEmptyDatesBibliography.txt
index 75018ee..4b0ffdd 100644
--- a/processor-tests/humans/date_SortEmptyDatesBibliography.txt
+++ b/processor-tests/humans/date_SortEmptyDatesBibliography.txt
@@ -2,10 +2,13 @@
 bibliography
 <<===== MODE =====<<
 
+
+>>===== DESCRIPTION =====>>
 Sort position of empty dates differs in citations and bibliographies.
 In citations, empty dates have a value equivalent to zero.  In
 bibliographies, they are always placed at the end of the sort
 (whether ascending or descending).
+<<===== DESCRIPTION =====<<
 
 
 >>===== RESULT =====>>