rose-pine-man

rose-pine color theme for man page viewing.

Key features

Rose-pine colors are available for terminal use beyond man colors
Customizable + tweakable truecolor man themes
Functions to help us learn about truecolor terminal colors

Quick Installation

Clone + add to .zshrc

$ mkdir -p ~/.config/zsh/
$ cd ~/.config/zsh
$ git clone https://github.com/const-void/rose-pine-man.git
$ vi ~/.zshrc
...
source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
...
$ . ~/.zshrc
$ man zsh

Want to try other rose-pine themes or a custom one? We got you.

rose-pine-moon

# ~/.zshrc
source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
colorize_man rose-pine-moon

rose-pine-dawn

# ~/.zshrc
source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
colorize_man rose-pine-dawn

customized theme

# ~/.zshrc
source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
colorize_man custom

Please see the tips+tricks section for customization hints!

Credits

oh-my-zsh -- https://github.com/ohmyzsh/ohmyzsh/blob/master/plugins/colored-man-pages/colored-man-pages.plugin.zsh
less termcap -- https://unix.stackexchange.com/questions/108699/documentation-on-less-termcap-variables/108840#108840
terminal truecolor -- https://github.com/termstandard/colors

Try out different themes on the fly!

To try a different theme on the fly:

$ colorize_man rose-pine
$ man zsh
$ colorize_man rose-pine-moon
$ man zsh
$ colorize_man rose-pine-dawn
$ man zsh
$ colorize_man custom
$ man zsh

Terminal notes

Assumptions:

Terminal is truecolor ready...there are NO checks...use your eyes! (for now)
Tested with zsh on OSX w/alacritty
ANSI control character separator is ;
ANSI escape control character is \033

Term notes:

OSX Terminal.app does not support true-color...at all. Avoid for now.

Tips and tricks

Some handy helper functions are included, prefixed with term16m to indicate they require truecolor (16 million colors) support.

To use, invoke functions as commands inside an interactive terminal, and explore color theming!

Color theming takes some trial and error.

Testing

When tweaking colors, it can be helpful to quickly test.

Check out colors used by current color settings / theme...

$ term16m_man_color_test

See all the themes in one go...handy when customizing! Note, this will reset your theme to the default.

$ term16m_man_theme_color_test

Trying out new colors

Want to try different colors? No problem. rose-pine.zsh is intended to be modified by you! You do you.

Theme colors are simply ANSI RGB values separated by ";" stored in the following environment variables:

Variable	Color Value
`MAN_THEME_BG`	Default background color (base)
`MAN_THEME_TXT`	Default foreground color
`MAN_THEME_BG2`	Secondary background color (base+)
`MAN_THEME_UNDERLINE`	Color that replaces underline
`MAN_THEME_BOLD`	Color that replaces bold
`MAN_THEME_BLINK`	Color that replaces blink
`MAN_THEME_REVERSE`	Color that replaces reverse

To change colors, simply set the above to ANSI RGB, where a byte is an integer 0-255.

$ MAN_THEME_<setting>="<red byte>;<green byte>;<blue byte>"
$ man zsh

Try out a completely new color

First, to get a feel for what an ANSI RGB value looks like:

$ term16m_rgb_to_ansi_rgb 255 128 237
255;128;237

Simple enough, right?

We know that finding RGB out in the wild is tough! So we have a helper function to convert hex to r;g;b:

$ term16m_hex_to_ansi_rgb '#ff80ed'
255;128;237

Then set, say, text, to the color you like...MAN_THEME_TXTis super dramatic, so let's try that!

$ MAN_THEME_TXT="255;128;237"
$ man zsh

If things go crazy, reset your theme to one of the defaults

$ colorize_man rose-pine
$ man zsh

Persisting customizations.

Any customization / exploration we have done is temporary.

Lazy way

One way to persist custom themes is to simply override settings in your .zshrc:

$ vi ~/.zshrc
...
source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
MAN_THEME_TXT="255;128;237"
...

While the above works and is quick, we lose the ability to try out themes, and in some cases...could be problematic.

Themeable way

Instead, let's copy rose-pine-man.zsh to somewhere else, so we can make changes to that secondary location, without having our updates overwritten by updates to the rose-pine-man github repository.

Never fear--customizing login shell scripts is a time honored tradition! So let's roll up our sleeves and get to it, and make our theme, truly yours.

Make and use local copy

$ cp ~/.config/zsh/rose-pine-man/rose-pine-man.zsh ~/.config/zsh/custom-man.zsh
$ vi ~/.zshrc
...
# source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
source ~/.config/zsh/custom-man.zsh
colorize_man custom
...
$ . ~/.zshrc

If we ever need to revert back, comment the line containing custom-man.zsh and uncomment rose-pine-man.zsh.

Applying custom colors

Locations intended for us to customize have been identified by a CUSTOMIZE-FOR-YOU token. For custom colors, there are two steps:

Add your custom color
Apply your custom color to the custom theme

Add custom color

The first step is to add custom colors..look for the second CUSTOMIZE-FOR-YOU token, and add your own colors!

