Produces bad whatis entries

[siretart]

This is being forwarded from https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=926824

Given a .md file that may start like this:

## containers-storage-add-names "August 2016"

## NAME
containers-storage add-names - Add names to a layer/image/container
[...]

The tool go-md2man should escape the - to an \-, so that tools such as lexgrog can produce good whatis entries. In Debian, we have a tool can lintian that reports this as a warning, and comes with the following (IMO well written) explanation of the issue:

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

[cpuguy83]

Been looking at this a bit today. Unfortunately its not entirely clear what is valid here.
I noticed that lintian still complains even if I fix the \-... I think it may be due to .PP after .SH NAMES
lexgrog doesn't seem to have a problem reading the values.

[cpuguy83]

In any case I think .SH followed by .PP is not particularly valid or at least not necessary... and may be the (partial) cause of #47 as well.