<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article id="index">
<artheader>
   <title>Visual Bell mini-Howto</title>
   <author>
      <firstname>Alessandro</firstname>
      <surname>Rubini</surname>
      <affiliation>
         <address>
            <email>rubini@linux.it</email>
         </address>
      </affiliation>
   </author>

   <revhistory>
      <revision>
         <revnumber>2.2</revnumber>
         <date>11 November 1997</date>
         <authorinitials>ar</authorinitials>
      </revision>
      <revision>
         <revnumber>2.2</revnumber>
         <date>9 November 1999</date>
         <authorinitials>dlr</authorinitials>
         <revremark>converted from LinuxDoc to DocBook</revremark>
      </revision>
   </revhistory>

   <abstract>
<para>
This document explains how to use termcap to configure a visual bell
on one's system and describes how to disable audible bells on demand.
</para>
   </abstract>

</artheader>

<sect1 id="copyright">
<title>Copyright and Licensing Information</title>
<para>
Copyright &copy; 1997 Alessandro Rubini.  This
material may be distributed only subject to the terms and conditions set
forth in the Open Publication License, v0.4 or later (the latest version
is presently available at <ulink
url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>).
</para>
<para>
Note that neither of the OPL "Options" apply to this document.  This
document may be freely reformatted, freely distributed, and freely
modified and translated according to the terms presented in the Open
Publication License.
</para>
</sect1>

<sect1 id="introduction">
<title>Introduction</title>
<para>
The Linux console driver beeps the audible bell whenever a BEL char is
output (ASCII code 7).  Though this is a right choice for the default
behaviour, many users don't like their computer to beep. This
mini-Howto is meant to explain how to tell applications not to output
the BEL code. It also explain how to instruct the kernel and the X
Window System to avoid beeping when a BEL is output. Note that most of
this document refers to the text console, as configuring the X server
is an easy catch-all for any user who works in a graphic environment.
</para>
<para>
In my opinion the best way to face a fussy computer is fixing the
hardware, and my own computer doesn't even carry a loudspeaker.
</para>
</sect1>

<sect1 id="speakerectomy">
<title>Speakerectomy</title>
<para>
Speakerectomy is by far the most brilliant solution to the audible bell
problem. As its name implies, it consists in removing the beeps by removing
the beeper. The operation is straightforward and you don't
even need any anesthetic, but if you want there's room for refinement.
</para>
<para>
PC's are usually equipped with a silly switch to lower CPU clock.  The
switch is never used when you work in a multitasking environment, as
you don't even need to slow the computer down to run games based on
software loops. Unfortunately we can't use the switch to increase
processor speed, but we can use it to enable/disable the
loudspeaker. Sometimes the speaker is useful even if you enjoy a
silent number cruncher, for example to signal the end of a lengthy
compilation.  To modify the switch functionality, just detach it from
the main board and connect its wires in series with the
loudspeaker.
</para>
<para>
Owners of laptop boxes, unfortunately, don't have easy access to the
loudspeaker, and neither they have a spare switch to turn to a
different task.  The preferred solution for such users is configuring
their software to avoid beeping, as described below.
</para>
</sect1>

<sect1 id="perconsole">
<title>Per-console Beep Configuration</title>
<para>
As of Linux 1.3.43, Martin Mares added the ability to configure the
pitch and duration of the beep, by modifying
<filename>console.c</filename>. Each console can be configured to
feature a different duration and/or pitch of the bell sound; the task is
accomplished by using escape sequences to the console device.  You can
configure your own <filename>~/.profile</filename> or
<filename>~/.login</filename> file to select a different beep sound
associated to each console (or no beep at all, if needed).
</para>
<para>
The escape sequences work as follow:
</para>

<itemizedlist>
<listitem>
<para>
<literal>ESC-[10;xx]</literal> selects the bell frequency in Hertz. The value
should be in the range 21-32766, otherwise the result is undefined.
If the <replaceable>xx</replaceable> argument is missing, the default value (750Hz) will apply,
as in <literal>`ESC-[10]</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>ESC-[11;xx]</literal> selects the bell duration, in
milli-seconds.  If you specify more than 2 seconds, the default applies
(125ms). Once again, if the `xx' argument is missing
(<literal>ESC-[11]</literal>) the default value will be used.
</para>
</listitem>
</itemizedlist>

