Repository: cli/cli
File: pkg/cmd/root/help_topic.go (Go)

Code before:
			to be installed on the system to use this formatting directive. When connected to a terminal,
			the output is automatically pretty-printed. To learn about jq query syntax, see:
			<https://jqlang.github.io/jq/manual/>

			The %[1]s--template%[1]s flag requires a string argument in Go template syntax, and will only print
			those JSON values which match the query.
			In addition to the Go template functions in the standard library, the following functions can be used
			with this formatting directive:
			- %[1]sautocolor%[1]s: like %[1]scolor%[1]s, but only emits color to terminals
			- %[1]scolor <style> <input>%[1]s: colorize input using <https://github.com/mgutz/ansi>
			- %[1]sjoin <sep> <list>%[1]s: joins values in the list using a separator
			- %[1]spluck <field> <list>%[1]s: collects values of a field from all items in the input
			- %[1]stablerow <fields>...%[1]s: aligns fields in output vertically as a table
			- %[1]stablerender%[1]s: renders fields added by tablerow in place
			- %[1]stimeago <time>%[1]s: renders a timestamp as relative to now
			- %[1]stimefmt <format> <time>%[1]s: formats a timestamp using Go's %[1]sTime.Format%[1]s function
			- %[1]struncate <length> <input>%[1]s: ensures input fits within length
			- %[1]shyperlink <url> <text>%[1]s: renders a terminal hyperlink

			The following Sprig template library functions can also be used with this formatting directive:
			- %[1]scontains <arg> <string>%[1]s: checks if %[1]sstring%[1]s contains %[1]sarg%[1]s
			- %[1]shasPrefix <prefix> <string>%[1]s: checks if %[1]sstring%[1]s starts with %[1]sprefix%[1]s
			- %[1]shasSuffix <suffix> <string>%[1]s: checks if %[1]sstring%[1]s ends with %[1]ssuffix%[1]s
			- %[1]sregexMatch <regex> <string>%[1]s: checks if %[1]sstring%[1]s has any matches for %[1]sregex%[1]s
			For more information about the Sprig library, see <https://masterminds.github.io/sprig/>.

			To learn more about Go templates, see: <https://golang.org/pkg/text/template/>.
		`, "`"),
		example: heredoc.Doc(`
			# Default output format
			$ gh pr list
			Showing 23 of 23 open pull requests in cli/cli

			#123  A helpful contribution          contribution-branch              about 1 day ago
			#124  Improve the docs                docs-branch                      about 2 days ago
			#125  An exciting new feature         feature-branch                   about 2 days ago


			# Adding the --json flag with a list of field names
			$ gh pr list --json number,title,author
			[
			  {
			    "author": {
			      "login": "monalisa"
			    },
			    "number": 123,
			    "title": "A helpful contribution"
			  },
			  {
			    "author": {
			      "login": "codercat"

Review comment (refactor):
**suggestion:** should we add a few new lines to make some of this and the above text easier to read?

Here is what this currently looks like from a local build:

```shell
$ bin/gh help formatting
By default, the result of `gh` commands are output in line-based plain text format.
Some commands support passing the `--json` flag, which converts the output to JSON format.
Once in JSON, the output can be further formatted according to a required formatting string by
adding either the `--jq` or `--template` flag. This is useful for selecting a subset of data,
creating new data structures, displaying the data in a different format, or as input to another
command line script.

The `--json` flag requires a comma separated list of fields to fetch. To view the possible JSON
field names for a command omit the string argument to the `--json` flag when you run the command.
Note that you must pass the `--json` flag and field names to use the `--jq` or `--template` flags.

The `--jq` flag requires a string argument in jq query syntax, and will only print
those JSON values which match the query. jq queries can be used to select elements from an
array, fields from an object, create a new array, and more. The `jq` utility does not need
to be installed on the system to use this formatting directive. When connected to a terminal,
the output is automatically pretty-printed. To learn about jq query syntax, see:
<https://jqlang.github.io/jq/manual/>

The `--template` flag requires a string argument in Go template syntax, and will only print
those JSON values which match the query.
In addition to the Go template functions in the standard library, the following functions can be used
with this formatting directive:
- `autocolor`: like `color`, but only emits color to terminals
- `color <style> <input>`: colorize input using <https://github.com/mgutz/ansi>
- `join <sep> <list>`: joins values in the list using a separator
- `pluck <field> <list>`: collects values of a field from all items in the input
- `tablerow <fields>...`: aligns fields in output vertically as a table
- `tablerender`: renders fields added by tablerow in place
- `timeago <time>`: renders a timestamp as relative to now
- `timefmt <format> <time>`: formats a timestamp using Go's `Time.Format` function
- `truncate <length> <input>`: ensures input fits within length
- `hyperlink <url> <text>`: renders a terminal hyperlink

The following Sprig template library functions can also be used with this formatting directive:
- `contains <arg> <string>`: checks if `string` contains `arg`
- `hasPrefix <prefix> <string>`: checks if `string` starts with `prefix`
- `hasSuffix <suffix> <string>`: checks if `string` ends with `suffix`
- `regexMatch <regex> <string>`: checks if `string` has any matches for `regex`
For more information about the Sprig library, see <https://masterminds.github.io/sprig/>.

To learn more about Go templates, see: <https://golang.org/pkg/text/template/>.
```

I think adding a newline before each of the following would make this easier to read:

1. `In addition to the Go template functions in the standard library, the following functions can be used`
2. `For more information about the Sprig library, see <https://masterminds.github.io/sprig/>.`

```shell
By default, the result of `gh` commands are output in line-based plain text format.
Some commands support passing the `--json` flag, which converts the output to JSON format.
Once in JSON, the output can be further formatted according to a required formatting string by
adding either the `--jq` or `--template` flag. This is useful for selecting a subset of data,
creating new data structures, displaying the data in a different format, or as input to another
command line script.

The `--json` flag requires a comma separated list of fields to fetch. To view the possible JSON
field names for a command omit the string argument to the `--json` flag when you run the command.
Note that you must pass the `--json` flag and field names to use the `--jq` or `--template` flags.

The `--jq` flag requires a string argument in jq query syntax, and will only print
those JSON values which match the query. jq queries can be used to select elements from an
array, fields from an object, create a new array, and more. The `jq` utility does not need
to be installed on the system to use this formatting directive. When connected to a terminal,
the output is automatically pretty-printed. To learn about jq query syntax, see:
<https://jqlang.github.io/jq/manual/>

The `--template` flag requires a string argument in Go template syntax, and will only print
those JSON values which match the query.

In addition to the Go template functions in the standard library, the following functions can be used
with this formatting directive:
- `autocolor`: like `color`, but only emits color to terminals
- `color <style> <input>`: colorize input using <https://github.com/mgutz/ansi>
- `join <sep> <list>`: joins values in the list using a separator
- `pluck <field> <list>`: collects values of a field from all items in the input
- `tablerow <fields>...`: aligns fields in output vertically as a table
- `tablerender`: renders fields added by tablerow in place
- `timeago <time>`: renders a timestamp as relative to now
- `timefmt <format> <time>`: formats a timestamp using Go's `Time.Format` function
- `truncate <length> <input>`: ensures input fits within length
- `hyperlink <url> <text>`: renders a terminal hyperlink

The following Sprig template library functions can also be used with this formatting directive:
- `contains <arg> <string>`: checks if `string` contains `arg`
- `hasPrefix <prefix> <string>`: checks if `string` starts with `prefix`
- `hasSuffix <suffix> <string>`: checks if `string` ends with `suffix`
- `regexMatch <regex> <string>`: checks if `string` has any matches for `regex`

For more information about the Sprig library, see <https://masterminds.github.io/sprig/>.

To learn more about Go templates, see: <https://golang.org/pkg/text/template/>.
```

Code after:
			to be installed on the system to use this formatting directive. When connected to a terminal,
			the output is automatically pretty-printed. To learn about jq query syntax, see:
			<https://jqlang.github.io/jq/manual/>

			The %[1]s--template%[1]s flag requires a string argument in Go template syntax, and will only print
			those JSON values which match the query.

			In addition to the Go template functions in the standard library, the following functions can be used
			with this formatting directive:
			- %[1]sautocolor%[1]s: like %[1]scolor%[1]s, but only emits color to terminals
			- %[1]scolor <style> <input>%[1]s: colorize input using <https://github.com/mgutz/ansi>
			- %[1]sjoin <sep> <list>%[1]s: joins values in the list using a separator
			- %[1]spluck <field> <list>%[1]s: collects values of a field from all items in the input
			- %[1]stablerow <fields>...%[1]s: aligns fields in output vertically as a table
			- %[1]stablerender%[1]s: renders fields added by tablerow in place
			- %[1]stimeago <time>%[1]s: renders a timestamp as relative to now
			- %[1]stimefmt <format> <time>%[1]s: formats a timestamp using Go's %[1]sTime.Format%[1]s function
			- %[1]struncate <length> <input>%[1]s: ensures input fits within length
			- %[1]shyperlink <url> <text>%[1]s: renders a terminal hyperlink

			The following Sprig template library functions can also be used with this formatting directive:
			- %[1]scontains <arg> <string>%[1]s: checks if %[1]sstring%[1]s contains %[1]sarg%[1]s
			- %[1]shasPrefix <prefix> <string>%[1]s: checks if %[1]sstring%[1]s starts with %[1]sprefix%[1]s
			- %[1]shasSuffix <suffix> <string>%[1]s: checks if %[1]sstring%[1]s ends with %[1]ssuffix%[1]s
			- %[1]sregexMatch <regex> <string>%[1]s: checks if %[1]sstring%[1]s has any matches for %[1]sregex%[1]s

			For more information about the Sprig library, see <https://masterminds.github.io/sprig/>.

			To learn more about Go templates, see: <https://golang.org/pkg/text/template/>.
		`, "`"),
		example: heredoc.Doc(`
			# Default output format
			$ gh pr list
			Showing 23 of 23 open pull requests in cli/cli

			#123  A helpful contribution          contribution-branch              about 1 day ago
			#124  Improve the docs                docs-branch                      about 2 days ago
			#125  An exciting new feature         feature-branch                   about 2 days ago


			# Adding the --json flag with a list of field names
			$ gh pr list --json number,title,author
			[
			  {
			    "author": {
			      "login": "monalisa"
			    },
			    "number": 123,
			    "title": "A helpful contribution"
			  },
			  {