[unix-history] / usr.sbin / keymap / keymap / keycap.5

.\" Copyright (c) 1983, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)keycap.5	1.1 (Contributed to 386bsd) 4/27/93
.\"
.Dd April 27, 1993
.Dt KEYCAP 5
.Os 386bsd
.Sh NAME
.Nm keycap
.Nd keyboard configuration data base
.Sh SYNOPSIS
.Nm keycap
.Sh DESCRIPTION
The
.Nm keycap
file describes national keyboard mappings for the console driver
.Xr co 4 .
This file is accessed by the 
.Xr keymap 8
utility.
Each entry in the data base
is used to describe one class of keyboards.
.Pp
There is a default keyboard class,
.Em default ,
which corresponds to the standard builtin mapping of the 
.Xr co 4
driver.
.Sh CAPABILITIES
Refer to
.Xr termcap 5
for a description of the file layout.
The
.Em default
column below lists defaults obtained if there is
no entry in the table obtained, nor one in the special
.Em default
table.
.Bl -column Symbol D0..D127 -column Type false
.It Symbol	Type	Default	Description
.It "ag 	num	0	key number of the ALTGRLOCK key
.It "A1..A127	str	0	map a string to the ALTGR key layer
.It "C1..C127	str	none	map a string to the CTRL key layer
.It "ca	num	0	key number of the CAPS LOCK key
.It "de	bool	false	sets the default mapping (top precedence)
.It "D0..D127	bool	false	disables the given key (1..127) entirely
.It "fn0	str	none	pathname of first loadable font
.It "fn1	str	none	pathname of second loadable font
.It "fe0	num	none	font encoding first font
.It "fe1	num	none	font encoding second font
.It "h1..h9	num	0	key numbers of the SHIFT keys (up to 9)
.It "K1..K127	str	none	map a string to the UNSHIFTED key
.It "l0	bool	false	clears the ALTGR map
.It "l1..l9	num	0	key numbers of the ALTGR keys (up to 9)	
.It "la	num	0	defines the operation of the CAPSLOCK LED
.It "m1..m9	num	0	key numbers of the META Keys (up to 9)
.It "M1..M127	str	0	map a string to the META key layer
.It "nl	num	0	key number of the NUM LOCK key
.It "p1..p9	num	0	key number of a diacritical prefix
.It "S1..S127	str	none	map a string to the SHIFTED key layer
.It "sc	num	0	key number of the SCROLL LOCK key
.It "sh	num	0	key number of the SHIFT LOCK key
.It "t0	bool	false	clears the CTRL map
.It "t1..t9	num	0	key numbers of the CTRL keys (up to 9)
.It "tc	str	none	allows extension of capabilities
.It "X1..X127	str	none	map a string to the SHIFTED-ALTGR key layer
.El
.Pp
The
.Em tc=capability
entry allows the extension of a keyboard entry. If, for instance,
the keyboard type 
.Em foo , 
differs from the similar type
.Em bar
in that the first has the capslock function on key 55, you might write
an entry for 
.Em foo 
in the following way:
.Pp
.Bd -literal
foo|the foo keyboard:\e
	ca#55:tc=bar:
