batman: Document issues with non-default themes

doc/batman.md

@@ -21,6 +21,21 @@ If you have `fzf` installed, you can even use `batman` to search through manual
 
 
 
+## Customization
+
+### Changing the Theme
+
+You can change the syntax highlighting theme for `batman` by setting the `BAT_THEME` environment variable before calling `batman`. The following wrapper function will change the theme to `Solarized (dark)` without affecting any other `bat` command.
+
+```bash
+batman() {
+    BAT_THEME="Solarized (dark)" batman "$@"
+    return $?
+}
+```
+
+
+
 
 ## Installation
 
@@ -28,6 +43,18 @@ This script is a part of the `bat-extras` suite of scripts. You can find install
 
 
 
+## Caveats
+
+**Flags aren't highlighted:**
+
+- This happens when you change `bat`'s theme through `bat`'s config file or the `BAT_THEME` environment variable. Not all themes provide colours for flags, and [it's a known issue](https://github.com/sharkdp/bat/issues/2115).
+- You can overriding the theme for `batman` by wrapping it in a function that sets `BAT_THEME`.
+- The following themes support manpage highlighting:
+  - `Monokai Extended` / ``Monokai Extended Light`
+  - `Solarized (dark)` / `Solarized (light)`
+
+
+
 ## Acknowledgements
 
 Thanks to [@sharkdp](https://github.com/sharkdp) and [@LunarLambda](https://github.com/LunarLambda) for debugging how to make this work properly in [certain environments](https://github.com/sharkdp/bat/issues/652).