[pkg-go] Bug#926824: go-md2man: Produced manpages contain many warnings "manpage-has-bad-whatis-entry" lintian warnings

[Reinhard Tartler]

Source: go-md2man
Severity: normal

I'm using this tool in the golang-github-containers-storage. At the end
of the package build, I see lots of warnings like this:

,----
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-mounted.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-set-container-data.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-set-image-data.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-set-metadata.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-set-names.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-shutdown.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-status.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-unmount.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-version.1.gz
| W: containers-storage: manpage-has-bad-whatis-entry usr/share/man/man1/containers-storage-wipe.1.gz
`----


The description of the lintian warning reads:

,----[ lintian-info -t manpage-has-bad-whatis-entry
| W: manpage-has-bad-whatis-entry
| N:
| N:   Each manual page should start with a "NAME" section, which lists the
| N:   name and a brief description of the page separated by "\-". The "NAME"
| N:   section is parsed by lexgrog and used to generate a database that's
| N:   queried by commands like apropos and whatis. This tag indicates that
| N:   lexgrog was unable to parse the NAME section of this manual page.
| N:   
| N:   For manual pages that document multiple programs, functions, files, or
| N:   other things, the part before "\-" should list each separated by a
| N:   comma and a space. Each thing listed must not contain spaces; a man
| N:   page for a two-part command like "fs listacl" must use something like
| N:   "fs_listacl" in the "NAME" section so that it can be parsed by
| N:   lexgrog.
| N:   
| N:   Refer to the lexgrog(1) manual page, the groff_man(7) manual page, and
| N:   the groff_mdoc(7) manual page for details.
| N:   
| N:   Severity: normal, Certainty: certain
| N:   
| N:   Check: manpages, Type: binary
| N:
`----

The .md files have headers that look like this:

,----
| ## containers-storage-add-names "August 2016"
| 
| ## NAME
| containers-storage add-names - Add names to a layer/image/container
| [...]
`----

AFAIUI the generated manpage should produce '\-' instead of '-' to have a functional
whatis database and unbreak lexgrog.

Best,
-rt

-- System Information:
Debian Release: buster/sid
  APT prefers testing
  APT policy: (500, 'testing'), (50, 'unstable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-4-amd64 (SMP w/4 CPU cores)
Kernel taint flags: TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled