[m-dev.] where to document color schemes

[Julien Fischer]

On Sat, 15 Jun 2024 at 11:24, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> The option --color-scheme and the envvar MERCURY_COLOR_SCHEME
> both need to document the syntax we use for color schemes.
> I could include the documentation of color schemes in either
> the documentation of the option or the documentation of the envvar,
> with a pointer from the other, but neither feels right, partially because
> of the asymmetry, and partially because describing what color schemes *are*
> and how they can be specified requires much longer text than the
> documentation of pretty much all other options and envvars.
> (I know, because I have been writing it today.)
>
> Would anyone object if I documented color schemes in a new
> section of the user guide, probably added after the current section 10
> which is Environment variables, with a link there from both the option
> and the envvar? I am thinking calling it "Color in diagnostics",
> and it would explain both color schemes and the algorithm we use
> to decide whether to use colors at all.

I have no objection to having a separate section for them.

> Does anyone have a better idea?

It is conceivable that we may add other options / envvars to control
the compiler's
diagnostic output, so I suggest having a new separate section, e.g.
"Diagnostic Output",
to cover all of them, with the documentation of color output being part of that.

(In fact we already have some other options for controlling aspects of
diagnostic
output, --max-error-line-width, --reverse-error-order.)

Julien.