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, 132 insertions, 0 deletions

diff --git a/hack/markdown-preprocess-review b/hack/markdown-preprocess-review
new file mode 100755
index 000000000..e8b042e94
--- /dev/null
+++ b/hack/markdown-preprocess-review
@@ -0,0 +1,132 @@
+#!/usr/bin/perl
+
+(our $ME = $0) =~ s|^.*/||;
+
+use v5.20;
+
+our $DSM = 'docs/source/markdown';
+
+my ($oldname, $newname);
+my %oldname;
+my %changed;
+open my $git_diff, '-|', 'git', 'log', '-1', '-p'
+    or die "$ME: Cannot fork: $!\n";
+while (my $line = <$git_diff>) {
+    chomp $line;
+
+    if ($line =~ m!^\-\-\-\s+a/$DSM/(podman-\S+\.md(\.in)?)!) {
+        $oldname = $1;
+        $newname = undef;
+    }
+    elsif ($line =~ m!^\+\+\+\s+b/$DSM/(podman-\S+\.md(\.in)?)!) {
+        $newname = $1;
+        $oldname{$newname} = $oldname;
+    }
+    elsif ($newname) {
+        if ($line =~ s/^-####\s+//) {
+            $line =~ /^\*\*--(\S+?)\*\*/
+                or die "$ME: in $newname: weird '$line'";
+            $changed{$newname}{$1}{name} = $1;
+        }
+        # Usually the same, but not for host.container and host.pod.md
+        elsif ($line =~ /^\+\@\@option\s+(\S+)/) {
+            my $optfile = $1;
+            if ($optfile =~ /^(.*)\.\S+$/) {
+                $changed{$newname}{$1}{name} = $optfile;
+            }
+        }
+    }
+}
+close $git_diff;
+
+# Pass 2: read each oldfile, parse changed options
+for my $f (sort keys %changed) {
+    my $oldfile = $oldname{$f};
+    open my $git_fh, '-|', 'git', 'show', "HEAD^:$DSM/$oldfile"
+        or die "$ME: Cannot fork: $!\n";
+    my $opt;
+    while (my $line = <$git_fh>) {
+        if ($line =~ /^####\s+\*\*--(\S+?)\*\*/) {
+            $opt = $1;
+            if ($changed{$f}{$opt}) {
+                $changed{$f}{$opt}{text} = $line;
+            }
+            else {
+                undef $opt;
+            }
+        }
+        elsif ($line =~ /^#/ || $line =~ /^\@\@option\s/) {
+            undef $opt;
+        }
+        elsif ($opt) {
+            $changed{$f}{$opt}{text} .= $line;
+        }
+    }
+    close $git_fh
+        or die "$ME: Error running git on $oldfile\n";
+}
+
+# Pass 3: write out files
+my $tempdir = "/tmp/$ME.diffs";
+system('rm', '-rf', $tempdir);
+mkdir $tempdir, 0755;
+
+for my $md_file (sort keys %changed) {
+    for my $opt (sort keys %{$changed{$md_file}}) {
+        my $d = "$tempdir/$changed{$md_file}{$opt}{name}";
+        mkdir $d, 0755;
+
+        my $outfile = "$d/$md_file";
+        open my $fh, '>', $outfile
+            or die "$ME: Cannot create $outfile: $!\n";
+        # strip all trailing newlines
+        (my $text = $changed{$md_file}{$opt}{text}) =~ s/\n+$/\n/s;
+        print { $fh } $text;
+        close $fh
+            or die "$ME: Error writing $outfile: $!\n";
+
+        my $new_text = "$DSM/options/$changed{$md_file}{$opt}{name}.md";
+        die "$ME: File does not exist: $new_text\n" if ! -e $new_text;
+        system('cp', $new_text, "$d/zzz-chosen.md");
+    }
+}
+
+# Now run diffuse
+chdir $tempdir or die;
+my @all_opts = glob("*");
+for my $i (0..$#all_opts) {
+    my $opt = $all_opts[$i];
+    chdir "$tempdir/$opt"
+        or die "??? Internal error, cannot cd $tempdir/$opt: $!";
+
+    $| = 1; printf "--%s (%d/%d) ", $opt, $i+1, scalar(@all_opts);
+
+    my @all_files = glob("*");
+    if (all_files_identical(@all_files)) {
+        pop @all_files;
+        print "[identical between @all_files]\n";
+        next;
+    }
+
+    # Prompt
+    print "[Y/n/q] ";
+    my $ans = <STDIN>;
+    next if $ans =~ /^n/i;
+    exit 0 if $ans =~ /^q/i;
+
+    system("diffuse", "-w", glob("*")) == 0
+        or die "Diffuse failed\n";
+}
+
+
+sub all_files_identical {
+    my %sha;
+    for my $f (@_) {
+        my $result = qx{sha256sum $f};
+        $result =~ /^([0-9a-f]+)\s/
+            or die "Internal error: unexpected result from sha256sum $f: $result";
+        $sha{$1}++;
+    }
+
+    return (keys(%sha) == 1);
+}