How to describe a flag in autogenerated help

[wayan]

Is there a simple way how to describe a command option (flag) on a few lines in generated help? The similar way how git options are described, see OPTIONS in the output of git fetch help as an example. I found no UsageText or anything similar in Flag types.

I appreciate any recommendations.

[dearchap]

@wayan

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/urfave/cli/v2"
)

func main() {
	app := &cli.App{
		Flags: []cli.Flag{
			&cli.StringFlag{
				Name:  "lang",
				Value: "english",
				Usage: `
					A very big nefertiti flag which
	can wrap multiples lines
	What up ?`,
			},
		},
		Action: func(c *cli.Context) error {
			name := "Nefertiti"
			if c.NArg() > 0 {
				name = c.Args().Get(0)
			}
			if c.String("lang") == "spanish" {
				fmt.Println("Hola", name)
			} else {
				fmt.Println("Hello", name)
			}
			return nil
		},
	}

	err := app.Run(os.Args)
	if err != nil {
		log.Fatal(err)
	}
}

and the output

$ go run main.go  -h
NAME:
   main - A new cli application

USAGE:
   main [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --lang value  A very big nefertiti flag which
                 can wrap multiples lines
                 What up ? (default: "english")
   --help, -h    show help (default: false)

[wayan]

But what are the rules for formatting multiline Usage texts? In your example (which I tried) it looks like that every line of Usage but first if started by the tab character is indented by 16 spaces. But when I tried some combinations it made me confused.

                Usage: `A very big nefertiti flag which 
 
    starts with one tab 
        start with two tabs`, 
            }

yields

   --language value  A very big nefertiti flag which

               starts with one tab
                 start with two tabs (default: "english")

while

                Usage: `A very big nefertiti flag which

    starts with one tab
        start with two tabs
starts with no indent`,

yields

   --language value  A very big nefertiti flag which

  starts with one tab
    start with two tabs
starts with no indent (default: "english")

What am I missing?

[dearchap]

@wayan There is no special treatment for multiline strings. Everything is treated exactly as given by user. It might be possible to add a feature in a future release to make this easier but for now we are stuck with what we have

[meatballhat]

@wayan perhaps something like https://github.com/lithammer/dedent would be helpful? Then you can format your multiline strings with any amount of common leading blankspace.

[wayan]

@wayan There is no special treatment for multiline strings. Everything is treated exactly as given by user. It might be possible to add a feature in a future release to make this easier but for now we are stuck with what we have

I still do not understand. In your source code example, the second and third line of Usage multiline text is indented by one tab, while in the help output those lines are indented by 16 spaces (real spaces]. What code causes this transformation and what are the rules?

If I just fmt.Print the Usage from your example, then those lines are indented by one tab - no change.

[dearchap]

@wayan We will fix this as part of #1465 . There will be an update to the code and docs to show how this needs to be done. For now I'm closing this issue. Feel free to comment in #1465 for further requirements

[dearchap]

Yeah I'm not sure what the rules are. Let me check.

On Mon, Apr 25, 2022 at 4:50 AM wayan @.***> wrote:

But what are the rules for formatting multiline Usage texts? In your example (which I tried) it looks like that every line of Usage but first if started by the tab character is indented by 16 spaces. But when I tried some combinations it made me confused.

            Usage: `A very big nefertiti flag which

starts with one tab
    start with two tabs`,
        }

yields

--language value A very big nefertiti flag which

           starts with one tab
             start with two tabs (default: "english")

while

            Usage: `A very big nefertiti flag which

starts with one tab
    start with two tabs

starts with no indent`,

yields

--language value A very big nefertiti flag which

starts with one tab start with two tabs starts with no indent (default: "english")

What am I missing?

— Reply to this email directly, view it on GitHub https://github.com/urfave/cli/issues/1344#issuecomment-1108271244, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAYNLZX5OL56M54ZPPFEV5TVGZMDRANCNFSM5S674KPQ . You are receiving this because you commented.Message ID: @.***>