Bug#842760: localectl documentation bad, many problems

[David Lawyer]

Package: systemd
Version 231-4

It seems that the keymap system is not only poorly documented but that
"man localectl" isn't clear.  One problem: If you type: localectl find-keymaps.
Results: Couldn't find any console keymaps.  Yet there are many console
keymaps in the /usr/share/keymap tree.  They can be loaded with loadkeys
and I loaded one and it loaded but failed to show up in "localectl
status".  This was the ru-yawerty keymap for qwerty and it doesn't work right
because it's for koi8-r font and I only have utf-8 fonts loaded but I
expected loadkeys to translate koi-8r mappings to utf-8.  All the data
necessary for such a translation is present on my PC but translation
doesn't happen

There are two ways mentioned in the man page (localectl) to set the
keyboard mapping for the console and X11.  They are: set-keymap MAP
[TOGGLEMAP]; set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]].  For the
first, I can "set-keymap abczzz" and it will show it loaded by typing "localectl
status" although abczzz is just a made-up name which should have been
rejected with an error message.  It shouldn't accept nonsense parameters
without an error message.   What does "MAP" mean?  Is it only for X11
format keymaps ? known as "layouts" and  located in the X11 symbol file.  What is a
TOGGLEMAP?  Looks like it's just another keymap but of what type: X11 or
the older Virtual Console type (legacy).  Furthermore, where does one set
the toggle hot-key to toggle between these two maps (MAP and TOGGLEMAP).
If these are X11 maps one needs to set the variant for each "layout" as
well as the toggle to toggle between layouts.  How is this to be done?

The "set-x11-keymap" is just as confusing.  Suppose one wants to install 2
layouts.  Does one give the command twice?  OPTIONS are shown as
being associated with a LAYOUT but actually, there is one set of OPTIONS
for each set of loaded LAYOUTs.  For example, I may need to give the
"set-x11-keymap" ....  command twice if I want to setup the ru (Russian)
and us layouts.  Then I need to specify the toggle to use to toggle between
ru and us.  This is placed as an OPTION but if I give the "set-xll-keymap
twice there are two "OPTIONS" strings.  But only one string of options is
allowed.  It should be mentioned that OPTIONS contains a , separated list
with no spaces.

Or perhaps LAYOUT is a comma separated list of the layouts I am installing
(likewise for VARIANT).  But the MODEL is only a single parameter and
OPTIONS is a single comma-separated list.  LAYOUT and VARIANT would have
the same number of commas (lists the same size).

I could, of course, experiment to find out how to use these commands and
what they do but I shouldn't need to as the documentation should explain
this but it doesn't.

The nomenclature needs improvement since what is called a LAYOUT is really
a class of layouts where each such layout it called a "variant".  Every
layout is a "variant" even if one didn't specify a variant, since then
the "basic" variant is used by default.  In some cases, a variant can be
not a single layout but a set of layouts with shift-levels used to change
layouts within a variant (assuming that a switch_latch is like a toggle).
For example the rus variant of the us layout includes both a latin and
Cyrillic (Russian) character set with level 3 being the latin characters.
This is tantamount to a variant within a variants.


			David Lawyer