Backslash-escape first hyphen in NAME section

This is the required format for man-page parsers across the ecosystem to
successfuly parse out whatis information.

Signed-off-by: Cory Snider <csnider@mirantis.com>

md2man/roff.go

@@ -103,7 +103,23 @@ func (r *roffRenderer) RenderNode(w io.Writer, node *blackfriday.Node, entering
 
 	switch node.Type {
 	case blackfriday.Text:
-		escapeSpecialChars(w, node.Literal)
+		// Special case: format the NAME section as required for proper whatis parsing.
+		// Refer to the lexgrog(1) and groff_man(7) manual pages for details.
+		if node.Parent != nil &&
+			node.Parent.Type == blackfriday.Paragraph &&
+			node.Parent.Prev != nil &&
+			node.Parent.Prev.Type == blackfriday.Heading &&
+			node.Parent.Prev.FirstChild != nil &&
+			bytes.EqualFold(node.Parent.Prev.FirstChild.Literal, []byte("NAME")) {
+			before, after, found := bytes.Cut(node.Literal, []byte(" - "))
+			escapeSpecialChars(w, before)
+			if found {
+				out(w, ` \- `)
+				escapeSpecialChars(w, after)
+			}
+		} else {
+			escapeSpecialChars(w, node.Literal)
+		}
 	case blackfriday.Softbreak:
 		out(w, crTag)
 	case blackfriday.Hardbreak:

md2man/roff_test.go

@@ -424,7 +424,13 @@ func TestComments(t *testing.T) {
 func TestHeadings(t *testing.T) {
 	tests := []string{
 		"# title\n\n# NAME\ncommand - description\n\n# SYNOPSIS\nA short description\n\nWhich spans multiple paragraphs\n",
-		".nh\n.TH title\n\n.SH NAME\ncommand - description\n\n\n.SH SYNOPSIS\nA short description\n\n.PP\nWhich spans multiple paragraphs\n",
+		".nh\n.TH title\n\n.SH NAME\ncommand \\- description\n\n\n.SH SYNOPSIS\nA short description\n\n.PP\nWhich spans multiple paragraphs\n",
+
+		"# title\n\n# Name\nmy-command, other - description - with - hyphens\n",
+		".nh\n.TH title\n\n.SH Name\nmy-command, other \\- description - with - hyphens\n",
+
+		"# title\n\n# Not NAME\nsome - other - text\n",
+		".nh\n.TH title\n\n.SH Not NAME\nsome - other - text\n",
 	}
 	doTestsInline(t, tests)
 }