Man pages: fix broken tables

[edsantiago]

Work around a go-md2man bug, and add a check script to make sure
this doesn't hit us again.

Background: go-md2man can't deal with a left-hand column > 31 chars.
It produces man pages that look like:

| Something With >31 Character |                |
|                              | ..description  |

(should be all on one row). It also has trouble when the vertical
bars are misaligned: it completely removes the right-hand side.

There's almost certainly a better solution: fix go-md2man, or
use a different conversion tool, or maybe even pre/postprocess.
But this is a quick interim solution.

Sorry for the perl. This could be done in bash/sed/awk/grep,
but not with any sort of sane error messages.

Signed-off-by: Ed Santiago [email protected]

Fix broken tables in man pages

[edsantiago]

This is what the script output looks like on main right now:

man-page-table-check: docs/build/man/podman-events.1:
          |podman-inspect as described above |                                |

man-page-table-check: docs/build/man/podman-images.1:
          |digest       |                            |

man-page-table-check: docs/build/man/podman-network-ls.1:
          |regex).  |                            |

man-page-table-check: docs/build/man/podman-pod-create.1:
          |kube play.  |                            |

man-page-table-check: docs/build/man/podman-save.1:
          |docker load(1) (the default)                      |                            |
          |docker-dir                                        |                            |
          |dir transport (see                                |                            |
          |containers-transports(5)) with v2s2 manifest type |                            |

man-page-table-check: docs/build/man/podman-system-connection-list.1:
          |host[:port]                               |                            |
          |Unix domain socket[?secure=True], unix:// |                            |
          |Unix domain socket, and tcp://localhost[: |                            |
          |port]                                     |                            |

man-page-table-check: docs/build/man/podman-systemd.unit.5:
          |HealthStartupCmd="/usr/bin/command"                                 |                                                               |
          |                                                                    | --health-startup-cmd="/usr/bin/command"                       |
          |Mount=type=bind,source=/path/on/host,destination=/path/in/container |                                                               |
          |                                                                    | --mount                                                       |
          |PodmanArgs=--annotation=key=value |                              |
          |                                  | --annotation=key=value       |

man-page-table-check: found empty cells in the above man page(s)

This is a bug in go-md2man: it gets really confused when it sees
markdown characters inside tables, and splits those into multiple
rows, and yields unreadable man pages.

WORKAROUND: find the above line(s) in the docs/source/markdown
file, look for '*' or '-' or '<' or '`' (backtick), and remove them.
Look for '.' (dot), and backslash-escape them. Keep regenerating
docs until it passes:

    $ make -C docs clean;make docs

[vrothberg]

LGTM

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: edsantiago, vrothberg

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [edsantiago,vrothberg]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Luap99]

Is this bug reported somewhere? I think it would make sense to fix it in go-md2man.

[edsantiago]

I don't know if it's a known bug; it's on my low-priority TODO list to check and report it.

[edsantiago]

Drafting again, to let #18671 go first

[rhatdan]

LGTM. It would be nice to fix md2man, but for now this is good.

Update the PR and we can get this in.

[edsantiago]

Update: go-md2man-2.02 fixes some, but not all, of the issues in my first push; so I've reduced the scope of my PR and amended the commit message accordingly. I genuinely don't understand some of the bugs (the "digest" one, and why backslashing dashes can in some cases allow a >31-character LHS).

[TomSweeneyRedHat]

LGTM

[TomSweeneyRedHat]

/lgtm