Keep footnote and reference names (hellt#14)

Author: mjbear

.github/workflows/cicd.yml

@@ -35,7 +35,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Run Python unit tests
-        run: python -m unittest discover -s ${{ env.test_dir }}
+        run: python -m unittest discover -v -s ${{ env.test_dir }}
 
   docker:
     runs-on: ubuntu-latest

README.md

@@ -38,5 +38,12 @@ This option adds spacing between those inline references so they are properly id
 
 `fnsort.py path/to/doc.md --adjacent`
 
+### --keepnames
+Retain or keep inline reference and footnote names.
+This prevents the default behavior of replacing the names with numbers.
+Footnotes at the end of the markdown are **still sorted**.
+
+`fnsort.py path/to/doc.md --keepnames`
+
 ## Contributing
 For information about contributing to this project, see the [contributing guidelines](CONTRIBUTING.md).

fnsort.py

@@ -39,6 +39,12 @@ def parse_arguments():
         help="Fix adjacent footnotes by adding a space between them",
     )
 
+    parser.add_argument(
+        "--keepnames",
+        action="store_true",
+        help="Keep footnote names and do not replace with numeric ones",
+    )
+
     return parser.parse_args()
 
 
@@ -85,7 +91,7 @@ def space_adjacent_references(text):
     return text
 
 
-def sort_footnotes(text):
+def sort_footnotes(text, args):
     # removes the last newline from EOF so there is no EOL on the last line
     text = text.rstrip()
 
@@ -105,20 +111,29 @@ def sort_footnotes(text):
     # Make a list of the footnote-references in order of appearance the original footnotes in text.
     # this is not the order of the footnote contents, but the order of the footnote references in the text.
     try:
-        newlabels = [f"[^{i+1}]: {labels[j]}" for (i, j) in enumerate(order)]
+        if args.keepnames:
+            # Retain ref/footnote names (don't replace with numeric ones)
+            newlabels = [f"[^{i}]: {labels[i]}" for i in order]
+        else:
+            # Make a list of the footnote-references in order of appearance in the original footnotes in text.
+            # This is not the order of the footnote contents, but the order of the footnote references in the text.
+            newlabels = [f"[^{i+1}]: {labels[j]}" for (i, j) in enumerate(order)]
     except KeyError as e:
         # add custom exception to improve error output
         raise MissingFootnoteError(
             f"Missing footnote or inline reference = {repr(e)}"
         )
+
     # print(f"newlabels: {newlabels}")
 
     # Remove the old footnote-references and put the new ones at the end of the text.
+    # https://docs.python.org/3/library/re.html#re.Pattern.sub
     text = label.sub("", text).strip() + "\n" * 2 + "\n".join(newlabels)
     # print(f"text: {text}")
 
-    # Rewrite the footnote-links with the new footnote-reference numbers.
-    text = link.sub(lambda m: replace_reference(m, order), text)
+    if not args.keepnames:
+        # Rewrite the footnote-links with the new footnote-reference numbers.
+        text = link.sub(lambda m: replace_reference(m, order), text)
 
     return text
 
@@ -131,7 +146,7 @@ def main():
         if args.adjacent:
             text = space_adjacent_references(text)
 
-        processed_text = sort_footnotes(text)
+        processed_text = sort_footnotes(text, args)
         file.seek(0)
         file.write(processed_text)
         file.truncate()

tests/keep_fn_names/keep_fn_names.md

