Repository: sharkdp/bat (language: rust)

Issue:
`man` page doesn't get colorized if the default theme's changed
**Describe the bug you encountered:**
I tried playing with multiple options, but as soon as I change the default theme to anything else, colorization on `man` pages break.

I tried setting theme to `ansi`, `base16`, `base16-256`, `OneHalfDark`, and `1337`. I also set `--color=always`, but that didn't help either even though I explicitly specify the language as `man` while piping into `bat`.

This can be reproduced by invoking `bat` on `bat`'s help itself: `bat --help | bat -l man`. Highlighting works with the default theme, but not with others -- only a few words get highlighted.

...

**What did you expect to happen instead?**
Syntax highlighting on the `man` page just as it functions with the default theme.
...


**How did you install `bat`?**

I used Scoop to install `bat`.

---

**bat version and environment**
I use PowerShell 7.2.1 that supports Unicode by default and Windows Terminal that has `xterm-256` terminal capabilities.

This the output on running `bat --help | bat -l man --diagnostic`:

#### Software version

bat 0.20.0 (0655ecf)

#### Operating system

Windows 6.2.9200

#### Command-line

```bash
C:\Users\anike\scoop\apps\bat\current\bat.exe -l man --diagnostic
```

#### Environment variables

```bash
SHELL=<not set>
PAGER=<not set>
LESS=<not set>
LANG=<not set>
LC_ALL=<not set>
BAT_PAGER=<not set>
BAT_CACHE_PATH=<not set>
BAT_CONFIG_PATH=<not set>
BAT_OPTS=<not set>
BAT_STYLE=<not set>
BAT_TABS=<not set>
BAT_THEME=<not set>
XDG_CONFIG_HOME=<not set>
XDG_CACHE_HOME=<not set>
COLORTERM=<not set>
NO_COLOR=<not set>
MANPAGER=<not set>
```

#### Config file

```
# This is `bat`s configuration file. Each line either contains a comment or
# a command-line option that you want to pass to `bat` by default. You can
# run `bat --help` to get a list of all possible configuration options.

# Specify desired highlighting theme (e.g. "TwoDark"). Run `bat --list-themes`
# for a list of all available themes
# --theme="ansi"

# Enable this to use italic text on the terminal. This is not supported on all
# terminal emulators (like tmux, by default):
--italic-text=always

# Uncomment the following line to disable automatic paging:
#--paging=never

# Uncomment the following line if you are using less version >= 551 and want to
# enable mouse scrolling support in `bat` when running inside tmux. This might
# disable text selection, unless you press shift.
--pager="less --RAW-CONTROL-CHARS --quit-if-one-screen --mouse"

# Syntax mappings: map a certain filename pattern to a language.
#   Example 1: use the C++ syntax for Arduino .ino files
#   Example 2: Use ".gitignore"-style highlighting for ".ignore" files
#--map-syntax "*.ino:C++"
#--map-syntax ".ignore:Git Ignore"

--style=changes,header,header-filesize
--color=always
```

#### Compile time information

- Profile: release
- Target triple: x86_64-pc-windows-msvc
- Family: windows
- OS: windows
- Architecture: x86_64
- Pointer width: 64
- Endian: little
- CPU features: fxsr,sse,sse2
- Host: x86_64-pc-windows-msvc

#### Less version

```
> C:\Users\anike\scoop\shims\less.exe --version
less 590 (Spencer V8 regular expressions)
Copyright (C) 1984-2021  Mark Nudelman

less comes with NO WARRANTY, to the extent permitted by law.
For information about the terms of redistribution,
see the file named README in the less distribution.
Home page: https://greenwoodsoftware.com/less
```



