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, 43 insertions, 17 deletions

diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess
index 4bc67a819..0b66abb06 100755
--- a/hack/markdown-preprocess
+++ b/hack/markdown-preprocess
@@ -5,6 +5,7 @@
 
 import glob
 import os
+import re
 import sys
 
 def main():
@@ -32,7 +33,7 @@ def process(infile):
         pod_or_container = 'pod'
 
     # Sometimes a man page includes the subcommand.
-    subcommand = removesuffix(removeprefix(infile,"podman-"),".1.md.in").replace("-", " ")
+    subcommand = podman_subcommand(infile)
 
     # foo.md.in -> foo.md -- but always write to a tmpfile
     outfile = os.path.splitext(infile)[0]
@@ -55,8 +56,8 @@ def process(infile):
                 fh_out.write("\n[//]: # (BEGIN included file " + optionfile + ")\n")
                 with open(optionfile, 'r') as fh_optfile:
                     for opt_line in fh_optfile:
-                        opt_line = opt_line.replace('<POD-OR-CONTAINER>', pod_or_container)
-                        opt_line = opt_line.replace('<SUBCOMMAND>', subcommand)
+                        opt_line = replace_type(opt_line, pod_or_container)
+                        opt_line = opt_line.replace('<<subcommand>>', subcommand)
                         fh_out.write(opt_line)
                 fh_out.write("\n[//]: # (END   included file " + optionfile + ")\n")
             else:
@@ -65,21 +66,46 @@ def process(infile):
     os.chmod(outfile_tmp, 0o444)
     os.rename(outfile_tmp, outfile)
 
-# str.removeprefix() is python 3.9+, we need to support older versions on mac
-def removeprefix(string: str, prefix: str) -> str:
-    if string.startswith(prefix):
-        return string[len(prefix):]
-    else:
-        return string[:]
-
-# str.removesuffix() is python 3.9+, we need to support older versions on mac
-def removesuffix(string: str, suffix: str) -> str:
-    # suffix='' should not call self[:-0].
-    if suffix and string.endswith(suffix):
-        return string[:-len(suffix)]
-    else:
-        return string[:]
+# Given a file path of the form podman-foo-bar.1.md.in, return "foo bar"
+def podman_subcommand(string: str) -> str:
+    if string.startswith("podman-"):
+        string = string[len("podman-"):]
+    if string.endswith(".1.md.in"):
+        string = string[:-len(".1.md.in")]
+    return string.replace("-", " ")
 
+# Replace instances of '<<pod|container>>' with the desired one (based on
+# 'type' which is 'pod' or 'container').
+def replace_type(line: str, type: str) -> str:
+    # Internal helper function: determines the desired half of the <a|b> string
+    def replwith(matchobj):
+        lhs, rhs = matchobj[0].split('|')
+        # Strip off '<<' and '>>'
+        lhs = lhs[2:]
+        rhs = rhs[:len(rhs)-2]
+
+        # Check both sides for 'pod' followed by (non-"m" or end-of-string).
+        # The non-m prevents us from triggering on 'podman', which could
+        # conceivably be present in both sides. And we check for 'pod',
+        # not 'container', because it's possible to have something like
+        # <<container in pod|container>>.
+        if re.match('pod([^m]|$)', lhs, re.IGNORECASE):
+            if re.match('pod([^m]|$)', rhs, re.IGNORECASE):
+                raise Exception("'%s' matches 'pod' in both left and right sides" % matchobj[0])
+            # Only left-hand side has "pod"
+            if type == 'pod':
+                return lhs
+            else:
+                return rhs
+        else:
+            if not re.match('pod([^m]|$)', rhs, re.IGNORECASE):
+                raise Exception("'%s' does not match 'pod' in either side" % matchobj[0])
+            if type == 'pod':
+                return rhs
+            else:
+                return lhs
+
+    return re.sub('<<[^\|>]+\|[^\|>]+>>', replwith, line)
 
 if __name__ == "__main__":
     main()