breakup v2 documentation

docs/v2/examples/combining-short-options.md

@@ -0,0 +1,67 @@
+Traditional use of options using their shortnames look like this:
+
+```sh-session
+$ cmd -s -o -m "Some message"
+```
+
+Suppose you want users to be able to combine options with their shortnames. This
+can be done using the `UseShortOptionHandling` bool in your app configuration,
+or for individual commands by attaching it to the command configuration. For
+example:
+
+<!-- {
+  "args": ["short", "&#45;som", "Some message"],
+  "output": "serve: true\noption: true\nmessage: Some message\n"
+} -->
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/urfave/cli/v2"
+)
+
+func main() {
+	app := &cli.App{
+		UseShortOptionHandling: true,
+		Commands: []*cli.Command{
+			{
+				Name:  "short",
+				Usage: "complete a task on the list",
+				Flags: []cli.Flag{
+					&cli.BoolFlag{Name: "serve", Aliases: []string{"s"}},
+					&cli.BoolFlag{Name: "option", Aliases: []string{"o"}},
+					&cli.StringFlag{Name: "message", Aliases: []string{"m"}},
+				},
+				Action: func(cCtx *cli.Context) error {
+					fmt.Println("serve:", cCtx.Bool("serve"))
+					fmt.Println("option:", cCtx.Bool("option"))
+					fmt.Println("message:", cCtx.String("message"))
+					return nil
+				},
+			},
+		},
+	}
+
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+If your program has any number of bool flags such as `serve` and `option`, and
+optionally one non-bool flag `message`, with the short options of `-s`, `-o`,
+and `-m` respectively, setting `UseShortOptionHandling` will also support the
+following syntax:
+
+```sh-session
+$ cmd -som "Some message"
+```
+
+If you enable `UseShortOptionHandling`, then you must not use any flags that
+have a single leading `-` or this will result in failures. For example,
+`-option` can no longer be used. Flags with two leading dashes (such as
+`--options`) are still valid.