@@ -0,0 +1,52 @@
+# Brown Bears
+
+Brown bears [^brn_bear] are majestic mammals best seen at a distance!
+There are several sub-species [^brn_bear] across Asia, Europe, and North America. Unfortunately mankind has endangered or pushed some species to extinction due to fur trade or human encroachment.
+
+![Grizzly Bear Sow and her cubs](https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Grizzly_Bear-_Sow_and_cubs_%285728173840%29.jpg/320px-Grizzly_Bear-_Sow_and_cubs_%285728173840%29.jpg "Grizzly Bear Sow and her cubs")
+
+## Eurasian Brown Bear
+
+### Asia
+* East Siberian brown bear [^e_sib]
+* Gobi bear [^gobi]
+* Himalayan brown bear [^hima]
+* Kamchatkan brown bear [^kamch]
+* Syrian brown bear [^syr]
+* Tibetan brown bear [^tib]
+* Ussuri brown bear [^ussuri]
+
+### Europe
+* Cantabrian brown bear [^cant_bear]
+* Marsican brown bear [^mars_bear] - critically endangered
+
+## Grizzly Bear
+
+### North America
+* Californian grizzly bear[^cali] - extinct
+* Dall Island brown bear[^dall]
+* Kodiak bear [^kodiak]
+* Mexican grizzly bear[^mex] - extinct
+* Peninsular giant bear [^pgb]
+* Sitka brown bear[^sitka]
+* Stickeen brown bear[^stick]
+* Ungava brown bear[^ungava] - extinct
+
+[^kamch]:https://en.wikipedia.org/wiki/Kamchatka_brown_bear
+[^brn_bear]:https://en.wikipedia.org/wiki/Brown_bear
+[^tib]:https://en.wikipedia.org/wiki/Tibetan_blue_bear
+[^syr]:https://en.wikipedia.org/wiki/Syrian_brown_bear
+[^cant_bear]: https://en.wikipedia.org/wiki/Cantabrian_brown_bear
+[^e_sib]: https://en.wikipedia.org/wiki/East_Siberian_brown_bear
+[^hima]: https://en.wikipedia.org/wiki/Himalayan_brown_bear
+[^mars_bear]: https://en.wikipedia.org/wiki/Marsican_brown_bear
+[^gobi]: https://en.wikipedia.org/wiki/Gobi_bear
+[^ussuri]: https://en.wikipedia.org/wiki/Ussuri_brown_bear
+[^ungava]: https://en.wikipedia.org/wiki/Ungava_brown_bear
+[^stick]: https://en.wikipedia.org/wiki/Stickeen_brown_bear
+[^sitka]: https://en.wikipedia.org/wiki/ABC_Islands_bear
+[^pgb]: https://en.wikipedia.org/wiki/Alaska_Peninsula_brown_bear
+[^mex]: https://en.wikipedia.org/wiki/Mexican_grizzly_bear
+[^cali]: https://en.wikipedia.org/wiki/California_grizzly_bear
+[^kodiak]: https://en.wikipedia.org/wiki/Kodiak_bear
+[^dall]: https://en.wikipedia.org/wiki/Dall_Island

tests/keep_fn_names/keep_fn_names_expected.md

@@ -0,0 +1,52 @@
+# Brown Bears
+
+Brown bears [^brn_bear] are majestic mammals best seen at a distance!
+There are several sub-species [^brn_bear] across Asia, Europe, and North America. Unfortunately mankind has endangered or pushed some species to extinction due to fur trade or human encroachment.
+
+![Grizzly Bear Sow and her cubs](https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Grizzly_Bear-_Sow_and_cubs_%285728173840%29.jpg/320px-Grizzly_Bear-_Sow_and_cubs_%285728173840%29.jpg "Grizzly Bear Sow and her cubs")
+
+## Eurasian Brown Bear
+
+### Asia
+* East Siberian brown bear [^e_sib]
+* Gobi bear [^gobi]
+* Himalayan brown bear [^hima]
+* Kamchatkan brown bear [^kamch]
+* Syrian brown bear [^syr]
+* Tibetan brown bear [^tib]
+* Ussuri brown bear [^ussuri]
+
+### Europe
+* Cantabrian brown bear [^cant_bear]
+* Marsican brown bear [^mars_bear] - critically endangered
+
+## Grizzly Bear
+
+### North America
+* Californian grizzly bear[^cali] - extinct
+* Dall Island brown bear[^dall]
+* Kodiak bear [^kodiak]
+* Mexican grizzly bear[^mex] - extinct
+* Peninsular giant bear [^pgb]
+* Sitka brown bear[^sitka]
+* Stickeen brown bear[^stick]
+* Ungava brown bear[^ungava] - extinct
+
+[^brn_bear]: https://en.wikipedia.org/wiki/Brown_bear
+[^e_sib]: https://en.wikipedia.org/wiki/East_Siberian_brown_bear
+[^gobi]: https://en.wikipedia.org/wiki/Gobi_bear
+[^hima]: https://en.wikipedia.org/wiki/Himalayan_brown_bear
+[^kamch]: https://en.wikipedia.org/wiki/Kamchatka_brown_bear
+[^syr]: https://en.wikipedia.org/wiki/Syrian_brown_bear
+[^tib]: https://en.wikipedia.org/wiki/Tibetan_blue_bear
+[^ussuri]: https://en.wikipedia.org/wiki/Ussuri_brown_bear
+[^cant_bear]: https://en.wikipedia.org/wiki/Cantabrian_brown_bear
+[^mars_bear]: https://en.wikipedia.org/wiki/Marsican_brown_bear
+[^cali]: https://en.wikipedia.org/wiki/California_grizzly_bear
+[^dall]: https://en.wikipedia.org/wiki/Dall_Island
+[^kodiak]: https://en.wikipedia.org/wiki/Kodiak_bear
+[^mex]: https://en.wikipedia.org/wiki/Mexican_grizzly_bear
+[^pgb]: https://en.wikipedia.org/wiki/Alaska_Peninsula_brown_bear
+[^sitka]: https://en.wikipedia.org/wiki/ABC_Islands_bear
+[^stick]: https://en.wikipedia.org/wiki/Stickeen_brown_bear
+[^ungava]: https://en.wikipedia.org/wiki/Ungava_brown_bear