<para>
To select, for example, a 50Hz pitch for one-second duration, you can
<command>echo -e "\\33[10;50]\\33[11;1000]"</command> with
<command>bash</command> (where <option>-e</option> means `understand
Escape sequences'. If you use <command>tcsh</command> the same command
spells <command>echo "\\033[10;50]\\033[11;1000]"</command>.
</para>
<para>
Although I don't know of any version of the <command>setterm</command>
command that supports such configuration, a future version of the
command might well support a command-line option to configure the bell
sound.  
</para>
<para>
If you run Linux-1.3.43 or newer, you may be satisfied with the escape
sequences and avoid reading further. If you run an older kernel, or if
you want the visual bell, you'll enjoy the rest of this document.
</para>
</sect1>

<sect1 id="concepts">
<title>Basic Concepts About Termcap and Terminfo</title>
<para>
The file <filename>/etc/termcap</filename> is a text file that lists the
<emphasis>term</emphasis>inal <emphasis>cap</emphasis>abilities. Several
applications use the <command>termcap</command> information to move the
cursor around the screen and do other screen-oriented tasks.
<command>tcsh</command>, <command>bash</command>, <command>vi</command>
and all the <command>curses</command>-based applications use the
<command>termcap</command> database.
</para>
<para>
The database describes several terminal types. The <envar>TERM</envar>
environment variable selects the right behaviour at run-time, by naming
a <command>termcap</command> entry to be used by applications.
</para>
<para>
Within the database, each capability of the terminal appears as a
two-letter code and a representation of the actual escape sequence
used to get the desired effect.  The separator character between
different capabilities is the colon (":").  As an example, the audible
bell, with code "bl", usually appears as <command>bl=^G</command>. This sequence
tells that the bell sound is obtained by printing the
<keycap>CTRL</keycap>-<keycap>G</keycap>
character, the ASCII BEL.
</para>
<para>
In addition to the <command>bl</command> capability, the
<command>vb</command> capability is recognized. It is used to represent
the "visible bell".  <command>vb</command> is usually missing in the
<command>linux</command> entry of the <filename>termcap</filename>
file.
</para>
<para>
Most modern applications and libraries use the
<filename>terminfo</filename> database instead of
<command>termcap</command>. This database uses one file per
terminal-type and lives in <filename>/usr/lib/terminfo</filename>; to
avoid using huge directories, the description of each terminal type is
stored in a directory named after its first letter; the
<command>linux</command> entry, therefore, is
<filename>/usr/lib/terminfo/l/linux</filename>. To build a
<command>terminfo</command> entry you'll ``compile'' the
<command>termcap</command> description; refer to the
<command>tic</command> program and its manual page.
</para>
</sect1>

<sect1 id="visiblebell">
<title>Defining a Visible Bell</title>
<para>
You can add the entry for the <command>vb</command> capability in your own termcap
file, if it doesn't already define one.  Dennis Henriksen
(duke@diku.dk) suggested to insert the following line in the
<command>termcap</command> entry for <command>linux</command> (note that the entry is called
<command>console</command> in old distributions):
</para>

<programlisting>
:vb=\E7\E[?5h\E[?5l\E[?5h\E[?5l\E[?5h\E[?5l\E[?5h\E[?5l\E8:\
</programlisting>

<para>
The trailing backslash is used to escape the newline in the database.
Dennis' code does the following (his own words):
</para>

<itemizedlist>
<listitem>
<para>
Save the cursor position (uust a safety precaution).
</para>
</listitem>
<listitem>
<para>
Change the background color several times between normal and reverse.
</para>
</listitem>
<listitem>
<para>
Restore the cursor position.
</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="audiblebell">
<title>Disabling the Audible Bell on the Text Console</title>
<para>
If you want to force the visible bell on your console you can use the
<command>bl</command> entry in <command>termcap</command> and define it
with the same string suggested for <command>vb</command> above.  This
approach is handy if you don't want to customize each application (which
is described below, anyway).  I use this option on all the machines
where I can run Linux and I can't detach the speaker.
</para>
</sect1>

<sect1 id="nobeep">
<title>Telling Applications to Avoid Beeping</title>
<para>
This is an incomplete list of applications that can be instructed to use
the <command>vb</command> entry for the current terminal type (using
either the <command>termcap</command> information or the
<command>terminfo</command> one):
</para>

<itemizedlist>

<listitem>
<para>
The X server: use the <command>xset b</command> command to select the
bell's behaviour. The command takes three numeric arguments: volume,
pitch and duration. <command>xset -b</command> disables the bell
altogether. Configuring the X server affects all the applications
running on the display.
</para>
</listitem>

<listitem>
<para>
<command>xterm</command>: xterm can convert each bell to either a
visible or audible signal. If you use the audible bell, the settings of
<command>xset</command> will apply. The bell in <command>xterm</command>
defaults to be audible, but you can use the <option>-vb</option> command
line option and the <command>xterm*visualBell: true</command> resource
to turn it to a visible flash. You can toggle visible/audible signaling
at run-time by using the menu invoked by control--left-mouse-button.  If
you run X you most likely won't need the following information.
</para>
</listitem>

<listitem>
<para>
<command>tcsh</command> (6.04 and later): <command>set
visiblebell</command>.  The instruction can be placed in
<filename>.cshrc</filename> or can be issued interactively. To reset the
audible bell just <command>unset visiblebell</command>. To disable any
notification issue use <command>set nobeep</command> instead.
</para>
</listitem>

<listitem>
<para>
<command>bash</command> (any bash, as fas as I know): put <command>set
bell-style visible</command> in your <filename>~/.bashrc</filename>.
Possible bell-style's are also <option>none</option> or
<option>audible</option>.
</para>
</listitem>

<listitem>
<para>
<command>bash</command> (with <command>readline</command>, as well as
other <command>readline</command>-based applications): put <command>set
prefer-visible-bell</command> in <filename>~/.inputrc</filename>.
</para>
</listitem>

<listitem>
<para>
<command>nvi</command> and <command>elvis</command>: put <command>set
flash</command> in <filename>~/.exrc</filename> or tell <command>:set
flash</command> interactively (note the colon).  To disable the visible
bell use <command>noflash</command> in place of
<command>flash</command>.
</para>
</listitem>

<listitem>
<para>
<command>emacs</command>: put <command>(setq visible-bell t)</command>
in your <filename>~/.emacs</filename>.  It is disabled by <command>(setq
visible-bell nil)</command>.
</para>
</listitem>

<listitem>
<para>
<command>less</command>: use <command>-q</command> on command line to
use the visual bell, use <command>-Q</command> to disable any reporting.
Default options can be put in your environment variable
<envar>LESS</envar>.
</para>
</listitem>

<listitem>
<para>
<command>screen</command>: issue the
<keycap>Ctrl</keycap><keycap>A</keycap>-<keycap>Ctrl</keycap><keycap>G</keycap>
command. It changes the behaviour of all the virtual screens. Refer to
the man page under "CUSTOMIZATION" for setting the default.
</para>
</listitem>

</itemizedlist>

</sect1>

<sect1 id="thedarkside">
<title>The Dark Side of the Problem</title>
<para>
The bad news is that not every application uses
<filename>termcap</filename> or <filename>terminfo</filename>. Most
small programs feature 'backslash-a' (alarm) characters in the C source
code.  The "alarm" code becomes a literal ASCII BEL in the strings as
stored in the executable binary.  Real application don't usually fall in
this category, but be careful of C newcomers who give you their own
programs. Students of computer science are the worst of all, granted.
</para>
<para>
The only way to make these programs silent applications is
speakerectomy, or using the escape sequences by Martin Mares.
</para>
</sect1>

</article>