Discussion / hints:
Yes, I just came here to search for the same problem.
I confirm this issue on Arch Linux, `bat 0.20.0 (0655ecf2)`.
Thanks for reporting. It seems these other color schemes are not targeting [the minimum viable scopes as recommended by ST](http://www.sublimetext.com/docs/scope_naming.html#color_schemes). For example, our `man` syntax definition is using `entity.name.command-line-option`, and the guidelines say color schemes should target `entity.name`. But "TwoDark", (to take a specific example,) only targets `entity.name.function`, `entity.name.class` and a few other "3 atom scopes" starting with `entity.name` but not `entity.name` itself and not `entity.name.command-line-option`.

The solution will be to get the third party color schemes updated - either by patching them in this repository, or by making fixes in the upstream repositories and then updating `bat`'s submodule dependencies. Therefore I am marking this as an upstream error and help-wanted.
Having said that, it could be that I'm biased because *I* chose to use those scopes for our Manpage syntax highlighting. I understand that it would likely take less effort to adjust the scopes we use to those which are more commonly targeted by color schemes. So it is conceivable that we might accept a PR adjusting the scopes in the Manpage syntax definition to resolve this issue.
@icy-comet, could it be that what you're trying to colorize is a --help message rather than a man page? If that's the case, I've been working on [a sublime syntax to scope help messages](https://github.com/victor-gp/cmd-help-sublime-syntax). It's still a work in progress but you may find it useful.

I plan to stabilize it over the next week and PR it to bat in 1-2 weeks.

@keith-hall, I tackled theme coverage by [multi-scoping](https://github.com/victor-gp/cmd-help-sublime-syntax/blob/c72a2dc7dcee4d5c83aa380f752613532d272023/syntaxes/cmd-help.sublime-syntax#L28), with mostly unrelated scopes. You may think it a sacrilege (it is :sweat_smile:) but if you're willing to ignore scope meaning, here's a couple of changes that improve theme coverage by a bit: [command options from entity.name to entity.name.function](https://github.com/victor-gp/cmd-help-sublime-syntax/commit/0a44e2ec44318008c423650286d0838cab4362e7) and [multi-scoping headings as entity.name.section](https://github.com/victor-gp/cmd-help-sublime-syntax/commit/c35ebe7e6410dcafa01733a74bd5d357ec0493e1). The commits' stat shows a list of the themes that changed (usually for the best).

Of course, there are surely better combinations of (totally unrelated) scopes, to cover the themes built into bat. Mine is just a quick & dirty assignation I may revisit later on.

I hit this one as well:

`MANPAGER="sh -c 'col -bx | bat -l man -p --paging=always --theme=OneHalfDark'" man bash`
![image](https://github.com/sharkdp/bat/assets/58201/9da51ad0-5f04-496d-a8da-9cad95fa6587)

`MANPAGER="sh -c 'col -bx | bat -l man -p --paging=always --theme=OneHalfDark'" man bash`
Much better! 
![image](https://github.com/sharkdp/bat/assets/58201/91c9beb9-5efe-4420-a778-bb6d561b9f82)


With man pages containing code snippets its not too bad:
`MANPAGER="sh -c 'col -bx | bat -l man -p --paging=always --theme=OneHalfDark'" man 2 open`
![image](https://github.com/sharkdp/bat/assets/58201/a9811389-165b-4cb4-ab1d-37895cd0aa34)


But for all command line utils man pages, bat themes do nothing really.

`batman` is also affected by this: https://github.com/eth-p/bat-extras/issues/102
For everyone hitting this issue, this is my workaround:

``` bash
export MANPAGER="sh -c 'col -bx | bat --theme=default -l man -p'"
man 2 select
```

thx. The man 2 select is just an example, I guess.
> thx. The man 2 select is just an example, I guess.

These are the official [instructions](https://github.com/sharkdp/bat#man) on how to use `bat` as a colorizing pager for `man`, I just added `--theme=default` as a workaround to this issue.
I see, but also in the instructions it is as far as I understand an example.
@8FordPrefect8 yes sure, it is just an example to see a colorized man page, and actually I think it should be a more straightforward example, such as `man cp` or similar. On my `Arch Linux` system, if I issue `man 2 select` I get the following message `No manual entry for select in section 2`.
> > thx. The man 2 select is just an example, I guess.
> 
> These are the official [instructions](https://github.com/sharkdp/bat#man) on how to use `bat` as a colorizing pager for `man`, I just added `--theme=default` as a workaround to this issue.

I just tried and `--theme=default` seems to correspond to `Monokai Extended Light` which is unreadable because it uses a dark grey color for text that is very close to the black of my terminal. Using`--theme="Monokai Extended"` works better for me.

-------------

Either way, I'll keep using the [`colored-man-pages`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/colored-man-pages) zsh plugin for the foreseeable future because `bat -l man` coloring is too unreliable for me.

See this comparison for an example:
- On the left `export MANPAGER="sh -c 'col -bx | bat --theme=\"Monokai Extended\" -l man -p'"; man ffmpeg`
- On the right [`colored man ffmpeg`](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/colored-man-pages#colored-man-pages-plugin)

<img width="1389" alt="image" src="https://github.com/sharkdp/bat/assets/2824100/867d54cd-078f-462f-9eda-a8c0b1d5992e">

 

**Edit**: and this is not a theme issue, here is what I see when I use the default theme with `export MANPAGER="sh -c 'col -bx | bat --theme=\"default\" -l man -p'"; man ffmpeg`:

![image](https://github.com/sharkdp/bat/assets/2824100/d98a46e6-793e-4e22-9eb2-70a4209a2628)


Fix patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c05a649a6..fd30fa960d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -75,6 +75,8 @@
 
 ## Themes
 
+- Patched/improved themes for better Manpage syntax highlighting support, see #2994 (@keith-hall).
+
 ## `bat` as a library
 
 - Changes to `syntax_mapping::SyntaxMapping` #2755 (@cyqsimon)
diff --git a/assets/patches/1337.tmTheme.patch b/assets/patches/1337.tmTheme.patch
new file mode 100644
index 0000000000..b927a74f41
--- /dev/null
+++ b/assets/patches/1337.tmTheme.patch
@@ -0,0 +1,22 @@
+diff --git themes/1337-Scheme/1337.tmTheme themes/1337-Scheme/1337.tmTheme
+index fdff5bf..8cfc888 100644
+--- themes/1337-Scheme/1337.tmTheme
++++ themes/1337-Scheme/1337.tmTheme
+@@ -280,7 +280,7 @@ SOFTWARE.
+ 			<key>name</key>
+ 			<string>PHP Namespaces</string>
+ 			<key>scope</key>
+-			<string>support.other.namespace, entity.name.type.namespace</string>
++			<string>support.other.namespace, entity.name.type.namespace, entity.name</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>foreground</key>
+@@ -561,7 +561,7 @@ SOFTWARE.
+ 		    <key>name</key>
+ 		    <string>diff.header</string>
+ 		    <key>scope</key>
+-		    <string>meta.diff, meta.diff.header</string>
++		    <string>meta.diff, meta.diff.header, markup.heading</string>
+ 		    <key>settings</key>
+ 		    <dict>
+ 			<key>foreground</key>
diff --git a/assets/patches/OneHalfDark.tmTheme.patch b/assets/patches/OneHalfDark.tmTheme.patch
new file mode 100644
index 0000000000..1ac3e5e8d4
--- /dev/null
+++ b/assets/patches/OneHalfDark.tmTheme.patch
@@ -0,0 +1,47 @@
+diff --git themes/onehalf/sublimetext/OneHalfDark.tmTheme themes/onehalf/sublimetext/OneHalfDark.tmTheme
+index b16050c..b021071 100644
+--- themes/onehalf/sublimetext/OneHalfDark.tmTheme
++++ themes/onehalf/sublimetext/OneHalfDark.tmTheme
+@@ -28,7 +28,7 @@
+ <plist version="1.0">
+ <dict>
+ 	<key>name</key>
+-	<string>OneHalfLight</string>
++	<string>OneHalfDark</string>
+ 	<key>semanticClass</key>
+ 	<string>theme.dark.one_half_dark</string>
+ 	<key>uuid</key>
+@@ -155,7 +155,7 @@
+ 			<key>name</key>
+ 			<string>Classes</string>
+ 			<key>scope</key>
+-			<string>support.class, entity.name.class, entity.name.type.class</string>
++			<string>support.class, entity.name.class, entity.name.type.class, entity.name</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>foreground</key>
+@@ -188,7 +188,7 @@
+ 			<key>name</key>
+ 			<string>Storage</string>
+ 			<key>scope</key>
+-			<string>storage</string>
++			<string>storage, meta.mapping.key string</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>foreground</key>
+@@ -309,7 +309,7 @@
+ 			<key>name</key>
+ 			<string>Markdown: Headings</string>
+ 			<key>scope</key>
+-			<string>markup.heading punctuation.definition.heading, entity.name.section</string>
++			<string>markup.heading punctuation.definition.heading, entity.name.section, markup.heading - text.html.markdown</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>fontStyle</key>
+@@ -660,4 +660,4 @@
+ 		</dict>
+ 	</array>
+ </dict>
+-</plist>
+\ No newline at end of file
++</plist>
diff --git a/assets/patches/TwoDark.tmTheme.patch b/assets/patches/TwoDark.tmTheme.patch
index 05f1fc6990..b6570fbc7f 100644
--- a/assets/patches/TwoDark.tmTheme.patch
+++ b/assets/patches/TwoDark.tmTheme.patch
@@ -2,6 +2,24 @@ diff --git themes/TwoDark/TwoDark.tmTheme themes/TwoDark/TwoDark.tmTheme
 index 87fd358..56376d3 100644
 --- themes/TwoDark/TwoDark.tmTheme
 +++ themes/TwoDark/TwoDark.tmTheme
+@@ -125,7 +125,7 @@
+ 			<key>name</key>
+ 			<string>Classes</string>
+ 			<key>scope</key>
+-			<string>support.class, entity.name.class, entity.name.type.class</string>
++			<string>support.class, entity.name.class, entity.name.type.class, entity.name</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>foreground</key>
+@@ -290,7 +290,7 @@
+ 			<key>name</key>
+ 			<string>Headings</string>
+ 			<key>scope</key>
+-			<string>markup.heading punctuation.definition.heading, entity.name.section</string>
++			<string>markup.heading punctuation.definition.heading, entity.name.section, markup.heading - text.html.markdown</string>
+ 			<key>settings</key>
+ 			<dict>
+ 				<key>fontStyle</key>
 @@ -533,7 +533,7 @@
  			<key>name</key>
  			<string>Json key</string>
diff --git a/assets/themes/ansi.tmTheme b/assets/themes/ansi.tmTheme
index 957f42bba6..f103b418de 100644
--- a/assets/themes/ansi.tmTheme
+++ b/assets/themes/ansi.tmTheme
@@ -69,7 +69,7 @@
                 <key>name</key>
                 <string>Labels</string>
                 <key>scope</key>
-                <string>entity.name.label</string>
+                <string>entity.name.label, variable.parameter</string>
                 <key>settings</key>
                 <dict>
                     <key>foreground</key>
@@ -80,7 +80,7 @@
                 <key>name</key>
                 <string>Classes</string>
                 <key>scope</key>
-                <string>support.class, entity.name.class, entity.name.type.class</string>
+                <string>support.class, entity.name.class, entity.name.type.class, entity.name</string>
                 <key>settings</key>
                 <dict>
                     <key>foreground</key>
@@ -234,7 +234,7 @@
                 <key>name</key>
                 <string>Headings</string>
                 <key>scope</key>
-                <string>markup.heading punctuation.definition.heading, entity.name.section</string>
+                <string>markup.heading punctuation.definition.heading, entity.name.section, markup.heading - text.html.markdown</string>
                 <key>settings</key>
                 <dict>
                     <key>fontStyle</key>
diff --git a/assets/themes/base16-256.tmTheme b/assets/themes/base16-256.tmTheme
index a4547e564d..b64b444e93 100644
--- a/assets/themes/base16-256.tmTheme
+++ b/assets/themes/base16-256.tmTheme
@@ -257,7 +257,7 @@
                 <key>name</key>
                 <string>Tags</string>
                 <key>scope</key>
-                <string>entity.name.tag</string>
+                <string>entity.name.tag, entity.name</string>
                 <key>settings</key>
                 <dict>
                     <key>foreground</key>
@@ -312,7 +312,7 @@
                 <key>name</key>
                 <string>Headings</string>
                 <key>scope</key>
-                <string>markup.heading punctuation.definition.heading, entity.name.section</string>
+                <string>markup.heading punctuation.definition.heading, entity.name.section, markup.heading - text.html.markdown</string>
                 <key>settings</key>
                 <dict>
                     <key>fontStyle</key>
diff --git a/assets/themes/base16.tmTheme b/assets/themes/base16.tmTheme
index 7b030068ed..b49f81175d 100644
--- a/assets/themes/base16.tmTheme
+++ b/assets/themes/base16.tmTheme
@@ -256,7 +256,7 @@
                 <key>name</key>
                 <string>Tags</string>
                 <key>scope</key>
-                <string>entity.name.tag</string>
+                <string>entity.name.tag, entity.name</string>
                 <key>settings</key>
                 <dict>
                     <key>foreground</key>
@@ -311,7 +311,7 @@
                 <key>name</key>
                 <string>Headings</string>
                 <key>scope</key>
-                <string>markup.heading punctuation.definition.heading, entity.name.section</string>
+                <string>markup.heading punctuation.definition.heading, entity.name.section, markup.heading - text.html.markdown</string>
                 <key>settings</key>
                 <dict>
                     <key>fontStyle</key>


Test patch: