[kbd] man keymaps

[kbd] man keymaps

[kalle]

hello,
I have some improvement proposals or unclear points (where explanation
could be improved) for the man 5 keymaps page.
*It would make sense to explain the term 'charset' somewhere
what for is the code produced by a keysym ? How is it related to
character encoding?
*it would make sense to explain basic terms at the beginning of the
page, e.g. charset, keysym, key(scan-)code
*keysym: what does the term stand for? why 'symbol'? what does 'keyboard
actions' mean? is keyboard induced action possibly better? how is this
set of actions related to the specific kernel (driver?)?
*'outputting character codes' -> explain more precisely what is meant
here by 'character codes'
*first the term 'keysyms' should be explained in detail, before
explaining special keysyms as modifiers are, e.g. the section "keysyms
can be given in decimal, octal" should be before the modifier part
*the modifier-part is in my opinion badly explained - I roughly propose
the following:
to every key there are 2^8=256 (?) possibilities/modes of outputting
symbols (defined by the kernel driver?)
The 2^8 modes can be represented by eight binary digits, or interpreted
as a binary number with 8 (?) digits, e.g. 010000101. The first digit
standing , the last one for units of 2^0=1, in this example
0*2^7+0*2^6+0*2^5+0*2^4+0*2^3+1*2^2+0*2^1+1*2^0=133.
The different digits are called modifiers, since by combination of all
their different states (0 or 1) they are able to produce 256 (?) modes,
where the default one is when all modifiers are off (=0) so 00000000
binary is also 0 decimal number. These modifiers are keysyms thus their
state can be changed by typing some keys and out of historical
development have been given following names:

modifier name 				power of 2		decimal value

Shift					0		1
AltGr			Alternate Graph 1		2
				ics
Control					2		4
Alt					3		8
ShiftL			left Shift key	4		16
ShiftR			right Shift key 5		32
CtrlL			left Control key6		64
CtrlR			right Control k.7		128
CapsShift				8		256
*I don't understand the example of the part starting with "Note that you
should be very careful[…]",because it tells that the Control modifier
stays switched on, until it is produced again by typing in the same key.
*To the sentence "these are actually being defined" add "by the map
specification line, see above"
*to "it has a special meaning" add: "to loadkeys (1)"?

greetings,
kalle

Re: [kbd] man keymaps

[Alexey Gladkov]

On Sun, Jul 23, 2017 at 07:51:38AM +0200, kalle wrote:
> hello,
> I have some improvement proposals or unclear points (where explanation
> could be improved) for the man 5 keymaps page.
> *It would make sense to explain the term 'charset' somewhere
> what for is the code produced by a keysym ? How is it related to
> character encoding?

Good.

> *it would make sense to explain basic terms at the beginning of the
> page, e.g. charset, keysym, key(scan-)code

ok.

> *keysym: what does the term stand for? why 'symbol'? what does 'keyboard
> actions' mean? is keyboard induced action possibly better? how is this
> set of actions related to the specific kernel (driver?)?

what do you mean by "specific kernel driver" ?

> *'outputting character codes' -> explain more precisely what is meant
> here by 'character codes'
> *first the term 'keysyms' should be explained in detail, before
> explaining special keysyms as modifiers are, e.g. the section "keysyms
> can be given in decimal, octal" should be before the modifier part

why ?

> *the modifier-part is in my opinion badly explained - I roughly propose
> the following:
> to every key there are 2^8=256 (?) possibilities/modes of outputting
> symbols (defined by the kernel driver?)
> The 2^8 modes can be represented by eight binary digits, or interpreted
> as a binary number with 8 (?) digits, e.g. 010000101. The first digit
> standing , the last one for units of 2^0=1, in this example
> 0*2^7+0*2^6+0*2^5+0*2^4+0*2^3+1*2^2+0*2^1+1*2^0=133.

This description confuses even me. I believe that it is as described
modifiers are now quite clear.

> The different digits are called modifiers, since by combination of all
> their different states (0 or 1) they are able to produce 256 (?) modes,
> where the default one is when all modifiers are off (=0) so 00000000
> binary is also 0 decimal number. These modifiers are keysyms thus their
> state can be changed by typing some keys and out of historical
> development have been given following names:
> 
> modifier name 				power of 2		decimal value
> 
> Shift					0		1
> AltGr			Alternate Graph 1		2
> 				ics
> Control					2		4
> Alt					3		8
> ShiftL			left Shift key	4		16
> ShiftR			right Shift key 5		32
> CtrlL			left Control key6		64
> CtrlR			right Control k.7		128
> CapsShift				8		256

