Original title: Light text over dark background isn't respected (linux)

Describe the bug

Whenever I install SMAPI, or run stardew, the outputted text as its color scheme forced. From what I can tell, it's the C# software output that is to blame. Normally, you shouldn't need to force a color scheme on the text output and if you do, you'd need to use the system colors.

On the first screenshot, you can see the "black" color to be in fact grayish and different from the background. That is how my urxvt is configured. However SMAPI spawn a xterm window (2nd screenshot) which have a different color scheme. Black is black and would thus render the text unreadable (3rd screenshot).

To Reproduce

1. Download SMAPI
2. install on a linux OS using a terminal emulator with a black background.

Log file

Not applicable.

Screenshots

SMAPI shows log levels with a standard color scheme for all mods. The gray text in that screenshot is DEBUG level, which is deliberately grayed out so the white text (INFO) stands out.

If Linux provides a way to color-code message levels out of the box I'd be interested to know, since this is what's available in the .NET framework:

The default color schemes are defined in the smapi-internal/config.json file (search for ConsoleColors), so you can override it (ideally using a config.user.json file) if you override the meaning of color codes.

SMAPI shows log levels with a standard color scheme for all mods.

I don't know what standard is being used here, if not your own. The issue isn't really with a standard itself, but on how hard it is to read the output.

The gray text in that screenshot is DEBUG level, which is deliberately grayed out so the white text (INFO) stands out.

With a dark background, shouldn't the grayed out section be LightGray instead of DarkGray? Would make stuff actually readable. Using xterm, the text is actually black though. I suspect something to do with TERM not expressly saying it supports 256 colors.

If Linux provides a way to color-code message levels out of the box I'd be interested to know, since this is what's available in the .NET framework

It isn't really Linux per say, but more about the shell environment. Bash (Bourne-Again Shell) being commonly used while other exists, such as zsh (Z shell). Bourne is simply the name of the inventory: Stephen Bourne. But I digress, the point is that there are many shells in the wild.

As such, the standard isn't to color code output but to make use of io redirection when required. Any errors should be sent to stderr, while the rest will be happy in stdout. It is quite trivial for the user to filter the output this way. If you really want to use colors, you would need to use bright colors when a dark background is used and reversely, dark colors on a white background.

If a software can be more verbose than necessary, it is usual to provide a flag the user can set in order to get more information. You'd commonly see --verbose or -v be used, multiple verbose flags used would increase the level of verbosity up to DEBUG mode. It really depends on the software itself as to how it is implemented. Some would instead provide a quiet flag to reduce the verbosity.

In the case of SMAPI and Stardew valley, I do consider the color coding to be a defect for the following reason. Launching the game, SMAPI output in black (debug) that some of the mods I use may be outdated. That is a very useful information to know, yet it is hidden by default (highlighting the text simply create a black on black area).

The case about installation

Color could be used, or not used. But if information is needed for debug, a log file containing such information would be more useful than simply writing to the shell.

tee¹ can be useful in this case, and doesn't require invasive changes.

if $COMMAND mono >/dev/null 2>&1; then
     mono internal/unix-install.exe | tee install.log
fi

The case about game launching

While always useful, simply using a log file as remedy wouldn't be satisfying. Still, a log file should be created as the terminal window disappear once the game ends. If there is a log somewhere, I haven't seen it.

As seen in the screenshot above, the debug output isn't readable because written in black. I assume the .NET framework to use the ANSI escape code or possibly tput. Thus the color being used are simply not a fit for the background. Avoid dark on dark or bright on bright.

I need to be able to comfortably read the warning information.

SMAPI shows log levels with a standard color scheme for all mods.

I don't know what standard is being used here, if not your own.

It's a standard color scheme applied across all SMAPI mods, meaning that individual mods can't specify the colors to use. It's not a standard in the sense of "web standard" or "Linux standard".

With a dark background, shouldn't the grayed out section be LightGray instead of DarkGray?

LightGray doesn't exist. Unfortunately there's a very limited set of colors available out of the box.

As such, the standard isn't to color code output but to make use of io redirection when required.

The SMAPI console is an interactive tool which lets players see at a glance when something is wrong, enter commands, review their installed mods, see update alerts, etc. It's not a general Unix command or utility, and I don't expect that the average player will be redirecting console output.

SMAPI is also crossplatform across Android, Linux, Mac, and Windows which have different conventions and standards; so something that's standard on Linux might be tricky to do in a crossplatform way.

If a software can be more verbose than necessary, it is usual to provide a flag the user can set in order to get more information. [...] Some would instead provide a quiet flag to reduce the verbosity.

SMAPI is in quiet mode by default (though some mods might log more than they should). Enabling DeveloperMode in smapi-internal/config.json (or installing the SMAPI for developers download) increases output, and other config options like VerboseMode can make it very verbose.

But if information is needed for debug, a log file containing such information would be more useful than simply writing to the shell.

SMAPI does have a log; the console is just a filtered, simplified, and color-coded view of what's being logged. For the vast majority of players that's more accessible than the raw log file.

As seen in the screenshot above, the debug output isn't readable because written in black.

Agreed, the black on black is an issue. It's hard to avoid automatically though, since Linux users can redefine colors and SMAPI has no way to detect that. Support for overriding the color scheme (and saving it across updates) was added specifically to support Linux players who do this.

LightGray doesn't exist. Unfortunately there's a very limited set of colors available out of the box.

They have to use standard ANSI escape code, otherwise I wouldn't see any colored output. It may not be available in the Enum, though they're missing 240 other colors. The ANSI color specs has white (which is a shade of gray) and bright white (actual white). So it may be under different names in the .NET doc. Just like Black (actual black) and Bright Black (dark gray). More on that.

Seems like Microsoft loves to redefine stuff needlessly.

