#2520 PR merged: Better wording in user messages about keyboard issues

Labels: enhancement, fixed / solved / done

jsmeix opened issue at 2020-11-18 08:27:

Works well for me.
On my openSUSE Laep 15.1 system I get during "rear -D mkrescue"

Included current keyboard mapping (via 'dumpkeys -f')
Included fallback US keyboard mapping /usr/share/kbd/keymaps/legacy/i386/qwerty/defkeymap.map.gz
Included other keyboard mappings in /usr/share/kbd/keymaps

But I did not test the various failure cases.

  • Brief description of the changes in this pull request:

Inform the user about possible issues with keyboard usage in the recovery system
but use neutral wording for those user messages to avoid false alarm
except when it fails to include the current keyboard mapping
(which is no fatal Error because the US keyboard mapping is included as fallback).

The actual reason behind why the changes here are needed is
that it seems newer Debian-based systems (including Ubuntu)
no longer contain any keymaps directory as part of the base system, cf.
https://github.com/rear/rear/issues/2519#issuecomment-729264699
so those distros do no longer provide console-multi-keyboard support by default.
In such cases ReaR aligns with what there is without being needlessly verbose.

If the distro provides console-multi-keyboard support, ReaR includes it (without being verbose).
If the distro has decided that this is not necessary, ReaR aligns with it (without being verbose).
If the user has installed multi-keyboard support, ReaR aligns with it (without being verbose).
Cf. https://github.com/rear/rear/pull/2520#issuecomment-729681053

Only when including the current keyboard mapping failed (i.e. when 'dumpkeys' failed)
it shows subsequent messages on the user's terminal in any case (via LogPrint and LogPrintError)
but normally it shows subsequent messages only in debug mode (via DebugPrint).

OliverO2 commented at 2020-11-18 11:35:

Thanks for picking this up. I'm now getting these messages on Ubuntu:

No fallback US keyboard mapping included (no KEYMAPS_DEFAULT_DIRECTORY specified)
No support for different keyboard layouts (neither KEYMAPS_DEFAULT_DIRECTORY nor KEYMAPS_DIRECTORIES specified)

The wording is certainly better, but it still gives the impression that something might be wrong here (in particular, as these are the only messages appearing). More importantly:

  • The motivation for these messages may not be apparent to users (see below).
  • The messages lack guidance on what to do about it.

Now I try to put myself into two different user's shoes:

  • US keyboard user
    • "I have a US keyboard. Is this not included? What is a fallback? Why should I care about different keyboard layouts at all?"
  • German keyboard user
    • "I have a German keyboard and never touched anything else. I have heard from the older guys that there was a time when US keyboards were seen in Germany. Not these days. Why would there be a need for some "fallback"?"

So of course, your mileage may vary, but you get the idea.

ReaR's Coding Style says:

Unless usr/sbin/rear was launched with '-v' or '-d' or '-D' there should be no output on the user's terminal.

Schlomo says in WARNING is a waste of my time:

WARNINGS for most cases only create extra manual work because somebody needs to go and check some log file and decide if there actually is a problem.

Note: It does not really matter if the word WARNING appears. Someone has to make a decision. If there are two messages, that means spending time on two decisions. In addition, if there are no directions, if means investing more time to research the issue.

To summarize:

  • The keyboard issues might no longer be relevant today with ssh use for rack servers and non-local keyboards being the rare exception elsewhere.
  • The notion of having a "fallback keyboard" may not be clear to users.
  • If ReaR runs on a system configured for a US keyboard, the message No fallback US keyboard mapping included is wrong. The standard keyboard is the "fallback keyboard".

My conclusions:

  • Two messages is at least one too much.
  • ReaR should not simply complain but rather provide helpful guidance on what to do.

Consider my suggestion in https://github.com/rear/rear/issues/2519#issuecomment-729264699:

TIP: To support different keyboard layouts, see 'KEYMAPS_DEFAULT_DIRECTORY' in 'default.conf'.

With a message like this, you could put in additional commentary in default.conf explaining the situation better than any message could do. There you could describe why a different keyboard layout might need to be supported and what could be done about it (e.g. installing packages, setting variables).

jsmeix commented at 2020-11-18 12:31:

@OliverO2
thank you for your comments!
I will need some time to think about it.
As always sleeping over it should help me.

Unless usr/sbin/rear was launched with '-v' or '-d' or '-D'
there should be no output on the user's terminal
of course unless there is something important to say to the user
and because of the reasons in https://github.com/rear/rear/pull/1781
my current personal opinion is that messages about possible issues
with the keyboard in the recovery system are important to notify
the user in any case.

I may consider your suggestion if at least the TIP was removed
for example something like

To include different keyboard layouts set KEYMAPS_DEFAULT_DIRECTORY (see default.conf)

because personally I hate it when computers give me (unsolicited) tips
what those machines "think" that I should preferably do.
"Shut up I am 'root' - I know what I do" ;-)

