go.mod

@@ -7,13 +7,13 @@ require (
 	github.com/pkg/sftp v1.13.6
 	github.com/rs/zerolog v1.33.0
 	github.com/stretchr/testify v1.9.0
-	github.com/urfave/cli/v2 v2.27.4
+	github.com/urfave/cli/v2 v2.27.7
 	golang.org/x/crypto v0.27.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
-	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/jmespath/go-jmespath v0.4.0 // indirect
 	github.com/kr/fs v0.1.0 // indirect

go.sum

@@ -7,6 +7,8 @@ github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHH
 github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
+github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -46,6 +48,8 @@ github.com/urfave/cli/v2 v2.25.7 h1:VAzn5oq403l5pHjc4OhD54+XGO9cdKVL/7lDjF+iKUs=
 github.com/urfave/cli/v2 v2.25.7/go.mod h1:8qnjx1vcq5s2/wpsqoZFndg2CE5tNFyrTvS6SinrnYQ=
 github.com/urfave/cli/v2 v2.27.4 h1:o1owoI+02Eb+K107p27wEX9Bb8eqIoZCfLXloLUSWJ8=
 github.com/urfave/cli/v2 v2.27.4/go.mod h1:m4QzxcD2qpra4z7WhzEGn74WZLViBnMpb1ToCAKdGRQ=
+github.com/urfave/cli/v2 v2.27.7 h1:bH59vdhbjLv3LAvIu6gd0usJHgoTTPhCFib8qqOwXYU=
+github.com/urfave/cli/v2 v2.27.7/go.mod h1:CyNAG/xg+iAOg0N4MPGZqVmv2rCoP267496AOXUZjA4=
 github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673 h1:bAn7/zixMGCfxrRTfdpNzjtPYqr8smhKouy9mxVdGPU=
 github.com/xrash/smetrics v0.0.0-20201216005158-039620a65673/go.mod h1:N3UwUGtsrSj3ccvlPHLoLsHnpR27oXr4ZE984MbSER8=
 github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGCjxCBTO/36wtF6j2nSip77qHd4x4=

vendor/github.com/cpuguy83/go-md2man/v2/md2man/debug.go

@@ -0,0 +1,62 @@
+package md2man
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/russross/blackfriday/v2"
+)
+
+func fmtListFlags(flags blackfriday.ListType) string {
+	knownFlags := []struct {
+		name string
+		flag blackfriday.ListType
+	}{
+		{"ListTypeOrdered", blackfriday.ListTypeOrdered},
+		{"ListTypeDefinition", blackfriday.ListTypeDefinition},
+		{"ListTypeTerm", blackfriday.ListTypeTerm},
+		{"ListItemContainsBlock", blackfriday.ListItemContainsBlock},
+		{"ListItemBeginningOfList", blackfriday.ListItemBeginningOfList},
+		{"ListItemEndOfList", blackfriday.ListItemEndOfList},
+	}
+
+	var f []string
+	for _, kf := range knownFlags {
+		if flags&kf.flag != 0 {
+			f = append(f, kf.name)
+			flags &^= kf.flag
+		}
+	}
+	if flags != 0 {
+		f = append(f, fmt.Sprintf("Unknown(%#x)", flags))
+	}
+	return strings.Join(f, "|")
+}
+
+type debugDecorator struct {
+	blackfriday.Renderer
+}
+
+func depth(node *blackfriday.Node) int {
+	d := 0
+	for n := node.Parent; n != nil; n = n.Parent {
+		d++
+	}
+	return d
+}
+
+func (d *debugDecorator) RenderNode(w io.Writer, node *blackfriday.Node, entering bool) blackfriday.WalkStatus {
+	fmt.Fprintf(os.Stderr, "%s%s %v %v\n",
+		strings.Repeat("  ", depth(node)),
+		map[bool]string{true: "+", false: "-"}[entering],
+		node,
+		fmtListFlags(node.ListFlags))
+	var b strings.Builder
+	status := d.Renderer.RenderNode(io.MultiWriter(&b, w), node, entering)
+	if b.Len() > 0 {
+		fmt.Fprintf(os.Stderr, ">> %q\n", b.String())
+	}
+	return status
+}

