[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