so something that's standard on Linux might be tricky to do in a crossplatform way.

You have a shell script for nearly each platform though. When I first came across the color issue, I went into the shell script to see if I could resolve it ; without success since the text output comes directly from a binary.

However I do understand the meaning of it: can't use platform specific features if you are to publish one binary. Would be silly to multiply the efforts anyhow.

SMAPI does have a log;

Another thing I didn't know :)

Would it be possible to install a readme file, using an obvious name like readme.smapi.txt, with the various information you've given me here? Namely: config file, log location, other light usability information.

Agreed, the black on black is an issue. It's hard to avoid automatically though, since Linux users can redefine colors and SMAPI has no way to detect that.

But it does, I answered "light text on dark background" during installation. So SMAPI knows I use a dark background... I can redefine the ANSI colors on a per terminal basis. By default the terminal backgrounds are black, but those can be changed by simply changing the black color to another kind of color. Thus, if you follow the color scheme (0 - black, as background), it would be very hard to end up with something unreadable. On my end, black isn't black but a shade of grey. Another way to circumvent the problem is to define a background color.

Don't forget that you can also reset the color, and not forcing anything, so you don't have to output text in black if you want to no color. Console.ResetColor(); if I read the documentation correctly, or a print of \033[0m.

Anyhow, the color in terminals is an old issue which has been resolved by older and wiser people than us ;)

Yep, but I noticed Console.ResetColor() resets to the color it thinks the terminal is using, rather than sending an actual reset code. That might be because Windows doesn't have an equivalent reset code.

You know, just for this kind of nonsense, I'm glad I've stopped using Microsoft products. Would there be a way to disable colors altogether? By setting an environment variable maybe.

The "player guide" button on the download page links to the modding wiki which covers install steps, FAQs, troubleshooting, log location, etc. (It doesn't cover the internal config since that's not usually meant to be edited directly, but it's documented in the file directly.)

I don't know. I usually don't go on the internet once I downloaded a package as I assume everything I need to know is in the archive or will be installed. The script extender for bethesda games does just that with packaging some documentation. Wikis are usually too big, too bloated and necessitate constant monitoring in order to maintain the information they contain. I've grown to appreciate good old html based documentation, usually auto-generated with sphinx or hosted on https://readthedocs.org/. You can get some pretty impressive documentation that way. Using a git repository to maintain the documentation is a less chaotic way to handle a wiki.

For example, on this page, the link to the troubleshooting page about the SMAPI log is broken. I remember having checked that page months ago. Couldn't fix it as I didn't know the information itself.

So we could add info there about overriding the color scheme (maybe on the troubleshooting page?).

My preferences remain a readme that tackles the basics once SMAPI is installed:

1. About smapi
2. Where to install mods
   in the Mods folder, duh!
3. How to configure smapi
   There is a smapi-internal/config.json file
4. Platform specific information
   log location, colors, terminal emulators, others?
5. Where to find more information (link to wiki)

They have to use standard ANSI escape code, otherwise I wouldn't see any colored output. It may not be available in the Enum, though they're missing 240 other colors.

The benefit of using .NET console APIs (instead of ANSI codes directly) is that they handle each OS' implementation without needing us to special-case them in the SMAPI code. SMAPI only needs seven colors at most, so the limited set available is fine.

You have a shell script for nearly each platform though.

The shell script is just a minimal launcher (derived from the game's launcher); everything else is in the binary.

Don't forget that you can also reset the color

Yep, but I noticed Console.ResetColor() resets to the color it thinks the terminal is using, rather than sending an actual reset code. That might be because Windows doesn't have an equivalent reset code.

Would it be possible to install a readme file, using an obvious name like readme.smapi.txt, with the various information you've given me here? Namely: config file, log location, other light usability information.

The "player guide" button on the download page links to the modding wiki which covers install steps, FAQs, troubleshooting, log location, etc. (It doesn't cover the internal config since that's not usually meant to be edited directly, but it's documented in the file directly.) So we could add info there about overriding the color scheme (maybe on the troubleshooting page?).

Would there be a way to disable colors altogether? By setting an environment variable maybe.

Sure, I'll add a None color scheme in the next update:

Wikis are usually too big, too bloated and necessitate constant monitoring in order to maintain the information they contain.

SMAPI is usually a one-person project, so a wiki lets the community help maintain documentation. The example you linked to is a wiki — just one changed through pull requests instead of page saves.

For example, on this page, the link to the troubleshooting page about the SMAPI log is broken.

Fixed!

My preferences remain a readme that tackles the basics once SMAPI is installed:

I've found that few users look at bundled readmes. Online pages are more accessible to most players, and they can link to more detailed info (e.g. troubleshooting or creating a mod) were needed. Since SMAPI has one codebase, that also makes it easier to provide platform-specific info without having to include every platform in the readme. I appreciate the desire for a nice man-style doc with everything in one place, but I don't think that's not the format most players would benefit most from.

Sure, I'll add a None color scheme in the next update

That non-existent color scheme could be selected with the install script, as a third option alongside Dark and Light.

The example you linked to is a wiki — just one changed through pull requests instead of page saves.

Yes, that's what I tried to convey. The wiki as it is contains too much information for nearly all possible case, unless it's just a giant and well maintained Q&A. But this discussion isn't within the scope of this issue :)

That non-existent color scheme could be selected with the install script, as a third option alongside Dark and Light.

Possibly, but I think it's rare enough that we could just have it as a config option. (Especially since it's generally only useful on Linux, where users are more familiar with config files.) You'd just need to create a smapi-internal/config.user.json file with this content:

{
   "ConsoleColors": {
      "UseScheme": "None"
   }
}

The installer doesn't change that file, so it'll be remembered across SMAPI updates.

Added in develop for the next SMAPI update.