You want to make a describe the binary arithmetic for noobs ?

> *I don't understand the example of the part starting with "Note that you
> should be very careful[…]",because it tells that the Control modifier
> stays switched on, until it is produced again by typing in the same key.

I think this paragraph is quite clear in manpage. It describes what can
happen if the keymap is wrong.

> *To the sentence "these are actually being defined" add "by the map
> specification line, see above"
> *to "it has a special meaning" add: "to loadkeys (1)"?

Patches are welcome! :)

-- 
Rgrds, legion

Re: [kbd] man keymaps

[kalle]

>> *keysym: what does the term stand for? why 'symbol'? what does 'keyboard
>> actions' mean? is keyboard induced action possibly better? how is this
>> set of actions related to the specific kernel (driver?)?
> what do you mean by "specific kernel driver" ?

i think there are a lot of different kernels (versions). I don't really
know what a keyboard driver is and does. But I suppose that there are
different ones. If the kernel driver translates scancodes into keyboard
actions, I assume the latter are driver-dependant. This is what I meant
by "specific kernel driver".


>> *'outputting character codes' -> explain more precisely what is meant
>> here by 'character codes'

> why ?

what irritates me, is that on one side I associate a binary/hexadecimal
code to the term "character code" (who according to the keyboard layout
is interpreted as a different character), on the other side the command
dumpkeys, who describes the keyboard actions, names some actions `A' or
`a',`b'. I assume, that a symbol like `a' describes the keycode
corresponding to the asciicode, but with another code , the symbol `a'
could mean another letter.

>> *first the term 'keysyms' should be explained in detail, before
>> explaining special keysyms as modifiers are, e.g. the section "keysyms
>> can be given in decimal, octal" should be before the modifier part
>
> why ?

well, because I think the general should come before the special.

>> *the modifier-part is in my opinion badly explained - I roughly propose
>> the following:
>> to every key there are 2^8=256 (?) possibilities/modes of outputting
>> symbols (defined by the kernel driver?)
>> The 2^8 modes can be represented by eight binary digits, or interpreted
>> as a binary number with 8 (?) digits, e.g. 010000101. The first digit
>> standing , the last one for units of 2^0=1, in this example
>> 0*2^7+0*2^6+0*2^5+0*2^4+0*2^3+1*2^2+0*2^1+1*2^0=133.
> 
> This description confuses even me. I believe that it is as described
> modifiers are now quite clear.

There is a mistake in my explanation - it should say: "The first digit
stands for units of 2^8=256 […]"
Is it better now? Is my explanation technically correct?

What irritates me, is that each key can -according to the modifiers
switched - produce 256 different keyboard actions, as there are 9
modifiers and should therefore be 2^9=512 possibilities.

My goal was to explain the relationship between the differenlty named
modifiers and the 256 columns of key-actions associated to keys, e.g.
that one finds the result of the combination of
Control(2^2=4)-Alt(2^3=8)-Shift(2^0=1)-`g' in the 8+4+1=13 th column of
the scan code `28' (german keyboard).  The explanation continues in the
part below.

>> The different digits are called modifiers, since by combination of all
>> their different states (0 or 1) they are able to produce 256 (?) modes,
>> where the default one is when all modifiers are off (=0) so 00000000
>> binary is also 0 decimal number. These modifiers are keysyms thus their
>> state can be changed by typing some keys and out of historical
>> development have been given following names:
>>
>> modifier name 				power of 2		decimal value
>>
>> Shift					0		1
>> AltGr			Alternate Graph 1		2
>> 				ics
>> Control					2		4
>> Alt					3		8
>> ShiftL			left Shift key	4		16
>> ShiftR			right Shift key 5		32
>> CtrlL			left Control key6		64
>> CtrlR			right Control k.7		128
>> CapsShift				8		256
> 
> You want to make a describe the binary arithmetic for noobs ?

see above. But of course, I think it shoudn't be necesseary to know
binary arithmetics already to learn unix. If you know a manpage, where
it is described already, it would make sense to link to it. Furthermore,
I want to stress on the 'historical background' of some terms as the
names of the modifiers. As the previous author as I suppose wanted to
demystify them by describing them as "completely arbitrarily", which is
not really correct.



>> *I don't understand the example of the part starting with "Note that you
>> should be very careful[…]",because it tells that the Control modifier
>> stays switched on, until it is produced again by typing in the same key.
> 
> I think this paragraph is quite clear in manpage. It describes what can
> happen if the keymap is wrong.

I mean - the Control modifier doesn't stay switched on, if i typed it
once,doesn't it?