tests/test_footnote_sorting.py

@@ -24,7 +24,7 @@ def setUpClass(self):
             self.expected_text = fh.read()
 
         # technically there is also a "file" kwarg by default
-        args = {"adjacent": False}
+        args = {"adjacent": False, "keepnames": False}
         self.args = set_command_line_args(args)
         if self.args.adjacent:
             self.text = fnsort.space_adjacent_references(self.text)
@@ -50,7 +50,7 @@ def test_replace_reference(self):
 
     def test_footnote_sort(self):
         """ Entire footnote sort process """
-        self.assertEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+        self.assertEqual(fnsort.sort_footnotes(self.text, self.args), self.expected_text)
 
 
 class TestDuplicates(unittest.TestCase):
@@ -65,7 +65,7 @@ def setUpClass(self):
             self.expected_text = fh.read()
 
         # technically there is also a "file" kwarg by default
-        args = {"adjacent": False}
+        args = {"adjacent": False, "keepnames": False}
         self.args = set_command_line_args(args)
         if self.args.adjacent:
             self.text = fnsort.space_adjacent_references(self.text)
@@ -95,7 +95,7 @@ def test_replace_references_with_dups(self):
 
     def test_footnote_sort_with_dups(self):
         """ Entire footnote sort process with duplicate tags """
-        self.assertEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+        self.assertEqual(fnsort.sort_footnotes(self.text, self.args), self.expected_text)
 
 
 class TestFootnotesMustBeLast(unittest.TestCase):
@@ -110,7 +110,7 @@ def setUpClass(self):
             self.expected_text = fh.read()
 
         # technically there is also a "file" kwarg by default
-        args = {"adjacent": False}
+        args = {"adjacent": False, "keepnames": False}
         self.args = set_command_line_args(args)
         if self.args.adjacent:
             self.text = fnsort.space_adjacent_references(self.text)
@@ -130,7 +130,7 @@ def test_footnote_sort_trailing_text(self):
 
         in short this is not expected to return the desired output
         """
-        self.assertNotEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+        self.assertNotEqual(fnsort.sort_footnotes(self.text, self.args), self.expected_text)
 
 
 class TestAdjacentFootnotes(unittest.TestCase):
@@ -148,7 +148,7 @@ def setUpClass(self):
             self.expected_text = fh.read()
 
         # technically there is also a "file" kwarg by default
-        args = {"adjacent": True}
+        args = {"adjacent": True, "keepnames": False}
         self.args = set_command_line_args(args)
 
         # allow for full diff output
@@ -171,7 +171,34 @@ def test_adjacent_footnote_sort(self):
         if self.args.adjacent:
             self.text = fnsort.space_adjacent_references(self.text)
 
-        self.assertEqual(fnsort.sort_footnotes(self.text), self.expected_text)
+        self.assertEqual(fnsort.sort_footnotes(self.text, self.args), self.expected_text)
+
+
+class TestKeepFootnoteNames(unittest.TestCase):
+    @classmethod
+    def setUpClass(self):
+        path = "tests/keep_fn_names"
+
+        with open(f"{path}/keep_fn_names.md") as fh:
+            self.text = fh.read()
+
+        with open(f"{path}/keep_fn_names_expected.md") as fh:
+            self.expected_text = fh.read()
+
+        # technically there is also a "file" kwarg by default
+        args = {"adjacent": False, "keepnames": True}
+        self.args = set_command_line_args(args)
+
+        # allow for full diff output
+        # self.maxDiff = None
+
+
+    def test_keep_footnote_names(self):
+        """ Entire footnote sort process while retaining footnote names """
+        if self.args.adjacent:
+            self.text = fnsort.space_adjacent_references(self.text)
+
+        self.assertEqual(fnsort.sort_footnotes(self.text, self.args), self.expected_text)
 
 
 class TestMissingFootnotes(unittest.TestCase):
@@ -186,7 +213,7 @@ def setUpClass(self):
         #   sense in "expected" test file
 
         # technically there is also a "file" kwarg by default
-        args = {"adjacent": False}
+        args = {"adjacent": False, "keepnames": False}
         self.args = set_command_line_args(args)
 
         # allow for full diff output
@@ -201,7 +228,7 @@ def test_missing_footnotes(self):
             self.text = fnsort.space_adjacent_references(self.text)
 
         with self.assertRaises(fnsort.MissingFootnoteError):
-            fnsort.sort_footnotes(self.text)
+            fnsort.sort_footnotes(self.text, self.args)
 
 
 if __name__ == "__main__":