jsmeix commented at 2020-11-18 13:21:

Via
https://github.com/rear/rear/pull/2520/commits/c166e4dd8ae2617df1aa750f1d3e62d0a06b34ba
only when 'dumpkeys' failed it shows subsequent messages on the user's terminal in any case.

@OliverO2
does in now behave better in your environment?

I don't like it so much now because now the code looks somewhat oversophisticated.
But I like to find out how to get your needs any my needs aligned as far as possible.

OliverO2 commented at 2020-11-18 13:36:

@jsmeix
Wow, that must have been a short night! ;-)

I would not call it over-sophisticated, but user-friendly: ReaR now follows what Linux distributions have decided (and what their users now are used to). If the distro includes console-multi-keyboard support, ReaR has it (without asking). If the distro has decided that this is not necessary, ReaR aligns with that decision. If a user has decided to install multi-keyboard support, ReaR again will pick it up. Looks just right.

I ran the new code on my Ubuntu system and now there is no output appearing. Ideal from my point of view. ReaR does the right thing, I can relax. ;-)

This is what a had just written before your new commit came in:

Take your time!

Now I see that you consider "TIP" as some imperative from a machine pretending to know better. I have never thought of it that way. For me "TIP" is just a friendly reminder because the machine does not know what you might want to do and you might not know what the machine has in store for you. ;-) I stuck with "TIP" because there are many places in ReaR where this is used and I wanted to be consistent.

I usually get upset if software starts to throw nonsense at me or if its programmer was too lazy to figure out what is going on, back-delegates the decision to me and fails to provide me with necessary information.

jsmeix commented at 2020-11-18 13:48:

@OliverO2
thank you for your prompt reply.
I will sleep over it nevertheless and
if I am still satified with it tomorrow I will "just merge" it.

Regarding the wording TIP:

I perceive the wording "TIP" as some kind of patronizing behaviour from a machine.

For the fun of it a side note:
I had an uncle in Westphalia https://en.wikipedia.org/wiki/Westphalia
who told me that one of the things that he doesn't like is
"a good advice from someone else when things went wrong"
and what makes him even angy is
"a good advice that is true from someone else when things went wrong"
;-)

Regarding your

I stuck with "TIP" because there are many places in ReaR
where this is used and I wanted to be consistent

I only find it in your code:

# find usr/sbin/rear usr/share/rear/ -type f | xargs grep -i 'tip[:]* ' | grep -v 'gethostip'

usr/share/rear/output/RAWDISK/Linux-i386/280_create_bootable_disk_image.sh:
        LogPrintError "TIP: You might achieve loop device partition support by installing the 'kpartx' tool, if available."

usr/share/rear/output/RAWDISK/Linux-i386/270_create_grub2_efi_bootloader.sh:
    LogPrint "TIP: You can achieve a faster EFI boot by installing syslinux for EFI on this system"

usr/share/rear/prep/OPALPBA/Linux-i386/001_configure_workflow.sh:
    LogPrintError "TIP: Your system seems to include a Plymouth graphical boot animation. You can achieve a nicer user"

;-)

OliverO2 commented at 2020-11-18 13:59:

@jsmeix
Thank you for taking care of it and for going the extra mile.

I only find it in your code:

Oh, really! It must be because ReaR has become too smart over time. In the past there was:

  • b3db59e10da3885ac287e41a7c341bab50e08f05 (Florent38 committed on Jul 17, 2013)
  • c532ab71231647384e973b093560cdd56568bbe5 (dagwieers committed on Jun 26, 2012)

(Some other TIPs are present in the documentation.)

And I was so convinced that the "TIP" prefix was not my idea at all... ;-)

jsmeix commented at 2020-11-18 14:05:

Guess who removed that TIP wording via
https://github.com/rear/rear/commit/df1d9623f6202f7908e6be8787211b4787626107
:-)

Good evolution:
From scaring WARNING to patronizing TIP to nothing :-)

When there is a TIP in the documentation I don't perceive it as patronizing
because I don't perceive reading documentation as if someone is talking to me.
In contrast working on a computer is some kind of dialog with a machine
and I don't like to get (unsolicited) good advice from a machine:

user@host $ rm -rf ~
Removed all files in your own home directory.
TIP: Now it's time for having a good backup.

;-)

jsmeix commented at 2020-11-19 11:33:

I tested it with artificial errors and (at least for me) things behave well
for "rear mkrescue" / "rear -v mkrescue" / "rear -d mkrescue".

Artificial error in rescue/GNU/Linux/500_clone_keyboard_mappings.sh

if dumpkeysQQQ -f >$ROOTFS_DIR$original_system_dumpkeys_file ; then

to let that fail.

Artificial error on openSUSE Leap 15.1:

# mv /usr/share/kbd/keymaps /usr/share/kbd/keymaps.away

[Export of Github issue for rear/rear.]