Man pages: refactor common options: arch

Smaller, more reviewable chunks.

This is just one option, --arch. Future PRs may, if the reviewing
is easy, include multiple options. This one includes fixes to
the preprocessor script, though:

 * big oops, I was not handling '<<something pod|something>>'
   where 'pod' appears other than the beginning of the string.
 * I was also not handling 'container<<| or pod>>', where one
   side was empty.
 * Behavior change: <<subcommand>>, on podman-pod-foo,
   becomes just 'foo' (not 'pod foo'). This will be useful
   in a future PR where we refactor --pod-id-file.

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

docs/source/markdown/options/README.md

@@ -42,3 +42,5 @@ This allows the shared use of examples in the option file:
 ```
     Example: podman <<subcommand>> --foo --bar
 ```
+As a special case, `podman-pod-X` becomes just `X` (the "pod" is removed).
+This makes the `pod-id-file` man page more useful.

docs/source/markdown/options/arch.md

@@ -0,0 +1,2 @@
+#### **--arch**=*ARCH*
+Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.

docs/source/markdown/podman-create.1.md.in

@@ -73,8 +73,7 @@ and specified with a _tag_.
 Add an annotation to the container. The format is key=value.
 The **--annotation** option can be set multiple times.
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--attach**, **-a**=*location*
 

docs/source/markdown/podman-pull.1.md.in

@@ -49,8 +49,7 @@ All tagged images in the repository will be pulled.
 
 *IMPORTANT: When using the all-tags flag, Podman will not iterate over the search registries in the **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** but will always use docker.io for unqualified image names.*
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--authfile**=*path*
 

docs/source/markdown/podman-run.1.md.in

@@ -90,8 +90,7 @@ and specified with a _tag_.
 Add an annotation to the container.
 This option can be set multiple times.
 
-#### **--arch**=*ARCH*
-Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
+@@option arch
 
 #### **--attach**, **-a**=*stdin* | *stdout* | *stderr*
 

hack/markdown-preprocess

@@ -68,6 +68,9 @@ def process(infile):
 
 # Given a file path of the form podman-foo-bar.1.md.in, return "foo bar"
 def podman_subcommand(string: str) -> str:
+    # Special case: 'podman-pod-start' becomes just 'start'
+    if string.startswith("podman-pod-"):
+        string = string[len("podman-pod-"):]
     if string.startswith("podman-"):
         string = string[len("podman-"):]
     if string.endswith(".1.md.in"):
@@ -89,8 +92,8 @@ def replace_type(line: str, type: str) -> str:
         # 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):
+        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':
@@ -98,14 +101,14 @@ def replace_type(line: str, type: str) -> str:
             else:
                 return rhs
         else:
-            if not re.match('pod([^m]|$)', rhs, re.IGNORECASE):
+            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)
+    return re.sub('<<[^\|>]*\|[^\|>]*>>', replwith, line)
 
 if __name__ == "__main__":
     main()

hack/markdown-preprocess.t

@@ -37,6 +37,24 @@ class TestPodReplacer(unittest.TestCase):
         """we ignore 'podman'"""
         self.assertEqual(mp.replace_type('<<podman container|pod in podman>>', 'container'), 'podman container')
 
+    def test_not_at_beginning(self):
+        """oops - test for 'pod' other than at beginning of string"""
+        s = '<<container|container or pod>>'
+        self.assertEqual(mp.replace_type(s, 'container'), 'container')
+        self.assertEqual(mp.replace_type(s, 'pod'), 'container or pod')
+        s = '<<container or pod|container>>'
+        self.assertEqual(mp.replace_type(s, 'container'), 'container')
+        self.assertEqual(mp.replace_type(s, 'pod'), 'container or pod')
+
+    def test_blank(self):
+        """test that either side of '|' can be empty"""
+        s = 'abc container<<| or pod>> def'
+        self.assertEqual(mp.replace_type(s, 'container'), 'abc container def')
+        self.assertEqual(mp.replace_type(s, 'pod'), 'abc container or pod def')
+        s = 'abc container<< or pod|>> def'
+        self.assertEqual(mp.replace_type(s, 'container'), 'abc container def')
+        self.assertEqual(mp.replace_type(s, 'pod'), 'abc container or pod def')
+
     def test_exception_both(self):
         """test that 'pod' on both sides raises exception"""
         with self.assertRaisesRegex(Exception, "in both left and right sides"):
@@ -52,6 +70,7 @@ class TestPodmanSubcommand(unittest.TestCase):
         """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")
+        self.assertEqual(mp.podman_subcommand("podman-pod-rm.1.md.in"), "rm")
 
 
 if __name__ == '__main__':