vendor/github.com/cpuguy83/go-md2man/v2/md2man/md2man.go

@@ -1,16 +1,24 @@
+// Package md2man aims in converting markdown into roff (man pages).
 package md2man
 
 import (
+	"os"
+	"strconv"
+
 	"github.com/russross/blackfriday/v2"
 )
 
 // Render converts a markdown document into a roff formatted document.
 func Render(doc []byte) []byte {
 	renderer := NewRoffRenderer()
+	var r blackfriday.Renderer = renderer
+	if v, _ := strconv.ParseBool(os.Getenv("MD2MAN_DEBUG")); v {
+		r = &debugDecorator{Renderer: r}
+	}
 
 	return blackfriday.Run(doc,
 		[]blackfriday.Option{
-			blackfriday.WithRenderer(renderer),
+			blackfriday.WithRenderer(r),
 			blackfriday.WithExtensions(renderer.GetExtensions()),
 		}...)
 }

vendor/github.com/cpuguy83/go-md2man/v2/md2man/roff.go

@@ -14,10 +14,8 @@ import (
 // roffRenderer implements the blackfriday.Renderer interface for creating
 // roff format (manpages) from markdown text
 type roffRenderer struct {
-	extensions   blackfriday.Extensions
 	listCounters []int
 	firstHeader  bool
-	firstDD      bool
 	listDepth    int
 }
 
@@ -43,36 +41,31 @@ const (
 	quoteTag          = "\n.PP\n.RS\n"
 	quoteCloseTag     = "\n.RE\n"
 	listTag           = "\n.RS\n"
-	listCloseTag      = "\n.RE\n"
+	listCloseTag      = ".RE\n"
 	dtTag             = "\n.TP\n"
 	dd2Tag            = "\n"
 	tableStart        = "\n.TS\nallbox;\n"
 	tableEnd          = ".TE\n"
 	tableCellStart    = "T{\n"
-	tableCellEnd      = "\nT}\n"
+	tableCellEnd      = "\nT}"
 	tablePreprocessor = `'\" t`
 )
 
 // NewRoffRenderer creates a new blackfriday Renderer for generating roff documents
 // from markdown
-func NewRoffRenderer() *roffRenderer { // nolint: golint
+func NewRoffRenderer() *roffRenderer {
-	var extensions blackfriday.Extensions
+	return &roffRenderer{}
-
-	extensions |= blackfriday.NoIntraEmphasis
-	extensions |= blackfriday.Tables
-	extensions |= blackfriday.FencedCode
-	extensions |= blackfriday.SpaceHeadings
-	extensions |= blackfriday.Footnotes
-	extensions |= blackfriday.Titleblock
-	extensions |= blackfriday.DefinitionLists
-	return &roffRenderer{
-		extensions: extensions,
-	}
 }
 
 // GetExtensions returns the list of extensions used by this renderer implementation
-func (r *roffRenderer) GetExtensions() blackfriday.Extensions {
+func (*roffRenderer) GetExtensions() blackfriday.Extensions {
-	return r.extensions
+	return blackfriday.NoIntraEmphasis |
+		blackfriday.Tables |
+		blackfriday.FencedCode |
+		blackfriday.SpaceHeadings |
+		blackfriday.Footnotes |
+		blackfriday.Titleblock |
+		blackfriday.DefinitionLists
 }
 
 // RenderHeader handles outputting the header at document start
@@ -103,7 +96,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 := bytesCut(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:
@@ -141,14 +150,25 @@ func (r *roffRenderer) RenderNode(w io.Writer, node *blackfriday.Node, entering
 	case blackfriday.Document:
 		break
 	case blackfriday.Paragraph:
-		// roff .PP markers break lists
-		if r.listDepth > 0 {
-			return blackfriday.GoToNext
-		}
 		if entering {
-			out(w, paraTag)
+			if r.listDepth > 0 {
+				// roff .PP markers break lists
+				if node.Prev != nil { // continued paragraph
+					if node.Prev.Type == blackfriday.List && node.Prev.ListFlags&blackfriday.ListTypeDefinition == 0 {
+						out(w, ".IP\n")
+					} else {
+						out(w, crTag)
+					}
+				}
+			} else if node.Prev != nil && node.Prev.Type == blackfriday.Heading {
+				out(w, crTag)
+			} else {
+				out(w, paraTag)
+			}
 		} else {
-			out(w, crTag)
+			if node.Next == nil || node.Next.Type != blackfriday.List {
+				out(w, crTag)
+			}
 		}
 	case blackfriday.BlockQuote:
 		if entering {
@@ -211,6 +231,10 @@ func (r *roffRenderer) handleHeading(w io.Writer, node *blackfriday.Node, enteri
 func (r *roffRenderer) handleList(w io.Writer, node *blackfriday.Node, entering bool) {
 	openTag := listTag
 	closeTag := listCloseTag
+	if (entering && r.listDepth == 0) || (!entering && r.listDepth == 1) {
+		openTag = crTag
+		closeTag = ""
+	}
 	if node.ListFlags&blackfriday.ListTypeDefinition != 0 {
 		// tags for definition lists handled within Item node
 		openTag = ""
@@ -239,23 +263,25 @@ func (r *roffRenderer) handleItem(w io.Writer, node *blackfriday.Node, entering
 		} else if node.ListFlags&blackfriday.ListTypeTerm != 0 {
 			// DT (definition term): line just before DD (see below).
 			out(w, dtTag)
-			r.firstDD = true
 		} else if node.ListFlags&blackfriday.ListTypeDefinition != 0 {
 			// DD (definition description): line that starts with ": ".
 			//
 			// We have to distinguish between the first DD and the
 			// subsequent ones, as there should be no vertical
 			// whitespace between the DT and the first DD.
-			if r.firstDD {
+			if node.Prev != nil && node.Prev.ListFlags&(blackfriday.ListTypeTerm|blackfriday.ListTypeDefinition) == blackfriday.ListTypeDefinition {
-				r.firstDD = false
+				if node.Prev.Type == blackfriday.Item &&
-			} else {
+					node.Prev.LastChild != nil &&
-				out(w, dd2Tag)
+					node.Prev.LastChild.Type == blackfriday.List &&
+					node.Prev.LastChild.ListFlags&blackfriday.ListTypeDefinition == 0 {
+					out(w, ".IP\n")
+				} else {
+					out(w, dd2Tag)
+				}
 			}
 		} else {
 			out(w, ".IP \\(bu 2\n")
 		}
-	} else {
-		out(w, "\n")
 	}
 }
 
@@ -290,9 +316,8 @@ func (r *roffRenderer) handleTableCell(w io.Writer, node *blackfriday.Node, ente
 		} else if nodeLiteralSize(node) > 30 {
 			end = tableCellEnd
 		}
-		if node.Next == nil && end != tableCellEnd {
+		if node.Next == nil {
-			// Last cell: need to carriage return if we are at the end of the
+			// Last cell: need to carriage return if we are at the end of the header row.
-			// header row and content isn't wrapped in a "tablecell"
 			end += crTag
 		}
 		out(w, end)
@@ -330,7 +355,7 @@ func countColumns(node *blackfriday.Node) int {
 }
 
 func out(w io.Writer, output string) {
-	io.WriteString(w, output) // nolint: errcheck
+	io.WriteString(w, output) //nolint:errcheck
 }
 
 func escapeSpecialChars(w io.Writer, text []byte) {
@@ -369,7 +394,7 @@ func escapeSpecialCharsLine(w io.Writer, text []byte) {
 			i++
 		}
 		if i > org {
-			w.Write(text[org:i]) // nolint: errcheck
+			w.Write(text[org:i]) //nolint:errcheck
 		}
 
 		// escape a character
@@ -377,6 +402,15 @@ func escapeSpecialCharsLine(w io.Writer, text []byte) {
 			break
 		}
 
-		w.Write([]byte{'\\', text[i]}) // nolint: errcheck
+		w.Write([]byte{'\\', text[i]}) //nolint:errcheck
 	}
 }
+
+// bytesCut is a copy of [bytes.Cut] to provide compatibility with go1.17
+// and older. We can remove this once we drop support  for go1.17 and older.
+func bytesCut(s, sep []byte) (before, after []byte, found bool) {
+	if i := bytes.Index(s, sep); i >= 0 {
+		return s[:i], s[i+len(sep):], true
+	}
+	return s, nil, false
+}

vendor/github.com/urfave/cli/v2/flag_string_slice.go

@@ -150,8 +150,8 @@ func (f *StringSliceFlag) Apply(set *flag.FlagSet) error {
 		setValue = f.Value.clone()
 	default:
 		setValue = new(StringSlice)
-		setValue.WithSeparatorSpec(f.separator)
 	}
+	setValue.WithSeparatorSpec(f.separator)
 
 	setValue.keepSpace = f.KeepSpace
 

vendor/github.com/urfave/cli/v2/godoc-current.txt

@@ -136,7 +136,10 @@ var SubcommandHelpTemplate = `NAME:
    {{template "helpNameTemplate" .}}
 
 USAGE:
-   {{if .UsageText}}{{wrap .UsageText 3}}{{else}}{{.HelpName}} {{if .VisibleFlags}}command [command options]{{end}}{{if .ArgsUsage}} {{.ArgsUsage}}{{else}}{{if .Args}} [arguments...]{{end}}{{end}}{{end}}{{if .Description}}
+   {{template "usageTemplate" .}}{{if .Category}}
+
+CATEGORY:
+   {{.Category}}{{end}}{{if .Description}}
 
 DESCRIPTION:
    {{template "descriptionTemplate" .}}{{end}}{{if .VisibleCommands}}

vendor/github.com/urfave/cli/v2/help.go

@@ -54,7 +54,7 @@ var helpCommand = &Command{
 			cCtx = cCtx.parentContext
 		}
 
-		// Case 4. $ app hello foo
+		// Case 4. $ app help foo
 		// foo is the command for which help needs to be shown
 		if argsPresent {
 			return ShowCommandHelp(cCtx, firstArg)
@@ -150,7 +150,7 @@ func printCommandSuggestions(commands []*Command, writer io.Writer) {
 		if command.Hidden {
 			continue
 		}
-		if strings.HasSuffix(os.Getenv("SHELL"), "zsh") {
+		if strings.HasSuffix(os.Getenv("0"), "zsh") {
 			for _, name := range command.Names() {
 				_, _ = fmt.Fprintf(writer, "%s:%s\n", name, command.Usage)
 			}

vendor/github.com/urfave/cli/v2/template.go

@@ -83,7 +83,10 @@ var SubcommandHelpTemplate = `NAME:
    {{template "helpNameTemplate" .}}
 
 USAGE:
-   {{if .UsageText}}{{wrap .UsageText 3}}{{else}}{{.HelpName}} {{if .VisibleFlags}}command [command options]{{end}}{{if .ArgsUsage}} {{.ArgsUsage}}{{else}}{{if .Args}} [arguments...]{{end}}{{end}}{{end}}{{if .Description}}
+   {{template "usageTemplate" .}}{{if .Category}}
+
+CATEGORY:
+   {{.Category}}{{end}}{{if .Description}}
 
 DESCRIPTION:
    {{template "descriptionTemplate" .}}{{end}}{{if .VisibleCommands}}

vendor/modules.txt

@@ -51,8 +51,8 @@ github.com/aws/aws-sdk-go/service/sso/ssoiface
 github.com/aws/aws-sdk-go/service/ssooidc
 github.com/aws/aws-sdk-go/service/sts
 github.com/aws/aws-sdk-go/service/sts/stsiface
-# github.com/cpuguy83/go-md2man/v2 v2.0.4
+# github.com/cpuguy83/go-md2man/v2 v2.0.7
-## explicit; go 1.11
+## explicit; go 1.12
 github.com/cpuguy83/go-md2man/v2/md2man
 # github.com/davecgh/go-spew v1.1.1
 ## explicit
@@ -88,7 +88,7 @@ github.com/russross/blackfriday/v2
 # github.com/stretchr/testify v1.9.0
 ## explicit; go 1.17
 github.com/stretchr/testify/assert
-# github.com/urfave/cli/v2 v2.27.4
+# github.com/urfave/cli/v2 v2.27.7
 ## explicit; go 1.18
 github.com/urfave/cli/v2
 # github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1