Re: [kbd] man keymaps

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