Refactor common options in man pages

podman-create and -run have many options in common. To date,
these are copy-pasted and haphazardly maintained.

Solution: add an include mechanism, '@@option foo', such
that multiple md source files can fetch from one common file.

This is a Phase One commit, a very small subset of what's
possible. Purpose of this commit is ease of review. If this
passes review, much more (trickier stuff) will be forthcoming.

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

1 files changed, 68 insertions, 0 deletions

diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess
new file mode 100755
index 000000000..ec641b6b8
--- /dev/null
+++ b/hack/markdown-preprocess
@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+#
+# markdown-preprocess - filter *.md.in files, convert to .md
+#
+
+import glob
+import os
+import sys
+
+def main():
+    try:
+        os.chdir("docs/source/markdown")
+    except FileNotFoundError:
+        raise Exception("Please invoke me from the base repo dir")
+
+    # If called with args, process only those files
+    infiles = [ os.path.basename(x) for x in sys.argv[1:] ]
+    if len(infiles) == 0:
+        # Called without args: process all *.md.in files
+        infiles = glob.glob('*.md.in')
+    for infile in infiles:
+        process(infile)
+
+def process(infile):
+    # Some options are the same between containers and pods; determine
+    # which description to use from the name of the source man page.
+    pod_or_container = 'container'
+    if '-pod-' in infile:
+        pod_or_container = 'pod'
+
+    # Sometimes a man page includes the subcommand.
+    subcommand = infile.removeprefix("podman-").removesuffix(".1.md.in").replace("-", " ")
+
+    # foo.md.in -> foo.md -- but always write to a tmpfile
+    outfile = os.path.splitext(infile)[0]
+    outfile_tmp = outfile + '.tmp.' + str(os.getpid())
+
+#    print("got here: ",infile, " -> ", outfile)
+
+    with open(infile, 'r') as fh_in, open(outfile_tmp, 'w') as fh_out:
+        for line in fh_in:
+            # '@@option foo' -> include file options/foo.md
+            if line.startswith('@@option '):
+                _, optionname = line.strip().split(" ")
+                optionfile = os.path.join("options", optionname + '.md')
+                fh_out.write("[//]: # (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)
+                        fh_out.write(opt_line)
+
+                    # Weird special case: options/image-volume.md ends in a
+                    # list, and in markdown lists are continued across lines,
+                    # so without an intervening blank line the '[//]' comment
+                    # becomes part of the final list entry.
+                    if opt_line.startswith('-'):
+                        fh_out.write("\n")
+
+                fh_out.write("[//]: # (END   included file " + optionfile + ")\n")
+            else:
+                fh_out.write(line)
+
+    os.chmod(outfile_tmp, 0o444)
+    os.rename(outfile_tmp, outfile)
+
+if __name__ == "__main__":
+    main()