Stop using ASCII quotation marks in compiler messages

[MisterDA]

Hi!
I got this error message:

File "lib/docker.ml", line 1:
Error: The implementation lib/docker.pp.ml
       does not match the interface lib/.obuilder.objs/byte/obuilder__Docker.cmi:
        ... In module Cmd:
       The value `run_result'' is required but not provided
       File "lib/s.ml", lines 183-190, characters 2-68: Expected declaration

The fact that my variable ends with a single quote makes the error message look somewhat weird, since two single quotes follow each other. imho it looks ugly everywhere too (but who am I to judge, I often use emoji).

There is also a recent trend of removing the ASCII quotes `…' in favour of Unicode quotation marks. See ASCII and Unicode quotation marks for a comprehensive history of the question and rationale for the change.

[gasche]

Not sure about unicode quotation marks:

• As a general issue with non-ASCII characters, they will break some environments (the syntax highlighting or typo detector of some web HTML form, LaTeX sources, etc.) which add up to a cost.
• The confusion comes from your code defining run_result', that is using a character that is also used for quotation marks. Today unicode quotes feel good because they cannot be used in OCaml code, but what will we do when unicode characters become usable in OCaml code?

Here one option would be to simply use parentheses: the value (run_result') is required but not provided. It looks a bit heavier on the eye, but it's one of the more robust forms of "I'm moving to indirect discourse" in ASCII. (And it works for any piece of OCaml code we want to include in error messages, possibly with the nice touch of not re-parenthesizing already-parenthesized expressions.)

[dbuenzli]

I don't think it's a good idea to stop quoting. I think it's good to stop doing `…' which is nowadays ugly (it used not to be the case, as mentioned in the link above).

Since the compiler has access to isatty (For cmdliner I wish that one would be in Sys btw.) I would suggest to use '…' when no colors are requested and bold when colors are available, that's the manpage convention for as-is and user input text (basically equivalent of markdown's ` `).

Unicode quotes are an option, broadly I don't think they would pose problem see the discussion here, but that's the kind of change you only really get to know it was problematic after you made it and people start showing up on your issue tracker…

[gasche]

I like the idea of using bold! We also had an issue for using bold and/or colors in type error messages, #10321.

If anyone is interested in improving this topic, I would suggest sending a PR that uses bold when applicable/possible, and keeps the current ASCII quoting otherwise. This is the most likely to be uncontroversial and get merged, and then we can have discussions on even better proposals turned into further PRs.

[xavierleroy]

There is no strong need to quote identifiers in error messages. Many OCaml error messages don't do it and it's fine:

# let x = y' + 1;;
Error: Unbound value y'

But I agree it would be even nicer if y' was in bold face or in a different color.

ASCII double quotes are barely acceptable:

Error: Unbound value "y'"

Other ASCII options are just awful:

Error: Unbound value 'y''
Error: Unbound value `y''
Error: Unbound value ``y'''

If Unicode is available, French guillemets win:

Error: Unbound value «y'»

But, again, quotes aren't really needed, even more so if bold or color are used.

[shindere]

Can we please keep accessibility in mind while discussing these matters?

FWIW, neither colors nor bold, underline, italics are easily rendered in
braille or for users of speech synthetizers.

I am not very excited by unicode either because at the moment it is likely
that Unicod quotation marks will be rendered as quesiton marks in braille
because they have no defined translations in braille tables.

[gasche]

I believe that we have configuration tweaks to not use colors in the display. (This is done explicitly if the terminal is detected to be too primitive, but users can also set it explicitly.) In particular, colors should be disabled if the NO_COLOR environment variable is set ( see #10560 ). I would expect a good implementation of 'use colors instead of quotation marks' to revert to quotation marks in this case. That being said, I don't know what is the treatment of bold (currently we don't use bold without colors); I would consider it a color, but this is not completely obvious.

[dbuenzli]

I think that using bold for when colors are requested and single quotes when they are not is an accessible solution.

[dbuenzli]

That being said, I don't know what is the treatment of bold (currently we don't use bold without colors); I would consider it a color, but this is not completely obvious.

"Colors" in the context of terminals means anything that uses ANSI terminal escape sequences (which includes bold) rather than plain text.

[shindere]

Many thanks for your contribution, @gasche. I just wanted to raise the question of what should be the default behaviour. I do realise that one approach is to sue as defautl behaviour the one that suits most people and it of course makes sense to do it that way. On the other hand, having something that is not accessible by default and needing users to do configuration steps that may be obscure to them also feels a bit suboptimal.

[shindere]

Daniel Bünzli (2022/10/25 08:38 -0700):

I think that using bold for when colors are requested and single quotes when they are not is an accessible solution.

Somehow yes, maybe. Just that I don't know how obvious it is for users how to disable colors in their environment. I also don't know how portable the `NO_COLORS` variable is.

[dbuenzli]

Just that I don't know how obvious it is for users how to disable colors in their environment.

Usually people who do not want colors know that setting TERM=dumb will suppress them from well behaved tools (ocaml does).

I also don't know how portable the NO_COLORS variable is.

There's no portability problem (unless your system doesn't support getenv). Whether to output ANSI escape sequences is under the control of the compiler, the exact logic of when it does is properly documented in the manual under the -color option.

[Octachron]

One important aspect to keep in mind is that we can start by adding a format style for inline code or quoted text in order to have one clear notion of quoting in error messages which would already improve the current situation where different error messages use different style for quoting. Then we could choose later how the style is rendered.

@shindere : in term of accessibility, since OCaml error messages but also quite a few CLI commands use colored CLI output by default, I imagine that your settings is either filtering terminal escape sequences or is already set in a TERM=dumb or NO_COLOR mode. Do you know which option is it?

[shindere]

Daniel Bünzli (2022/10/26 07:23 -0700):

> I also don't know how portable the `NO_COLORS` variable is. There's no portability problem (unless your system doesn't support `getenv`).

Sorry, I meanst, how many programs actually take this variable into account.

[gasche]

NO_COLOR is a sort of informal standard, see https://no-color.org/, which contains a long-ish list of software supporting it, and also many terminal libraries used by many other software. (I realize that we should add OCaml to this list.)

[shindere]

Florian Angeletti (2022/10/26 07:31 -0700):

@shindere : in term of accessibility, since OCaml error messages but also quite a few CLI commands use colored CLI output by default, I imagine that your settings is either filtering terminal escape sequences

Yes, merely they are ignored by brltty. Wellnot exactly ignored, rather, not even seen because brltty looks at `/dev/vcsa` which only has the characters (and the attributes, I think) because the escapbe sequences have already been interpreted at this stage.

or is already set in a `TERM=dumb` or `NO_COLOR` mode.

I have `TERM=linux` on my machine, and nothing else with respect to colors as far as environment variables are concerned. The only tool for which I did need to disable colors is git, so in my `~/.gitconfig` I have a `[color]` section with just one setting: `ui = off`.

Do you know which option is it?

I hope I replied to your question?

[shindere]

Oh! Thanks a lot for the link!

[dbuenzli]

Sorry, I meanst, how many programs actually take this variable into account.

Ah that new NO_COLOR "standard" was a pretty bad idea in the first place. Someone else said it better than I would.

In general the combination of cli switches (-color in ocaml), a program specific variable (OCAML_COLOR, in ocaml) and the TERM=dumb + isatty(2) detection logic is already plenty enough.

But someone thought it was a good idea to add one more way for a reason that escapes me – it's pretty clear that this problem is being solved at the wrong level (i.e. your terminal emulator should be in charge of that problem).

[Octachron]

@shindere Thanks for your answer! Taking in account your settings, I have the impression we cannot rely on the TERM settings to know if we can use only colors in the cases where quotes are absolutely required.

Maybe in this case, we could use both double quotes and bold ("rec") except if colors were explicitly requested (with -color or OCAML_COLOR). The other options is to just homogeneously use double quotes in the error messages.

However, when quoting would be only a nicety, I think it is probably fine to use bold directly as a improvement for many users that doesn't impair readability for anyone.

(If my memory is right @shindere when we discussed the issue previously the conclusion was that there was simply no real equivalent to this kind of quickly scanned text decoration on a braille terminal)

[shindere]

You are indeed correct that there is nothing that would make it as easy to scan a text in braille as it is when reading with eyes. One situation where quoting may be useful is when the text is not just an identifier but an expression with spaces etc. In this situations, quoting may be helpfull. Also, I remember having thought at several occastions that I found the idio `this expression` in error messages not that useful and that I would have preferred `the expression` followed by the expression itself.

[gasche]

I think that this issue was either solved or made irrelevant by #12210, which stopped using `foo' for quoting source in compiler error messages.