Skip to content

fix: Angle brackets stripped from manpage output #2341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
majiayu000 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: Angle brackets stripped from manpage output #2341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions doc/man_docs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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) {
Expand All @@ -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)))
})
}

Expand Down
25 changes: 25 additions & 0 deletions doc/man_docs_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down