`--colors=` option is missing from `--help` and `man` pages

[Winterhuman]

I rediscovered this option after seeing #409, and realised it was because it's not officially documented anywhere.

[Disonantemus]

You're right, I did test that and works, and is not in both places.
But you can do the same with:

CLI help:

$ pngquant 2>&1 | sed -n '3,4p'
usage:  pngquant [options] [ncolors] -- pngfile [pngfile ...]
        pngquant [options] [ncolors] - >stdout <stdin

Man page:

$ man pngquant | sed -n '6,7p'
       pngquant ⟨options⟩ [ncolors] file [file ...]
       pngquant ⟨options⟩ [ncolors] - <file >file

Comparing [ncolors] and --colors=:

$ magick logo: 1.png
$ pngquant --colors=5 --output 2.png -- 1.png
$ pngquant 5 --output 3.png -- 1.png
$ md5sum 2.png
475f59c84f78d3ab5af996cfa2811742  2.png
$ md5sum 3.png
475f59c84f78d3ab5af996cfa2811742  3.png

Same result.

[kornelski]

The first argument being the number of colors is there only as a hack for backwards compatibility.

The quality setting is meant to be a better replacement for the number of colors, because it will reduce colors only when it makes sense for a given image.

In either case, reducing the number of colors isn't nearly as beneficial as it may seem.

If you reduce to 128 colors, you already halve the quality, but save only 1/8th of the data.

PNG doesn't even have dedicated pixel modes between 4 and 8 bits (for a good reason - anything other than 8 doesn't compress as well).

At 4 bits you get 50% of the data size, but only 6.3% of the palette. Such a low number of colors needs more of an artistic reimagination than an algorithmic reduction.

So basically the default 256 is already the sweet spot that gives the maximum quality and aligns best with the compression algorithm.

[Disonantemus]

If the image is a photo, maybe --quality 98 or --posterize 2 still looks ok.

With a drawing with a few colors, I can get to --quality 20 or --posterize 4 and is ok.

Depends on the image, but I agree that is better use quality or posterize, that use MSE (difference statistic vs original), yo can see better using: --verbose.