.Ed
.Sh String Entries for the keys (K*,S*,C*,A*):
These allow mappings of strings to keys. Examples:
.Pp
.Bl -tag -width K123=abcdef -compact
.It Em K123=abcdef
maps the string "abcdef" to key 123
.It Em K123=^D
maps CTRL-D to key 123
.It Em K123=\e072
maps the colon \: to key 123 (only way to do it)
.It Em K123=\e176
maps the tilde \~ to key 123 (only way to do it)
.It Em K123=\e077
maps the question mark ? to key 123 (only way to do it)
.El
.Pp
The maximum allowed length of string is 15 bytes.
.Pp
.Sh Special alphabetic characters (new since 0.1.2):
The CAPSLOCK key if present on your keyboard influences alphabetic
keys only. This is obvious for the Latin alphabet only. If you use
another than the latin alphabet, the alphabetic characters must
be identified otherwise. If a key string starts with a tilde \~
the following code inherits the ALPHA attribute, i.e. it is
influenced by the CAPSLOCK key. 
.Pp
.Sh Locking keys (new since 0.1.2):
The ALTGR key layer (A,X) has its own LOCK key which can be
assigned with the 
.Em ag
capability. To have an indicator which
layer is currently active, the CAPSLOCK LED may be redefined
to follow the ALTGRLOCK key
.Em (la#2) 
rather than the CAPSLOCK key
.Em (la#0) 
or SHIFTLOCK key
.Em (la#1).
.Pp
.Sh Special hotkeys (new since 0.1.2):
The
.Xr co 4
driver has support for some hotkeys that are processed
.Em before 
the normal character interpretation. Hotkey functions can be assigned to
any key like any standard string. To encode them, a two character
sequence starting with a question mark ? is used. Any of the six layers
K,S,A,C,X,M can be used, with the M (META) layer denoting SYSKEY,
and the X layer denoting CTRL-ALT. SYSKEY is a prefix key.
Note that a hotkey mapped to some key layer will suppress the
underlying standard function. The following table shows the hotkeys, 
their encoding, their default mapping and their meaning:

.Bl -column Name VTY-PREV  -column Encoding ?X -column Default CTRL-ALT-DEL
.It "Name     Encoding  Default	        Description
.It "---         ?-     none            deletes a default hotkey
.It "RESET       ?R     CTRL-ALT-DEL    do a CPU reset
.It "DEBUG       ?D     CTRL-ALT-ESC    call the kernel debugger (if conf'd)
.It "VTY-PREV    ?P     none            switch to previous vty in sequence
.It "VTY-NEXT    ?N     none            switch to previous vty in sequence
.It "VTY-0       ?0     CTRL-ALT-F1     switch to vty 0
.It "...         ..     ...             ...
.It "VTY-9       ?9     CTRL-ALT-F10    switch to vty 9 (if conf'd)
.It "VTY-10      ?A     CTRL-ALT-F11    switch to vty 10 (if conf'd)
.It "VTY-11      ?B     CTRL-ALT-F12    switch to vty 11 (if conf'd)
.El
.Pp
.Sh Diacritical Prefixes:
Normally, keys like ` ' ^ ~ have their regular meaning and return the
corresponding ASCII code. If the corresponding key gets the 
.Em diacritical prefix attribute , 
it behaves different: Returning the ASCII code is retained
until a second character. If this is a character, which may have an
additional diacritical mark, then the corresponding diacritical character
is returned. If the character is a blank, the original ASCII code of the
prefix is returned. Otherwise the prefix is absorbed. Example:
To get the A with an accent grave, press first ` , then A.
In the data base, these diacritical keys are entered by their corresponding
octal number.
.Pp
.Sh SEE ALSO
.Xr co 4 ,
.Xr keymap 8.
.Sh BUGS
In general, the database is downward compatible to keycap 0.1.1 and 
pccons clones, but there is no guarantee that it works as expected.
Upgrade to the new
.Xr co 4
driver (release 0.1.2 or later) to get full support for all the features.
Furthermore, there is no good way to express ISO-LATIN1 or other
characters >127 other than by their octal representation.
.Sh HISTORY
The
.Nm keycap
file format is a new feature of 386bsd 0.1 and later.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1983, 1991 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)keycap.5 1.1 (Contributed to 386bsd) 4/27/93
	33	.\"
	34	.Dd April 27, 1993
	35	.Dt KEYCAP 5
	36	.Os 386bsd
	37	.Sh NAME
	38	.Nm keycap
	39	.Nd keyboard configuration data base
	40	.Sh SYNOPSIS
	41	.Nm keycap
	42	.Sh DESCRIPTION
	43	The
	44	.Nm keycap
	45	file describes national keyboard mappings for the console driver
	46	.Xr co 4 .
	47	This file is accessed by the
	48	.Xr keymap 8
	49	utility.
	50	Each entry in the data base
	51	is used to describe one class of keyboards.
	52	.Pp
	53	There is a default keyboard class,
	54	.Em default ,
	55	which corresponds to the standard builtin mapping of the
	56	.Xr co 4
	57	driver.
	58	.Sh CAPABILITIES
	59	Refer to
	60	.Xr termcap 5
	61	for a description of the file layout.
	62	The
	63	.Em default
	64	column below lists defaults obtained if there is
65	no entry in the table obtained, nor one in the special
66	.Em default
67	table.
68	.Bl -column Symbol D0..D127 -column Type false
69	.It Symbol Type Default Description
70	.It "ag num 0 key number of the ALTGRLOCK key
71	.It "A1..A127 str 0 map a string to the ALTGR key layer
72	.It "C1..C127 str none map a string to the CTRL key layer
73	.It "ca num 0 key number of the CAPS LOCK key
74	.It "de bool false sets the default mapping (top precedence)
75	.It "D0..D127 bool false disables the given key (1..127) entirely
76	.It "fn0 str none pathname of first loadable font
77	.It "fn1 str none pathname of second loadable font
78	.It "fe0 num none font encoding first font
79	.It "fe1 num none font encoding second font
80	.It "h1..h9 num 0 key numbers of the SHIFT keys (up to 9)
81	.It "K1..K127 str none map a string to the UNSHIFTED key
82	.It "l0 bool false clears the ALTGR map
83	.It "l1..l9 num 0 key numbers of the ALTGR keys (up to 9)
84	.It "la num 0 defines the operation of the CAPSLOCK LED
85	.It "m1..m9 num 0 key numbers of the META Keys (up to 9)
86	.It "M1..M127 str 0 map a string to the META key layer
87	.It "nl num 0 key number of the NUM LOCK key
88	.It "p1..p9 num 0 key number of a diacritical prefix
89	.It "S1..S127 str none map a string to the SHIFTED key layer
90	.It "sc num 0 key number of the SCROLL LOCK key
91	.It "sh num 0 key number of the SHIFT LOCK key
92	.It "t0 bool false clears the CTRL map
93	.It "t1..t9 num 0 key numbers of the CTRL keys (up to 9)
94	.It "tc str none allows extension of capabilities
95	.It "X1..X127 str none map a string to the SHIFTED-ALTGR key layer
96	.El
97	.Pp
98	The
99	.Em tc=capability
100	entry allows the extension of a keyboard entry. If, for instance,
101	the keyboard type
102	.Em foo ,
103	differs from the similar type
104	.Em bar
105	in that the first has the capslock function on key 55, you might write
106	an entry for
107	.Em foo
108	in the following way:
109	.Pp
110	.Bd -literal
111	foo\|the foo keyboard:\e
112	ca#55:tc=bar:
113	.Ed
114	.Sh String Entries for the keys (K,S,C,A):
115	These allow mappings of strings to keys. Examples:
116	.Pp
117	.Bl -tag -width K123=abcdef -compact
118	.It Em K123=abcdef
119	maps the string "abcdef" to key 123
120	.It Em K123=^D
121	maps CTRL-D to key 123
122	.It Em K123=\e072
123	maps the colon \: to key 123 (only way to do it)
124	.It Em K123=\e176
125	maps the tilde \~ to key 123 (only way to do it)
126	.It Em K123=\e077
127	maps the question mark ? to key 123 (only way to do it)
128	.El
129	.Pp
130	The maximum allowed length of string is 15 bytes.
131	.Pp
132	.Sh Special alphabetic characters (new since 0.1.2):
133	The CAPSLOCK key if present on your keyboard influences alphabetic
134	keys only. This is obvious for the Latin alphabet only. If you use
135	another than the latin alphabet, the alphabetic characters must
136	be identified otherwise. If a key string starts with a tilde \~
137	the following code inherits the ALPHA attribute, i.e. it is
138	influenced by the CAPSLOCK key.
139	.Pp
140	.Sh Locking keys (new since 0.1.2):
141	The ALTGR key layer (A,X) has its own LOCK key which can be
142	assigned with the
143	.Em ag
144	capability. To have an indicator which
145	layer is currently active, the CAPSLOCK LED may be redefined
146	to follow the ALTGRLOCK key
147	.Em (la#2)
148	rather than the CAPSLOCK key
149	.Em (la#0)
150	or SHIFTLOCK key
151	.Em (la#1).
152	.Pp
153	.Sh Special hotkeys (new since 0.1.2):
154	The
155	.Xr co 4
156	driver has support for some hotkeys that are processed
157	.Em before
158	the normal character interpretation. Hotkey functions can be assigned to
159	any key like any standard string. To encode them, a two character
160	sequence starting with a question mark ? is used. Any of the six layers
161	K,S,A,C,X,M can be used, with the M (META) layer denoting SYSKEY,
162	and the X layer denoting CTRL-ALT. SYSKEY is a prefix key.
163	Note that a hotkey mapped to some key layer will suppress the
164	underlying standard function. The following table shows the hotkeys,
165	their encoding, their default mapping and their meaning:
166
167	.Bl -column Name VTY-PREV -column Encoding ?X -column Default CTRL-ALT-DEL
168	.It "Name Encoding Default Description
169	.It "--- ?- none deletes a default hotkey
170	.It "RESET ?R CTRL-ALT-DEL do a CPU reset
171	.It "DEBUG ?D CTRL-ALT-ESC call the kernel debugger (if conf'd)
172	.It "VTY-PREV ?P none switch to previous vty in sequence
173	.It "VTY-NEXT ?N none switch to previous vty in sequence
174	.It "VTY-0 ?0 CTRL-ALT-F1 switch to vty 0
175	.It "... .. ... ...
176	.It "VTY-9 ?9 CTRL-ALT-F10 switch to vty 9 (if conf'd)
177	.It "VTY-10 ?A CTRL-ALT-F11 switch to vty 10 (if conf'd)
178	.It "VTY-11 ?B CTRL-ALT-F12 switch to vty 11 (if conf'd)
179	.El
180	.Pp
181	.Sh Diacritical Prefixes:
182	Normally, keys like ` ' ^ ~ have their regular meaning and return the
183	corresponding ASCII code. If the corresponding key gets the
184	.Em diacritical prefix attribute ,
185	it behaves different: Returning the ASCII code is retained
186	until a second character. If this is a character, which may have an
187	additional diacritical mark, then the corresponding diacritical character
188	is returned. If the character is a blank, the original ASCII code of the
189	prefix is returned. Otherwise the prefix is absorbed. Example:
190	To get the A with an accent grave, press first ` , then A.
191	In the data base, these diacritical keys are entered by their corresponding
192	octal number.
193	.Pp
194	.Sh SEE ALSO
195	.Xr co 4 ,
196	.Xr keymap 8.
197	.Sh BUGS
198	In general, the database is downward compatible to keycap 0.1.1 and
199	pccons clones, but there is no guarantee that it works as expected.
200	Upgrade to the new
201	.Xr co 4
202	driver (release 0.1.2 or later) to get full support for all the features.
203	Furthermore, there is no good way to express ISO-LATIN1 or other
204	characters >127 other than by their octal representation.
205	.Sh HISTORY
206	The
207	.Nm keycap
208	file format is a new feature of 386bsd 0.1 and later.