[seflue]

Closes #2520

manPrintFlags now writes the flag usage as a go-md2man definition list (: usage), which renders as .TP. gh uses the same form in its copy of the generator.

A definition list alone isn't enough, because go-md2man still reads the usage as Markdown. It turns a usage line starting with - , * , + or 1. into a list and indents all following flags by 2 instead of 7. A blank line in the usage ends the definition, and the next paragraph loses its indent. The fix escapes these markers at the start of each line and indents the following lines by four spaces.

The escaping also fixes an existing bug. Until now, a usage line starting with # turned into a section heading, and all following flags ended up under it.

TestGenManFlagsAsTaggedParagraphs covers these cases. TestManPrintFlagsHidesShortDeprecated now expects the definition list instead of the tab-indented line.

I built docker, hugo, restic, caddy and helm against this branch and generated their man pages. Every flag now renders as .TP. The text of the pages is unchanged, only the flag layout differs.

restic's restic-backup.1, before and after (MANWIDTH=80):

     --exclude-caches[=false]      excludes cache directories that  are  marked
     with  a  CACHEDIR.TAG file. See https://bford.info/cachedir/ for the Cache
     Directory Tagging Standard

     --exclude-caches[=false]
            excludes cache directories that  are  marked  with  a  CACHEDIR.TAG
            file. See https://bford.info/cachedir/ for the Cache Directory Tag‐
            ging Standard

[CLAassistant]

All committers have signed the CLA.