From cc0bcea4eafd355e49a2ea3f2470a647bdc9206c Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 29 Mar 2021 12:56:22 -0600 Subject: manpage xref: helpful diagnostic for unescaped dash-dash PR #9856 works around a buggy markdown processor that cleverly converts double dashes to em-dash. The unfortunate result is that the man page source files are unmaintainable, because every '--foo' has to be specified as '\-\-foo'. This is impossible for humans to remember, so let's add a helpful diagnostic message when we detect new options added without the escapes. Signed-off-by: Ed Santiago --- hack/xref-helpmsgs-manpages | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages index 42dd3634f..25e972fbc 100755 --- a/hack/xref-helpmsgs-manpages +++ b/hack/xref-helpmsgs-manpages @@ -331,6 +331,15 @@ sub podman_man { @most_recent_flags = (); # As of PR #8292, all options are

and anchored if ($line =~ s/^\#{4}\s+//) { + # 2021-03: PR #9856: some (bleep) markdown processor converts + # double dashes to a single em-dash. We need to escape every + # instance with backslashes. This is anti-intuitive, and + # developers will naturally write --foo; try to catch that + # and warn with a helpful message. + if ($line =~ /--([a-z]+)/) { + warn "$ME: $subpath:$.: You probably need to backslash-escape '--$1' as '\\-\\-$1'\n"; + } + # If option has long and short form, long must come first. # This is a while-loop because there may be multiple long # option names, e.g. --net/--network -- cgit v1.2.3-54-g00ecf