$ vi ~/.config/zsh/custom-man.zsh
...
##
# CUSTOMIZE-FOR-YOU
# suggest prefixing with my_<color name> but...you do you!
my_hot_pink="255;128;237"
my_color_name_1="<r>;<g>;<b>"
my_color_name_2="<r>;<g>;<b>"
my_color_name_3="<r>;<g>;<b>"
...

Apply custom color

Now let's add our new custom colors to the custom theme. Look for the first CUSTOMIZE-FOR-YOU token, and update with your desired color combination!

...
##
# CUSTOMIZE-FOR-YOU
#   Modify the below with your own colors!
#   Suggest using variables, but feel free to use <var>="r;g;b"...you do you!
"custom")
  export MAN_THEME_BG=$my_color_name
  export MAN_THEME_TXT=$my_hot_pink
  export MAN_THEME_BG2=$rose_pine_highlight_med
  export MAN_THEME_UNDERLINE=$my_other_color_name
  export MAN_THEME_BOLD=$rose_pine_iris
  export MAN_THEME_BLINK=$rose_pine_love
  export MAN_THEME_REVERSE=$rose_pine_rose  
...

Try custom theme out

Save, reload via . ~/.zshrc, and try it out!

A common pattern is recommended to make edits in one terminal window or with one editor, and in another terminal window, reload and try out the changes!

$ . ~/.zshrc
$ colorize_man custom      #just in case we missed a step...
$ term16m_man_color_test
$ man ls

Update default theme

We have put good work into our custom theme, so let's update custom-man.zsh to use our custom theme by default. Doing so will also make your .zshrc process a tiny bit faster.

Using the editor of your choice...

Change from:

function colorize_man() {
  local theme="rose-pine" #default
  ...

To:

function colorize_man() {
  local theme="custom" #default
  ...

Update your .zshrc...no need to specify custom!

...
# source ~/.config/zsh/rose-pine-man/rose-pine-man.zsh
source ~/.config/zsh/custom-man.zsh
...

Remember to reload your .zshrc:

$ . ~/.zshrc
$ term16m_man_color_test
$ man ls

Create new themes

To apply new themes...this part is not so elegant and...may change in the future! But, for the adventurous...read on!

First, decide on a theme name; remember, kebab-case looks nice! From here:

Next, we will add our theme name such that colorize_man recognizes the parameter.
Next, add your theme to colorize_man
Finally, add your theme to term16m_man_theme_color_test

Add your new theme to the list of recognized themes

...
 case "${theme_input}" in
      ...
      "my-theme-name") theme=${theme_input}
      ;;
      ...
...

Add your theme

...
    "my-theme-name")
      export MAN_THEME_BG=$color1
      export MAN_THEME_TXT=$color2
      export MAN_THEME_BG2=$color3
      export MAN_THEME_UNDERLINE=$color4
      export MAN_THEME_BOLD=$color5
      export MAN_THEME_BLINK=$color6
      export MAN_THEME_REVERSE=$color7
    ;;
...

Add your theme `term16m_man_theme_color_test()`

function term16m_man_theme_color_test() {
  ...
   term16m_man_theme_test my-theme-name
  ...

Test out your theme

Remember to reload your .zshrc:

$ . ~/.zshrc
$ color_man my-theme-name
$ term16m_man_color_test
$ man ls

How it works

man colors are applied via the less pager. For whatever reason, the less pager has undocumented environment variables that apply arbitrary text strings (that we have chosen to render true-color enabled ANSI terminal tokens) to different bits and pieces of the source man documents.

Note that environment variable names are case sensitive!

Less environment variable	Function
LESS_TERMCAP_md	Activate bold
LESS_TERMCAP_mb	Activate blink
LESS_TERMCAP_me	Inactivate bold/blink
LESS_TERMCAP_so	Activate stand-out
LESS_TERMCAP_se	Inactivate stand-out
LESS_TERMCAP_us	Activate underline
LESS_TERMCAP_ue	Inactivate underline

Note that setting a global export LESS_TERMCAP_md can negatively impact other colorization functions that feed text through less - for ex, chroma / pygments etc can render askew.

Instead of setting these environment variables globally, we use the zsh builtin env - this allows us to pass in an array of settings that apply once, to a specific command, and protect the global less environment from our man color shenanigans.

We bundle all of the above in a function man()...this way, we have better control over how the actual man command executes...including the ability to set a different default background/foreground text value!

To-Dos

Document how to use beyond man
Theme check / application is inelegant - load from ~/.config/zsh/theme
Confirm linux compatibility
Confirm bash compatibility

const-void/rose-pine-man

rose-pine-man

Key features

Quick Installation

rose-pine-moon

rose-pine-dawn

customized theme

Credits

Try out different themes on the fly!

Terminal notes

Tips and tricks

Testing

Trying out new colors

Try out a completely new color

Persisting customizations.

Lazy way

Themeable way

Make and use local copy

Applying custom colors

Add custom color

Apply custom color

Try custom theme out

Update default theme

Create new themes

Add your new theme to the list of recognized themes

Add your theme

Add your theme term16m_man_theme_color_test()

Test out your theme

How it works

To-Dos

Add your theme `term16m_man_theme_color_test()`