Return to keyboardtables CVS log

Up to [MW Coherent from dump] / coherent / a / usr / man / COHERENT

Annotation of coherent/a/usr/man/COHERENT/keyboardtables, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: keyboard tables       Technical Information       keyboard tables
        !             4: 
        !             5: 
        !             6: 
        !             7: 
        !             8: How to write a keyboard table
        !             9: 
        !            10: 
        !            11: The  COHERENT device-driver  nnkkbb supports  industry-standard 83-,
        !            12: 101-, and 102-key  AT-protocol keyboards attached as the computer
        !            13: console.
        !            14: 
        !            15: nnkkbb  lets you  define both  the  layout of  the keyboard  and the
        !            16: values  returned by  function keys.   You  can change  layout and
        !            17: function-key  bindings  by  using  the special  keyboard  mapping
        !            18: programs kept in directory /ccoonnff/kkbbdd. This directory contains the
        !            19: C source code for the mapping  tables, as well as a MMaakkeeffiillee that
        !            20: helps you rebuild the mapping programs.
        !            21: 
        !            22: Before you  begin to write or modify  an existing keyboard table,
        !            23: be sure to read  throroughly this article and the Lexicon article
        !            24: on nnkkbb. If you do not, you may foul up the keyboard so thoroughly
        !            25: that it will not work well enough for you to undo your mistake!
        !            26: 
        !            27: ***** Operational  Overview ***** The device  driver nnkkbb provides
        !            28: the system's  portion of the  interface to the  console keyboard.
        !            29: It  handles hardware-specific details,  such as  initializing the
        !            30: keyboard  and  internal   state,  handling  keyboard  interrupts,
        !            31: processing key scan codes, and queueing characters.
        !            32: 
        !            33: The user half  of the keyboard interface is provided  by a set of
        !            34: stand-alone  utilities.   With these,  you  can  program the  nnkkbb
        !            35: driver  via specialized  iiooccttll() calls.   These  utilities differ
        !            36: from each  other only in  the keyboard binding  or mapping tables
        !            37: each uses.  You can  re-construct the interface to the nnkkbb driver
        !            38: by  modifying a  keyboard-mapping file and  then using  a support
        !            39: module to link that file to the driver.
        !            40: 
        !            41: The  keyboard-mapping  file  is  a  C  program that  consists  of
        !            42: initialized  tables  and strings.   In  addition, several  header
        !            43: files provide the scan codes and other constants required for the
        !            44: key tables.   This format makes  the file easy to  edit, and also
        !            45: lets you enter characters in several different formats.
        !            46: 
        !            47: The  support  module, in  turn,  performs  several tasks.   These
        !            48: include   scanning   the   keyboard-mapping  file   for   errors,
        !            49: reformatting the table for  use by the device driver, and passing
        !            50: the reformatted table to the driver.
        !            51: 
        !            52: ***** Key Mapping Files *****
        !            53: 
        !            54: By convention, directory  /ccoonnff/kkbbdd contains the keyboard-mapping
        !            55: files, executables, and a  MMaakkeeffiillee that you use to construct the
        !            56: executables from the corresponding source files.
        !            57: 
        !            58: A keyboard-mapping  source file consists primarily  of three data
        !            59: structures  that you  must  modify to  support  a given  keyboard
        !            60: mapping.  The first, and simplest, of the structures is ttbbll_nnaammee.
        !            61: This  is a  character string  that  describes the  keyboard.  For
        !            62: 
        !            63: 
        !            64: COHERENT Lexicon                                           Page 1
        !            65: 
        !            66: 
        !            67: 
        !            68: 
        !            69: keyboard tables       Technical Information       keyboard tables
        !            70: 
        !            71: 
        !            72: 
        !            73: example,  the   stock  101-key   US  AT  keyboard   mapping  file
        !            74: /ccoonnff/kkbbdd/uuss.cc initializes this string to:
        !            75: 
        !            76: 
        !            77:         "U.S. AT keyboard table"
        !            78: 
        !            79: 
        !            80: The  second data  structure, kkbbttbbll,  is  an array  of key-mapping
        !            81: entries.   It  has  one entry  (or  row)  for  each possible  key
        !            82: location.  Each  entry in this  structure consists of  11 fields,
        !            83: which hold,  respectively, the key number,  nine possible mapping
        !            84: values, and a mode  field.  The following example is for physical
        !            85: key location 3 from key-mapping source file /ccoonnff/kkbbdd/bbeellggiiaann.cc:
        !            86: 
        !            87: 
        !            88:         { K_3, 0x82, '2', none, none, 0x82, '2', '~', none, '~', O|T },
        !            89: 
        !            90: 
        !            91: Field 1 contains  the _s_c_a_n _c_o_d_e _s_e_t _3 code  value for the desired
        !            92: key.  Header  file <ssyyss/kkbbssccaann.hh> contains  symbolic constants of
        !            93: the form KK__n_n_n that map the AT keyboard's _p_h_y_s_i_c_a_l key number _n_n_n
        !            94: to  the corresponding  scan  code set  3 value  generated by  the
        !            95: keyboard.  In the  above example, KK_33 corresponds to key location
        !            96: three.
        !            97: 
        !            98: Fields 2 through 10 contain the key mappings corresponding to the
        !            99: following shift states, as follows:
        !           100: 
        !           101: 
        !           102:          2   base or unshifted
        !           103:          3   SSHHIIFFTT
        !           104:          4   CCOONNTTRROOLL
        !           105:          5   CCOONNTTRROOLL+SSHHIIFFTT
        !           106:          6   AALLTT
        !           107:          7   AALLTT+SSHHIIFFTT
        !           108:          8   AALLTT+CCOONNTTRROOLL
        !           109:          9   AALLTT+CCOONNTTRROOLL+SSHHIIFFTT
        !           110:         10   AALLTT_GGRRAAPPHHIICC
        !           111: 
        !           112: 
        !           113: For ``regular'' keys, the values for these nine fields are eight-
        !           114: bit  characters; for  ``function''  or ``shift''  keys, they  are
        !           115: special values.   The symbolic  constant nnoonnee indicates  that you
        !           116: want no  output when  the key is  pressed in the  specified shift
        !           117: state.
        !           118: 
        !           119: In the case of a function  key, the value specified is the number
        !           120: of the  desired function key.   Header file <ssyyss/kkbb.hh>  defines a
        !           121: set of symbolic constants of the form ff_n, where  _n is the desired
        !           122: function key  number.  You should use  these constants; they will
        !           123: improve the readability of  your code, and they will protect your
        !           124: keyboard  mapping source  files from  any  future changes  in the
        !           125: structure of the keyboard driver.
        !           126: 
        !           127: 
        !           128: 
        !           129: 
        !           130: COHERENT Lexicon                                           Page 2
        !           131: 
        !           132: 
        !           133: 
        !           134: 
        !           135: keyboard tables       Technical Information       keyboard tables
        !           136: 
        !           137: 
        !           138: 
        !           139: In  the  case  of a  ``shift''  key,  all  nine  entries must  be
        !           140: identical  and must  consist  of one  of  the following  symbolic
        !           141: constants: ssccrroollll, nnuumm,  ccaappss, llaalltt, rraalltt, llsshhiifftt, rrsshhiifftt, llccttrrll,
        !           142: rrccttrrll, or aallttggrr. These are defined in the <ssyyss/kkbb.hh> header file.
        !           143: Note that  83-key XT-layout  keyboards only have  one ``control''
        !           144: and  ``alt''  key,  so  not  all  shift-key combinations  may  be
        !           145: possible on your target keyboard.
        !           146: 
        !           147: The last  (11th) field  in the key  entry is the  ``mode'' field.
        !           148: The following symbolic  constants specify the mode of the current
        !           149: key:
        !           150: 
        !           151: CC    The ccaappss lock key affects this key.
        !           152: 
        !           153: FF    The  specified key  is a ``function''  or special  key.  The
        !           154:      value of  all mapping entries must  name function keys.  See
        !           155:      header file <kkbb.hh> for a list of predefined function keys.
        !           156: 
        !           157: MM    Make: use this mode with keys that do not repeat.  Note that
        !           158:      accidentally using  this mode with ``shift''  keys will stop
        !           159:      you from being able to ``unshift'' upon releasing the key!
        !           160: 
        !           161: MMBB   Make/Break: use this mode with ``shift'' keys.
        !           162: 
        !           163: NN    The nnuumm lock key affects this key.
        !           164: 
        !           165: OO    The  specified key  is ``regular''  and requires  no special
        !           166:      processing.
        !           167: 
        !           168: SS    The specified key is a ``shift'' or ``lock'' key.  Note that
        !           169:      all mapping entries for a  given key must be identical for a
        !           170:      ``shift'' or ``lock'' key to work correctly.
        !           171: 
        !           172: TT    Typematic:   this  type   is  usually   associated   with  a
        !           173:      ``regular'' key.
        !           174: 
        !           175: TTMMBB  Typematic/Make/Break.
        !           176: 
        !           177: The  above   example  specifies  a  mode   field  of  OO|TT,  which
        !           178: corresponds to  a ``regular'' key  with Typematic repeat,  and no
        !           179: special handling of the ``lock'' keys.
        !           180: 
        !           181: The  last  data  structure,  ffuunnkkeeyy,  consists  of  an  array  of
        !           182: function-key   initializers,   one   per   function   key.    The
        !           183: initializers  are simple  quoted character  strings  delimited by
        !           184: either  hexadecimal value  00xxFFFF,  octal value  \337777, or  symbolic
        !           185: constant DDEELLIIMM. Note that any other  value can be used as part of
        !           186: a function-key  binding.  Function keys are  numbered starting at
        !           187: zero.  By convention,  function key 0, when enabled, reboots your
        !           188: computer.  For traditional  reasons, this function key is usually
        !           189: bound to the key sequence <ccttrrll><aalltt><ddeell>.
        !           190: 
        !           191: Function keys  are useful not only in the  classical sense of the
        !           192: programmable function keys on the keyboard, but also as a general
        !           193: purpose   mechanism  for   binding  arbitrary   length  character
        !           194: 
        !           195: 
        !           196: COHERENT Lexicon                                           Page 3
        !           197: 
        !           198: 
        !           199: 
        !           200: 
        !           201: keyboard tables       Technical Information       keyboard tables
        !           202: 
        !           203: 
        !           204: 
        !           205: sequences  to a  given key.  For  example, physical  key location
        !           206: sixteen is  usually associated with  the <ttaabb> and  <bbaacckk ttaabb> on
        !           207: the  AT  keyboard.   For  example,  /ccoonnff/kkbbdd/uuss.cc sets  the  key
        !           208: mapping table entry for key 16 as follows:
        !           209: 
        !           210: 
        !           211: { K_16, f42, f43, none, none, f42, f43, none, none, none, F|T },
        !           212: 
        !           213: 
        !           214: For traditional reasons,  the <bbaacckk ttaabb> key outputs the sequence
        !           215: <eesscc>[ZZ whereas  the <ttaabb> key simply  outputs the horizontal-tab
        !           216: character <ccttrrll-II>.   Because at least one  of the mapping values
        !           217: for this  key is more  than one character  long, the key  must be
        !           218: defined as  a ``function''  key and all  entries for the  the key
        !           219: must  correspond  to  function-key  numbers.   In  this  example,
        !           220: function key  number 42  was chosen  for <ttaabb>, and  function key
        !           221: number 43 was chosen for <bbaacckk ttaabb>.  The constant nnoonnee indicates
        !           222: that you want no output when  the key is pressed in the specified
        !           223: shift state.  The corresponding ffuunnkkeeyy initialization entries for
        !           224: function keys ff4422 and ff4433 are as follows:
        !           225: 
        !           226: 
        !           227: /* 42 */      "\t\377",          /* Tab */
        !           228: /* 43 */      "\033[Z\377",      /* Back Tab */
        !           229: 
        !           230: 
        !           231: We  strongly   recommend  that  you   comment  your  function-key
        !           232: bindings.
        !           233: 
        !           234: You can also  change function-key bindings via the command ffnnkkeeyy.
        !           235: This command lets  you temporarily alter one or more function-key
        !           236: mappings without changing your key-mapping sources.
        !           237: 
        !           238: ***** Building New Binaries *****
        !           239: 
        !           240: After you  have modified an existing  keyboard-mapping table, use
        !           241: the following commands to rebuild the corresponding executables:
        !           242: 
        !           243: 
        !           244: cd /conf/kbd
        !           245: su root
        !           246: make
        !           247: 
        !           248: 
        !           249: If you  have created a new keyboard mapping  table, you must edit
        !           250: /ccoonnff/kkbbdd/MMaakkeeffiillee.   Duplicate  an   existing  entry   from  the
        !           251: MMaakkeeffiillee, and  change the  duplicated name  to match the  name of
        !           252: your new  keyboard-mapping table.   After you have  finished your
        !           253: editing,  build an  executable from  your  source file  by simply
        !           254: executing the above series of commands.
        !           255: 
        !           256: To  load your  new keyboard  table, simply type  the name  of the
        !           257: executable that  corresponds to your  keyboard-mapping file.  For
        !           258: example,  if you  just built executable  ffrreenncchh from  source file
        !           259: ffrreenncchh.cc, type the following command:
        !           260: 
        !           261: 
        !           262: COHERENT Lexicon                                           Page 4
        !           263: 
        !           264: 
        !           265: 
        !           266: 
        !           267: keyboard tables       Technical Information       keyboard tables
        !           268: 
        !           269: 
        !           270: 
        !           271: 
        !           272: 
        !           273: /conf/kbd/french
        !           274: 
        !           275: 
        !           276: If the  keyboard-support module finds an error,  it will print an
        !           277: appropriate message.   If it finds no errors,  it will update the
        !           278: internal  tables  of  the  nnkkbb  keyboard  driver,  reprogram  the
        !           279: keyboard, and print a message of the form:
        !           280: 
        !           281: 
        !           282: Loaded French AT keyboard table
        !           283: 
        !           284: 
        !           285: ***** Examples *****
        !           286: 
        !           287: Prior to the release  of the 101- and 102-key, enhanced-layout AT
        !           288: keyboards, the <ccttrrll> key was  positioned to the left of `A' key.
        !           289: Most  terminals also  locate  the <ccttrrll>  key  there.  The  first
        !           290: example shows how to swap the left <ccttrrll> key and the <ccaappss-lloocckk>
        !           291: key  on a  101-  and 102-key  keyboard.  The  <ccaappss-lloocckk> key  is
        !           292: physical key 30, whereas the  left <ccttrrll> key is physical key 58.
        !           293: Their respective  entries in file /ccoonnff/kkbbdd/uuss.cc  source file are
        !           294: as follows:
        !           295: 
        !           296: 
        !           297: { K_30, caps, caps, caps, caps, caps, caps, caps, caps, caps,  S|M },
        !           298: { K_58, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB },
        !           299: 
        !           300: 
        !           301: Note that the  <ccaappss-lloocckk> key is defined with mode  MM as it is a
        !           302: ``lock''  key.    The  keyboard   will  interrupt  only   on  key
        !           303: depressions, because releasing a ``lock'' key has no effect.  The
        !           304: left <ccttrrll> key is defined with mode MMBB as it is a ``shift'' key.
        !           305: The keyboard  generates an interrupt  on both key  depression and
        !           306: key release, because the driver must track the state of this key.
        !           307: 
        !           308: To swap the aforementioned keys, simply change all occurrences of
        !           309: ccaappss  to  llccttrrll and  vice-versa,  as well  as  swapping the  mode
        !           310: fields.  After making the changes, the entries now appear as:
        !           311: 
        !           312: 
        !           313: { K_30, lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl,lctrl, S|MB },
        !           314: { K_58, caps, caps, caps, caps, caps, caps, caps, caps, caps,  S|M  },
        !           315: 
        !           316: 
        !           317: The second  example converts a 101- or  102-key keyboard table to
        !           318: support  an  XT-style  83-key  keyboard  layout.   The  following
        !           319: section  summarizes   the  ``typical''  differences   found  when
        !           320: comparing the  two keyboard layouts.  Needless  to say, given the
        !           321: extreme variety in keyboard designs, your mileage may vary.
        !           322: 
        !           323: 
        !           324: 
        !           325: 
        !           326: 
        !           327: 
        !           328: COHERENT Lexicon                                           Page 5
        !           329: 
        !           330: 
        !           331: 
        !           332: 
        !           333: keyboard tables       Technical Information       keyboard tables
        !           334: 
        !           335: 
        !           336: 
        !           337:       _P_h_y_s_i_c_a_l     _1_0_1/_1_0_2        _8_3-_k_e_y
        !           338:       _L_o_c_a_t_i_o_n      _V_a_l_u_e          _V_a_l_u_e        _C_o_m_m_e_n_t_s
        !           339:          14          nnoonnee         _v_a_r_i_o_u_s       Keyboard specific
        !           340:          30          ccaappss          llccttrrll
        !           341:          58         llccttrrll          llaalltt
        !           342:          64         rrccttrrll          ccaappss
        !           343:          65          nnoonnee            ff22         Function Key
        !           344:          66          nnoonnee            ff44         Function Key
        !           345:          67          nnoonnee            ff66         Function Key
        !           346:          68          nnoonnee            ff88         Function Key
        !           347:          69          nnoonnee           ff1100         Function Key
        !           348:          70          nnoonnee            ff11         Function Key
        !           349:          71          nnoonnee            ff33         Function Key
        !           350:          72          nnoonnee            ff55         Function Key
        !           351:          73          nnoonnee            ff77         Function Key
        !           352:          74          nnoonnee            ff99         Function Key
        !           353:          90          nnuumm            eesscc
        !           354:          95          `/'            nnuumm
        !           355:          100         `*'          ssccrroollll
        !           356:          105         `-'            nnoonnee        <SSyyssRReeqq> not used
        !           357:          106         `+'            '*'
        !           358:          107         nnoonnee           '-'
        !           359:          108       <eenntteerr>          '+'
        !           360:          110         eesscc            nnoonnee        Not on XT layout
        !           361:        112-123      FF11-FF1122          nnoonnee        Not on XT layout
        !           362:          124         nnoonnee           nnoonnee        <PPrrttSSccrr> not used
        !           363:          125        ssccrroollll          nnoonnee        Not on XT layout
        !           364:          126         nnoonnee           nnoonnee        <PPaauussee> not used
        !           365: 
        !           366: 
        !           367: ***** See Also *****
        !           368: 
        !           369: ddeevviiccee ddrriivveerrss, ffnnkkeeyy, nnkkbb
        !           370: 
        !           371: ***** Notes *****
        !           372: 
        !           373: Key 14, if used, varies considerably among keyboard models.
        !           374: 
        !           375: The  location of  the key  that contains  characters `\'  and `|'
        !           376: varies among 101-key US-layout keyboards.
        !           377: 
        !           378: When  designing  keyboard  tables  for  keyboards  that  use  the
        !           379: AALLTT_GGRRAAPPHHIICC shift key, for reasons of backwards compatibility you
        !           380: should allow  the use of combination shift  AALLTT+CCTTRRLL as a synonym
        !           381: for AALLTT_GGRRAAPPHHIICC.
        !           382: 
        !           383: 
        !           384: 
        !           385: 
        !           386: 
        !           387: 
        !           388: 
        !           389: 
        !           390: 
        !           391: 
        !           392: 
        !           393: 
        !           394: COHERENT Lexicon                                           Page 6
        !           395: 
        !           396: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.