Refactor common man page options, phase 2

Followup to #15174. These are the options that are easy(ish)
to review: those that have only drifted slightly, and need
only minor tweaks to bring back to sanity. For the most part,
I went with the text in podman-run because that was cleaned up
in #5192 way back in 2020. These diffs primarily consist of
using '**' (star star) instead of backticks, plus other
formatting and punctuation changes.

This PR also adds a README in the options dir, and a new
convention: <<container text...|pod text...>> which tries
to do the right thing based on whether the man page name
includes "-pod-" or not. Since that's kind of hairy code,
I've also added a test suite for it.

Finally, since this is impossible to review by normal means,
I'm temporarily committing hack/markdown-preprocess-review,
a script that will diff option-by-option. I will remove it
once we finish this cleanup, but be advised that there are
still 130+ options left to examine, and some of those are
going to be really hard to reunite.

Review script usage: simply run it (you need to have 'diffuse'
installed). It isn't exactly obvious, but it shouldn't take more
than a minute to figure out. The rightmost column (zzz-chosen.md)
is the "winner", the actual content that will be used henceforth.
You really want an ultrawide screen here.

Signed-off-by: Ed Santiago <santiago@redhat.com>

1 files changed, 58 insertions, 0 deletions

diff --git a/hack/markdown-preprocess.t b/hack/markdown-preprocess.t
new file mode 100755
index 000000000..a6fe793b1
--- /dev/null
+++ b/hack/markdown-preprocess.t
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+
+"""
+Tests for markdown-preprocess
+"""
+
+import unittest
+
+# https://stackoverflow.com/questions/66665217/how-to-import-a-python-script-without-a-py-extension
+from importlib.util import spec_from_loader, module_from_spec
+from importlib.machinery import SourceFileLoader
+
+spec = spec_from_loader("mp", SourceFileLoader("mp", "hack/markdown-preprocess"))
+mp = module_from_spec(spec)
+spec.loader.exec_module(mp)
+
+class TestPodReplacer(unittest.TestCase):
+    def test_basic(self):
+        """basic pod|container and vice-versa"""
+        s = '<<container|pod>>'
+        self.assertEqual(mp.replace_type(s, 'pod'), 'pod')
+        self.assertEqual(mp.replace_type(s, 'container'), 'container')
+        s = '<<container|pod>>'
+        self.assertEqual(mp.replace_type(s, 'pod'), 'pod')
+        self.assertEqual(mp.replace_type(s, 'container'), 'container')
+
+    def test_case_insensitive(self):
+        """test case-insensitive replacement of Pod, Container"""
+        s = '<<Pod|Container>>'
+        self.assertEqual(mp.replace_type(s, 'pod'), 'Pod')
+        self.assertEqual(mp.replace_type(s, 'container'), 'Container')
+        s = '<<Container|Pod>>'
+        self.assertEqual(mp.replace_type(s, 'pod'), 'Pod')
+        self.assertEqual(mp.replace_type(s, 'container'), 'Container')
+
+    def test_dont_care_about_podman(self):
+        """we ignore 'podman'"""
+        self.assertEqual(mp.replace_type('<<podman container|pod in podman>>', 'container'), 'podman container')
+
+    def test_exception_both(self):
+        """test that 'pod' on both sides raises exception"""
+        with self.assertRaisesRegex(Exception, "in both left and right sides"):
+            mp.replace_type('<<pod 123|pod 321>>', 'pod')
+
+    def test_exception_neither(self):
+        """test that 'pod' on neither side raises exception"""
+        with self.assertRaisesRegex(Exception, "in either side"):
+            mp.replace_type('<<container 123|container 321>>', 'pod')
+
+class TestPodmanSubcommand(unittest.TestCase):
+    def test_basic(self):
+        """podman subcommand basic test"""
+        self.assertEqual(mp.podman_subcommand("podman-foo.1.md.in"), "foo")
+        self.assertEqual(mp.podman_subcommand("podman-foo-bar.1.md.in"), "foo bar")
+
+
+if __name__ == '__main__':
+    unittest.main()