<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
]>

<refentry>
  <docinfo>
    <address><email>dirson@debian.org</email></address>
    <author>
      <firstname/Yann/ <surname/Dirson/
     </author>
    <copyright>
      <year>1999-2001</year>
      <holder>Yann Dirson</holder>
    </copyright>

    <date>April 5, 2001</date>
  </docinfo>

  <refmeta>
    <refentrytitle>INSTALL-KEYMAP</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>install-keymap</refname>
    <refpurpose>expand a given keymap and install it as boot-time keymap</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>install-keymap</command>
      <arg><replaceable>keymap-name</replaceable> | NONE | KERNEL</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title/DESCRIPTION/

    <para><command/install-keymap/ usually takes a
    <replaceable/keymap-name/ as argument.  The file is passed to
    <command/loadkeys/ for loading, so that valid values for this
    argument are the same than that of arguments to
    <command/loadkeys/.  <command/install-keymap/ expands include-like
    statements in that file, and puts the result in
    <filename>/etc/console/boottime.kmap.gz</filename>, which will be
    loaded into the kernel at boot-time.</para>

    <para>One may also specify <literal/KERNEL/ instead of a keymap
    name, causing <filename>/etc/console/boottime.kmap.gz</filename>
    to be removed, making sure that no custom keymap will replace the
    kernel's builtin keymap at next reboot.</para>

    <para>An argument of <literal/NONE/ tells the command to do
    nothing.  It can be used by caller scripts to avoid handling this
    special case and needlessly duplicate code.</para>

    <para>The purpose of this processing is to solve an annoying
    problem, of 2 apparently conflicting issues.  The first one is an
    important goal of keymap management in Debian, namely ensuring
    that whenever the user or admin is expected to use the keyboard,
    the keymap selected as boot-time keymap is in use; this means the
    keymap has to be loaded before a shell is ever proposed, which
    means very early in the booting process, and especially before all
    local filesystems are mounted
    (<filename>/etc/rcS.d/S10checkroot.sh</filename> can spawn
    <command>sulogin</command>).</para>

    <para>The second issue is that for flexibility we allow that
    <filename>/usr</filename> or <filename>/usr/share</filename> may
    live on their own partition(s), and thus
    <filename>/usr/share/keymaps</filename>, where keymap files live,
    may not be available for reading at the time we need a keymap
    file.  And no, we won't put 1Mb of keymaps in the root
    partition just for this.</para>

    <para>And the problem is, most keymap files are not
    self-contained, so it does not help to just copy the selected file
    into the root partition.  The best known solution so far is to
    expand the keymap file so that it becomes self-contained, and put
    it in the root partition.  That's what this tool does.</para>

  </refsect1>

  <refsect1>
    <title>FILES</title>

    <glosslist>
      <glossentry>
	<glossterm><filename>/etc/console/boottime.kmap.gz</filename></glossterm>
	<glossdef><simpara>Where the boot-time keymap is stored</simpara></glossdef>
      </glossentry>
    </glosslist>

  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para>loadkeys (8).</para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>This program and manual page were written by Yann Dirson
      <email>dirson@debian.org</email> for the &debian; system, but as
      it should not include any Debian-specific code, it may be used by
      others.</para>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-ecat-files:nil
End:
-->
