fix: escape angle brackets in man page generation

Angle brackets in command usage, descriptions, and flag help text were
being stripped during man page generation because md2man interprets
them as HTML tags. This fix escapes < and > characters with backslashes
so they are preserved in the rendered man page output.

Fixes #2330

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: majiayu000 <1835304752@qq.com>

Author: majiayu000

doc/man_docs.go

@@ -140,6 +140,14 @@ func fillHeader(header *GenManHeader, name string, disableAutoGen bool) error {
 	return nil
 }
 
+// escapeAngleBrackets escapes < and > characters to prevent md2man from
+// interpreting them as HTML tags. See https://github.com/spf13/cobra/issues/2330
+func escapeAngleBrackets(s string) string {
+	s = strings.ReplaceAll(s, "<", `\<`)
+	s = strings.ReplaceAll(s, ">", `\>`)
+	return s
+}
+
 func manPreamble(buf io.StringWriter, header *GenManHeader, cmd *cobra.Command, dashedName string) {
 	description := cmd.Long
 	if len(description) == 0 {
@@ -149,11 +157,11 @@ func manPreamble(buf io.StringWriter, header *GenManHeader, cmd *cobra.Command,
 	cobra.WriteStringAndCheck(buf, fmt.Sprintf(`%% "%s" "%s" "%s" "%s" "%s"
 # NAME
 `, header.Title, header.Section, header.date, header.Source, header.Manual))
-	cobra.WriteStringAndCheck(buf, fmt.Sprintf("%s \\- %s\n\n", dashedName, cmd.Short))
+	cobra.WriteStringAndCheck(buf, fmt.Sprintf("%s \\- %s\n\n", dashedName, escapeAngleBrackets(cmd.Short)))
 	cobra.WriteStringAndCheck(buf, "# SYNOPSIS\n")
-	cobra.WriteStringAndCheck(buf, fmt.Sprintf("**%s**\n\n", cmd.UseLine()))
+	cobra.WriteStringAndCheck(buf, fmt.Sprintf("**%s**\n\n", escapeAngleBrackets(cmd.UseLine())))
 	cobra.WriteStringAndCheck(buf, "# DESCRIPTION\n")
-	cobra.WriteStringAndCheck(buf, description+"\n\n")
+	cobra.WriteStringAndCheck(buf, escapeAngleBrackets(description)+"\n\n")
 }
 
 func manPrintFlags(buf io.StringWriter, flags *pflag.FlagSet) {
@@ -180,7 +188,7 @@ func manPrintFlags(buf io.StringWriter, flags *pflag.FlagSet) {
 			format += "]"
 		}
 		format += "\n\t%s\n\n"
-		cobra.WriteStringAndCheck(buf, fmt.Sprintf(format, flag.DefValue, flag.Usage))
+		cobra.WriteStringAndCheck(buf, fmt.Sprintf(format, flag.DefValue, escapeAngleBrackets(flag.Usage)))
 	})
 }
 

doc/man_docs_test.go

@@ -214,6 +214,31 @@ func assertNextLineEquals(scanner *bufio.Scanner, expectedLine string) error {
 	return fmt.Errorf("hit EOF before finding %v", expectedLine)
 }
 
+func TestGenManAngleBrackets(t *testing.T) {
+	// Test that angle brackets are preserved in man page output.
+	// See https://github.com/spf13/cobra/issues/2330
+	cmd := &cobra.Command{
+		Use:   "cmd [<remote>:]<instance>",
+		Short: "A command with <angle> brackets",
+		Long:  "This is a longer description with <placeholder> values.",
+		Run:   emptyRun,
+	}
+	cmd.Flags().StringP("config", "c", "", "Path to <config> file")
+
+	buf := new(bytes.Buffer)
+	if err := GenMan(cmd, nil, buf); err != nil {
+		t.Fatal(err)
+	}
+	output := buf.String()
+
+	// Verify angle brackets are preserved in the rendered man page
+	checkStringContains(t, output, "<remote>")
+	checkStringContains(t, output, "<instance>")
+	checkStringContains(t, output, "<angle>")
+	checkStringContains(t, output, "<placeholder>")
+	checkStringContains(t, output, "<config>")
+}
+
 func BenchmarkGenManToFile(b *testing.B) {
 	file, err := os.CreateTemp("", "")
 	if err != nil {