Re: zsh/nearcolor module usage

[Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>]

On Mon, Feb 6, 2023 at 6:54 PM Jim <linux.tech.guy@xxxxxxxxx> wrote:
>
> Unless I missed something, which I may have, I didn't see anything about how to
> use it.

It is a bit obscure.

The expansion of prompts section has a cross-reference

       %F (%f)
              Start (stop) using a different foreground colour,  if  supported
              by  the  terminal.  The colour may be specified two ways: either
              as a numeric argument, as normal, or by  a  sequence  in  braces
              following  the  %F, for example %F{red}.  In the latter case the
              values allowed are as described for the fg zle_highlight  attri‐
              bute;  see Character Highlighting in zshzle(1).  This means that
              numeric colours are allowed in the second format also.

In the section on Character Highlighting, we find

       fg=colour
              The  foreground  colour should be set to colour, a decimal inte‐
              ger, the name of one of the eight most widely-supported  colours
              or as a `#' followed by an RGB triplet in hexadecimal format.

And then in the entry for the nearcolor module

       The zsh/nearcolor module replaces colours  specified  as  hex  triplets
       with  the  nearest  colour  in  the  88 or 256 colour palettes that are
       widely used by terminal emulators.

> % print -P '%F{#ABCB8D}text%f'
>
> Question:  Does anyone know any other ways to use nearcolor?  I tried using the
> parameter expansion flag (%) but nothing I tried worked.

Parameter expansion with (%) should work.
  palegreenpants="%F{#ABCB8D}pants%f"
  print -r -- $palegreenpants

> As I said, unless I missed something, it would also seem useful to add a usage
> example to the man page along with how to load the module.

A reference back to prompts and highlighting would be appropriate.

> BTW, not all virtual terminals seem to use the parameter COLORTERM.
> [...]  If using the example in the man page, nearcolor would
> never have loaded for xterm.

That example is not intended to be exhaustive or necessarily even
correct, it's just showing how to load the module only when some
arbitrary condition is true.  It's up to you to figure out the right
condition to test.  I'm not sure how to express that in the text.