Switch to using backticks for multiline strings for many commands

7 files changed, 38 insertions, 41 deletions

diff --git a/cmd/gitaly/main_test.go b/cmd/gitaly/main_test.go
index 2c820f84f..ca4bc3698 100644
--- a/cmd/gitaly/main_test.go
+++ b/cmd/gitaly/main_test.go
@@ -42,7 +42,7 @@ func TestGitalyCLI(t *testing.T) {
 			desc:     "check without config",
 			args:     []string{"check"},
 			exitCode: 2,
-			stdout:   "NAME:\n   gitaly check - verify internal API is accessible\n\nUSAGE:\n   gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n   Check that the internal Gitaly API is accessible.\n\n   Example: `gitaly check gitaly.config.toml`.\n\nOPTIONS:\n   --help, -h  show help\n",
+			stdout:   "NAME:\n   gitaly check - verify internal API is accessible\n\nUSAGE:\n   gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n   Check that the internal Gitaly API is accessible.\n\n   Example: gitaly check gitaly.config.toml\n\nOPTIONS:\n   --help, -h  show help\n",
 			stderr:   "invalid argument(s)",
 		},
 		{
diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md
index b11654f4d..8c01b85b4 100644
--- a/doc/help_text_style_guide.md
+++ b/doc/help_text_style_guide.md
@@ -20,12 +20,12 @@ To help users discover `gitaly` and `praefect` features through the CLI:
   Instead, list subcommands in the value of the `Description` field key. For example:
 
   ```go
-  Description: "This is a long description of all the things example command can do.\n\n" +
+  Description: `This is a long description of all the things example command can do.
 
-                "Provides the following subcommands:\n\n" +
+  Provides the following subcommands:
 
-                "- subcommand1\n\n" +
-                "- subcommand2\n\n",
+  - subcommand1
+  - subcommand2`,
   ```
 
 ## Rules for command strings
@@ -81,25 +81,19 @@ When providing values for the `Usage` field key:
 
 When providing values for the `Description` field key:
 
-- If referring to subcommands or flags, put the subcommand or flag in backticks. For example:
-
-  ```plaintext
-  `subcommand` can be run at any time with the `flag` flag.
-  ```
-
 - Can mention Gitaly, Praefect, or Gitaly Cluster. For example:
 
   ```plaintext
   Runs all of the processes for the Gitaly Cluster.
   ```
 
-If the command or subcommand requires more than just flags, add an example of invoking the command. For example:
+- If the command or subcommand requires more than just flags, add an example of invoking the command. For example:
 
-```go
-Description: "The subcommand accepts a file on stdin.\n\n" +
+  ```go
+  Description: `The subcommand accepts a file on stdin.
 
-             "Example: `command subcommand < file`." +
-```
+  Example: command subcommand < file`
+  ```
 
 ## Related topics
 
diff --git a/internal/cli/gitaly/check.go b/internal/cli/gitaly/check.go
index 9c0c3932b..40d5f925e 100644
--- a/internal/cli/gitaly/check.go
+++ b/internal/cli/gitaly/check.go
@@ -17,9 +17,9 @@ func newCheckCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "check",
 		Usage: "verify internal API is accessible",
-		Description: "Check that the internal Gitaly API is accessible.\n\n" +
+		Description: `Check that the internal Gitaly API is accessible.
 
-			"Example: `gitaly check gitaly.config.toml`.",
+Example: gitaly check gitaly.config.toml`,
 		ArgsUsage:       "<configfile>",
 		Action:          checkAction,
 		HideHelpCommand: true,
diff --git a/internal/cli/gitaly/configuration-validate.go b/internal/cli/gitaly/configuration-validate.go
index e53710b6a..4495f5461 100644
--- a/internal/cli/gitaly/configuration-validate.go
+++ b/internal/cli/gitaly/configuration-validate.go
@@ -13,27 +13,26 @@ func newConfigurationCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "configuration",
 		Usage: "run configuration-related commands",
-		Description: "Run commands related to Gitaly configuration.\n\n" +
+		Description: `Run commands related to Gitaly configuration.
 
-			"Provides the following subcommand:\n\n" +
+Provides the following subcommand:
 
-			"- validate",
+- validate`,
 		HideHelpCommand: true,
 		Subcommands: []*cli.Command{
 			{
 				Name:  "validate",
 				Usage: "validate Gitaly configuration",
-				Description: "Check that input provided on stdin is valid Gitaly configuration.\n" +
-					"Use `validate` before starting Gitaly.\n\n" +
+				Description: `Check that input provided on stdin is valid Gitaly configuration.
+Use validate before starting Gitaly.
 
-					"Prints all configuration problems to stdout in JSON format.\n" +
-					"The output's structure includes:\n\n" +
+Prints all configuration problems to stdout in JSON format.
+The output's structure includes:
 
-					"- A key, which is the path to the configuration field where the\n" +
-					"  problem is detected.\n" +
-					"- A message, with an explanation of the problem.\n\n" +
+- A key, which is the path to the configuration field where the problem is detected.
+- A message, with an explanation of the problem.
 
-					"Example: `gitaly configuration validate < gitaly.config.toml`.",
+Example: gitaly configuration validate < gitaly.config.toml`,
 				Action: validateConfigurationAction,
 			},
 		},
diff --git a/internal/cli/gitaly/hooks.go b/internal/cli/gitaly/hooks.go
index d1ced6462..2aa8819f6 100644
--- a/internal/cli/gitaly/hooks.go
+++ b/internal/cli/gitaly/hooks.go
@@ -29,21 +29,21 @@ func newHooksCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "hooks",
 		Usage: "manage Git hooks",
-		Description: "Manage hooks for a Git repository.\n\n" +
+		Description: `Manage hooks for a Git repository.
 
-			"Provides the following subcommand:\n\n" +
+Provides the following subcommand:
 
-			"- set",
+- set`,
 		HideHelpCommand: true,
 		Subcommands: []*cli.Command{
 			{
 				Name:  "set",
 				Usage: "set custom hooks for a Git repository",
-				Description: "Reads a tarball containing custom Git hooks from stdin and writes the hooks to the specified repository.\n\n" +
+				Description: `Reads a tarball containing custom Git hooks from stdin and writes the hooks to the specified repository.
 
-					"Example: `gitaly hooks set --storage default --repository @hashed/<path_to_git_repository>/repository.git --config gitaly.config.toml < hooks_tarball.tar`.\n\n" +
+Example: gitaly hooks set --storage default --repository @hashed/<path_to_git_repository>/repository.git --config gitaly.config.toml < hooks_tarball.tar
 
-					"To remove custom Git hooks for a specified repository, run the set subcommand with an empty tarball file.",
+To remove custom Git hooks for a specified repository, run the set subcommand with an empty tarball file.`,
 				Action: setHooksAction,
 				Flags: []cli.Flag{
 					&cli.StringFlag{
diff --git a/internal/cli/gitaly/serve.go b/internal/cli/gitaly/serve.go
index 3c5bcdfc5..50ca2f78c 100644
--- a/internal/cli/gitaly/serve.go
+++ b/internal/cli/gitaly/serve.go
@@ -54,9 +54,11 @@ import (
 
 func newServeCommand() *cli.Command {
 	return &cli.Command{
-		Name:            "serve",
-		Usage:           "launch the server daemon",
-		Description:     "Launch the Gitaly server daemon.",
+		Name:  "serve",
+		Usage: "launch the server daemon",
+		Description: `Launch the Gitaly server daemon.
+
+Example: gitaly serve gitaly.config.toml`,
 		ArgsUsage:       "<configfile>",
 		Action:          serveAction,
 		HideHelpCommand: true,
diff --git a/internal/cli/praefect/serve.go b/internal/cli/praefect/serve.go
index 3e3711231..267bfb04c 100644
--- a/internal/cli/praefect/serve.go
+++ b/internal/cli/praefect/serve.go
@@ -42,9 +42,11 @@ import (
 
 func newServeCommand() *cli.Command {
 	return &cli.Command{
-		Name:            "serve",
-		Usage:           "launch the server daemon",
-		Description:     "Launch the Praefect server daemon.",
+		Name:  "serve",
+		Usage: "launch the server daemon",
+		Description: `Launch the Praefect server daemon.
+
+Example: praefect --config praefect.config.toml serve`,
 		Action:          serveAction,
 		HideHelpCommand: true,
 		Before: func(context *cli.Context) error {