From b0898900ce0d1e70a7c1e805a1bcfce7d1e2b824 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?V=C3=ADctor=20Gonz=C3=A1lez=20Prieto?=
 <victor.gp.dev@gmail.com>
Date: Tue, 26 Apr 2022 19:42:18 +0200
Subject: [PATCH] Syntax: add cmd-help (#2148)

* Add cmd-help syntax

To highlight command --help messages.

* README.md: mention help message highlighting

* README.md: edit help message highlighting
---
 .gitmodules                                   |  5 ++
 CHANGELOG.md                                  |  1 +
 README.md                                     | 18 +++++++
 assets/syntaxes/02_Extra/cmd-help             |  1 +
 .../highlighted/cmd-help/test.cmd-help        | 54 +++++++++++++++++++
 .../source/cmd-help/test.cmd-help             | 54 +++++++++++++++++++
 6 files changed, 133 insertions(+)
 create mode 160000 assets/syntaxes/02_Extra/cmd-help
 create mode 100644 tests/syntax-tests/highlighted/cmd-help/test.cmd-help
 create mode 100644 tests/syntax-tests/source/cmd-help/test.cmd-help

diff --git a/.gitmodules b/.gitmodules
index 50616ed2..156f4206 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -239,3 +239,8 @@
 [submodule "assets/syntaxes/02_Extra/SublimeJQ"]
 	path = assets/syntaxes/02_Extra/SublimeJQ
 	url = https://github.com/zogwarg/SublimeJQ.git
+[submodule "assets/syntaxes/02_Extra/cmd-help"]
+	path = assets/syntaxes/02_Extra/cmd-help
+	url = https://github.com/victor-gp/cmd-help-sublime-syntax.git
+	branch = main
+	shallow = true
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6447c1eb..fc8f5c9b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@
 
 - Mapped clang-format config file (.clang-format) to YAML syntax (@TruncatedDinosour)
 - log syntax: improved handling of escape characters in double quoted strings. See #2123 (@keith-hall)
+- Added cmd-help syntax to scope --help messages. See #2148 (@victor-gp)
 
 ## Themes
 
diff --git a/README.md b/README.md
index 7c1611ad..63b57897 100644
--- a/README.md
+++ b/README.md
@@ -212,6 +212,24 @@ Also, note that this will [not work](https://github.com/sharkdp/bat/issues/1145)
 
 The [`prettybat`](https://github.com/eth-p/bat-extras/blob/master/doc/prettybat.md) script is a wrapper that will format code and print it with `bat`.
 
+#### Highlighting `--help` messages
+
+You can use `bat` to colorize help text: `$ cp --help | bat -plhelp`
+
+You can also use a wrapper around this:
+
+```bash
+# in your .bashrc/.zshrc/*rc
+alias bathelp='bat --plain --language=help'
+help() {
+    "$@" --help 2>&1 | bathelp
+}
+```
+
+Then you can do `$ help cp` or `$ help git commit`.
+
+Please report any issues with the help syntax in [this repository](https://github.com/victor-gp/cmd-help-sublime-syntax).
+
 
 ## Installation
 
diff --git a/assets/syntaxes/02_Extra/cmd-help b/assets/syntaxes/02_Extra/cmd-help
new file mode 160000
index 00000000..1e513f5f
--- /dev/null
+++ b/assets/syntaxes/02_Extra/cmd-help
@@ -0,0 +1 @@
+Subproject commit 1e513f5f194e868035d2d24952ecab6d9f49572a
diff --git a/tests/syntax-tests/highlighted/cmd-help/test.cmd-help b/tests/syntax-tests/highlighted/cmd-help/test.cmd-help
new file mode 100644
index 00000000..c758a0d9
--- /dev/null
+++ b/tests/syntax-tests/highlighted/cmd-help/test.cmd-help
@@ -0,0 +1,54 @@
+bat 0.20.0 (e735562-modified)
+A cat(1) clone with syntax highlighting and Git integration.
+
+USAGE:
+    bat [OPTIONS] [FILE]...
+    bat <SUBCOMMAND>
+
+OPTIONS:
+    -A, --show-all
+            Show non-printable characters (space, tab, newline, ..).
+
+    -p, --plain                          Show plain style (alias for '--style=plain').
+    -l, --language <language>            Set the language for syntax highlighting.
+    -H, --highlight-line <N:M>...        Highlight lines N through M.
+        --file-name <name>...            Specify the name to display for a file.
+    -d, --diff
+            Only show lines that have been added/removed/modified.
+
+        --tabs <T>                       Set the tab width to T spaces.
+        --wrap <mode>
+            Specify the text-wrapping mode (*auto*, never, character).
+
+    -n, --number
+            Show line numbers (alias for '--style=numbers').
+
+        --color <when>                   When to use colors (*auto*, never, always).
+        --italic-text <when>             Use italics in output (always, *never*)
+        --decorations <when>
+            When to show the decorations (*auto*, never, always).
+
+        --paging <when>
+            Specify when to use the pager, or use `-P` to disable (*auto*, never,
+            always).
+    -m, --map-syntax <glob:syntax>...
+            Use the specified syntax for files matching the glob pattern
+            ('*.cpp:C++').
+        --theme <theme>                  Set the color theme for syntax highlighting.
+        --list-themes                    Display all supported highlighting themes.
+        --style <components>
+            Comma-separated list of style elements to display (*auto*, full, plain,
+            changes, header, grid, rule, numbers, snip).
+    -r, --line-range <N:M>...            Only print the lines from N to M.
+    -L, --list-languages                 Display all supported languages.
+    -h, --help                           Print this help message.
+    -V, --version                        Show version information.
+
+ARGS:
+    <FILE>...    File(s) to print / concatenate. Use '-' for standard input.
+
+SUBCOMMANDS:
+    cache    Modify the syntax-definition and theme cache
+
+Note: `bat -h` prints a short and concise overview while `bat --help` gives all
+details.
diff --git a/tests/syntax-tests/source/cmd-help/test.cmd-help b/tests/syntax-tests/source/cmd-help/test.cmd-help
new file mode 100644
index 00000000..7c40925c
--- /dev/null
+++ b/tests/syntax-tests/source/cmd-help/test.cmd-help
@@ -0,0 +1,54 @@
+bat 0.20.0 (e735562-modified)
+A cat(1) clone with syntax highlighting and Git integration.
+
+USAGE:
+    bat [OPTIONS] [FILE]...
+    bat <SUBCOMMAND>
+
+OPTIONS:
+    -A, --show-all
+            Show non-printable characters (space, tab, newline, ..).
+
+    -p, --plain                          Show plain style (alias for '--style=plain').
+    -l, --language <language>            Set the language for syntax highlighting.
+    -H, --highlight-line <N:M>...        Highlight lines N through M.
+        --file-name <name>...            Specify the name to display for a file.
+    -d, --diff
+            Only show lines that have been added/removed/modified.
+
+        --tabs <T>                       Set the tab width to T spaces.
+        --wrap <mode>
+            Specify the text-wrapping mode (*auto*, never, character).
+
+    -n, --number
+            Show line numbers (alias for '--style=numbers').
+
+        --color <when>                   When to use colors (*auto*, never, always).
+        --italic-text <when>             Use italics in output (always, *never*)
+        --decorations <when>
+            When to show the decorations (*auto*, never, always).
+
+        --paging <when>
+            Specify when to use the pager, or use `-P` to disable (*auto*, never,
+            always).
+    -m, --map-syntax <glob:syntax>...
+            Use the specified syntax for files matching the glob pattern
+            ('*.cpp:C++').
+        --theme <theme>                  Set the color theme for syntax highlighting.
+        --list-themes                    Display all supported highlighting themes.
+        --style <components>
+            Comma-separated list of style elements to display (*auto*, full, plain,
+            changes, header, grid, rule, numbers, snip).
+    -r, --line-range <N:M>...            Only print the lines from N to M.
+    -L, --list-languages                 Display all supported languages.
+    -h, --help                           Print this help message.
+    -V, --version                        Show version information.
+
+ARGS:
+    <FILE>...    File(s) to print / concatenate. Use '-' for standard input.
+
+SUBCOMMANDS:
+    cache    Modify the syntax-definition and theme cache
+
+Note: `bat -h` prints a short and concise overview while `bat --help` gives all
+details.