>> *To the sentence "these are actually being defined" add "by the map
>> specification line, see above"
>> *to "it has a special meaning" add: "to loadkeys (1)"?
> 
> Patches are welcome! :)

thanks


kalle

Re: [kbd] man keymaps

[Oleg Bulatov]

Hi,

> On 23 Jul 2017, at 07:51, kalle <kalle at projektwerkstatt.de> wrote:
> 
> hello,
> I have some improvement proposals or unclear points (where explanation
> could be improved) for the man 5 keymaps page.
> *It would make sense to explain the term 'charset' somewhere
> what for is the code produced by a keysym ? How is it related to
> character encoding?

man 7 charsets

Some of them define a character encoding as well (iso-8859-1, koi8-r), some other don’t (iso-10646-18).

> *it would make sense to explain basic terms at the beginning of the
> page, e.g. charset, keysym, key(scan-)code

The exact definition of these terms are beyond the scope of this man page. The brief descriptions are provided when necessary:

It [charset] defines how following keysyms are to be interpreted.

Each of the keysyms represent keyboard actions.

keycode keynumber = ...
keynumber is the internal identification number of the key, roughly equivalent to the scan code of it.

> *keysym: what does the term stand for? why 'symbol’?

A key code corresponds roughly to a physical key, while a keysym corresponds to the symbol on the key top.

> what does ‘keyboard actions' mean?

From the man page:

The actions available include outputting character codes or character sequences, switching consoles or keymaps, booting the machine etc.

For example: +A, VoidSymbol, Return, Caps_Lock, Compose, AltGr_Lock.

> is keyboard induced action possibly better?

I don’t think so.

> how is this set of actions related to the specific kernel (driver?)?

The set of actions has not changed for many years (since Linux 2.0?). But obviously any action you use has to be supported by kbd and the kernel.

> *'outputting character codes' -> explain more precisely what is meant
> here by 'character codes’

What can be more precise than character code?

> *first the term 'keysyms' should be explained in detail, before
> explaining special keysyms as modifiers are, e.g. the section "keysyms
> can be given in decimal, octal" should be before the modifier part

Suppose you want to change behaviour of one key on your keyboard. The current narration first helps you to find what you should change in a key map, and then how it should be changed.

> *the modifier-part is in my opinion badly explained - I roughly propose
> the following:
> to every key there are 2^8=256 (?) possibilities/modes of outputting
> symbols (defined by the kernel driver?)
> The 2^8 modes can be represented by eight binary digits, or interpreted
> as a binary number with 8 (?) digits, e.g. 010000101. The first digit
> standing , the last one for units of 2^0=1, in this example
> 0*2^7+0*2^6+0*2^5+0*2^4+0*2^3+1*2^2+0*2^1+1*2^0=133.
> The different digits are called modifiers, since by combination of all
> their different states (0 or 1) they are able to produce 256 (?) modes,
> where the default one is when all modifiers are off (=0) so 00000000
> binary is also 0 decimal number. These modifiers are keysyms thus their
> state can be changed by typing some keys and out of historical
> development have been given following names:
> 
> modifier name 				power of 2		decimal value
> 
> Shift					0		1
> AltGr			Alternate Graph 1		2
> 				ics
> Control					2		4
> Alt					3		8
> ShiftL			left Shift key	4		16
> ShiftR			right Shift key 5		32
> CtrlL			left Control key6		64
> CtrlR			right Control k.7		128
> CapsShift				8		256

I found the current explanation easier to understand.

I want to change behaviour of Ctrl+Shift+A. Let's see:

The effective action of a key is found out by adding up the weights of all the modifiers in effect.

Ok, 4+1 = 5, I need to change the 6th column.

Hurray! I should not care about binary digits to do this.

For those who understand binary arithmetic, it’s obvious why it works and produces a unique value for each combination.

> *I don't understand the example of the part starting with "Note that you
> should be very careful[?]",because it tells that the Control modifier
> stays switched on, until it is produced again by typing in the same key.

Let’s say you define your left shift key as

keycode 42 = Shift A

Then the key down event will be handled as Shift and next actions will be taken from the 2nd column. Which means the key up event will be handled as the ‘A’ key. So from the kernel's point of view the shift key isn’t released.

And if you have not any Shifts in the second column, you cannot ‘release’ the shift key anymore.

> *To the sentence "these are actually being defined" add "by the map
> specification line, see above”
> *to "it has a special meaning" add: "to loadkeys (1)"?

Everything in this man page is for loadkeys.

> greetings,
> kalle

-- 
WBR, Oleg