merge XFree86 4.3.0.1 to -CURRENT

1 files changed, 572 insertions, 125 deletions

diff --git a/README.sgml b/README.sgml
index 56e2f7a..88c647c 100644
--- a/README.sgml
+++ b/README.sgml
@@ -1,25 +1,31 @@
-<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN">
+<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
+<!ENTITY % defs SYSTEM "defs.ent"> %defs;
+]>
 
 <article>
 <title>Mouse Support in XFree86
 <author>Kazutaka Yokota
-<date>28 February 1998
+<date>17 December 2002
+
+<ident>
+$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/mouse.sgml,v 1.13 2002/12/17 20:55:22 dawes Exp $
+</ident>
+
 <toc>
  
 <sect>Introduction <p>
 
-This document describes mouse support in XFree86 3.3.2, whose
-X servers have the revised mouse driver.
+This document describes mouse support in XFree86 &relvers;.
 
 Mouse configuration has often been mysterious task for
 novice users.
 However, once you learn several basics, it is straightforward
-to choose options in <tt>XF86Setup</tt> or write the <tt>"Pointer"</tt>
+to write the mouse <tt>"InputDevice"</tt>
 section in the <tt>XF86Config</tt> file by hand.
 
 <sect>Supported Hardware <p>
 
-XFree86 X servers support three classes of mice:
+The XFree86 X server supports three classes of mice:
 serial, bus and PS/2 mice.
 
 <descrip>
@@ -35,8 +41,8 @@ to the host computer.
 The modern serial mouse conforms to the PnP COM device specification
 so that the host computer can automatically detect the mouse
 and load an appropriate driver.
-The XFree86 3.3.2 X servers support this specification and can detect
-popular PnP serial mouse models.
+The XFree86 X server supports this specification and can detect
+popular PnP serial mouse models on most platforms.
 
 <tag>Bus mouse</tag>
 The bus mouse connects to a dedicated interface card in an expansion
@@ -61,6 +67,13 @@ The PS/2 mouse with additional features requires a specialized
 initialization procedure to enable these features.
 Without proper initialization, it behaves as though it were an ordinary
 two or three button mouse.
+
+<tag>USB mouse </tag>
+USB (Universal Serial Bus) ports are present on most modern
+computers. Several devices can be plugged into this bus, including
+mices and keyboards. 
+
+The XFree86 server includes support for USB mices on some systems.
 </descrip>
 
 Many mice nowadays can be used both as a serial mouse and as a PS/2 mouse.
@@ -71,10 +84,10 @@ used in such a way, even if you can find an appropriate
 adapter with which you can connect the PS/2 mouse to a serial port
 or visa versa.
 
-XFree86 now supports the mouse with a wheel, a roller or a knob.
+XFree86 supports the mouse with a wheel, a roller or a knob.
 Its action is detected as the Z (third) axis motion of the mouse.
 As the X server or clients normally do not use the Z axis movement of the 
-pointing device, a new configuration option, <tt>ZAxisMapping</tt>,
+pointing device, a configuration option, <tt>"ZAxisMapping"</tt>,
 is provided to assign the Z axis movement to another axis or a pair
 of buttons (see below).
 
@@ -85,23 +98,23 @@ of buttons (see below).
                                 Protocol Types
                 serial     PnP     BusMouse    PS/2   Extended PS/2
 OS platforms   protocols  serial   protocol  protocol  protocols
-                          "Auto"  "BusMouse"  "PS/2"   "xxxPS/2"
---------------------------------------------------------------------
-BSD/OS            Ok        ?         ?         ?         ?
-FreeBSD           Ok        Ok        Ok        Ok        SP*1
-FreeBSD(98)       Ok        ?         Ok        NA        NA
-Interactive Unix  Ok        NA        ?*1       ?*1       NA
-Linux             Ok        Ok        Ok        Ok        Ok
-Linux/98          Ok        ?         Ok        NA        NA
-LynxOS            Ok        NA        Ok        Ok        NA
-NetBSD            Ok        Ok        Ok        SP*1      NA
-NetBSD/pc98       Ok        ?         Ok        NA        NA
-OpenBSD           Ok        Ok        Ok        Ok*1      NA
-OS/2              SP*2      SP*2      SP*2      SP*2      SP*2
-SCO               Ok        ?         SP*1      SP*1      NA
-Solaris 2.x       Ok        NA*1      ?*1       Ok        NA
-SVR4              Ok        NA*1      SP*1      SP*1      NA
-PANIX             Ok        ?         SP*1      SP*1      NA
+                          "Auto"  "BusMouse"  "PS/2"   "xxxPS/2"    USB
+-------------------------------------------------------------------------
+BSD/OS            Ok        ?         ?         ?         ?          ?
+FreeBSD           Ok        Ok        Ok        Ok        SP*1       SP*1
+FreeBSD(98)       Ok        ?         Ok        NA        NA         ?
+Interactive Unix  Ok        NA        ?*1       ?*1       NA         ?
+Linux             Ok        Ok        Ok        Ok        Ok         ?
+Linux/98          Ok        ?         Ok        NA        NA         ?
+LynxOS            Ok        NA        Ok        Ok        NA         ?
+NetBSD            Ok        Ok        Ok        SP*1      SP*1       SP*1
+NetBSD/pc98       Ok        ?         Ok        NA        NA         NA
+OpenBSD           Ok        Ok        Ok        Ok*1      Ok*1       Ok*1
+OS/2              SP*2      SP*2      SP*2      SP*2      SP*2       ?
+SCO               Ok        ?         SP*1      SP*1      NA         ?
+Solaris 2.x       Ok        NA*1      ?*1       Ok        Ok         ?
+SVR4              Ok        NA*1      SP*1      SP*1      NA         ?
+PANIX             Ok        ?         SP*1      SP*1      NA         ?
 
 Ok: support is available,  NA: not available, ?: untested or unknown.
 SP: support is available in a different form
@@ -120,17 +133,32 @@ FreeBSD supports the <tt>"SysMouse"</tt> protocol which must be
 specified when the <tt>moused</tt> daemon is running in versions 2.2.1 
 or later.
 
+When running the <tt>moused</tt>daemon, you must always specify the
+<tt>/dev/sysmouse</tt> device and the <tt>"SysMouse"</tt> protocol
+to the X server, regardless of the actual type of your mouse.
+
+FreeBSD versions 2.2.6 or later include the kernel-level
+support for extended PS/2 mouse protocols and there is no need to specify
+the exact protocol name to the X server.
+Instead specify the <tt>"PS/2"</tt> or <tt>"Auto"</tt> protocol and 
+the X server will automatically make use of the kernel-level support.
+
+In fact, <tt>"Auto"</tt> protocol support is really efficient in these 
+versions.
+You may always specify <tt>"Auto"</tt> to any mouse, serial, 
+bus or PS/2, unless the mouse is an old serial model which doesn't
+support PnP.
+
 FreeBSD versions 2.2.5 or earlier do not support extended PS/2 
 mouse protocols (<tt>"xxxPS/2"</tt>).
 Always specify the <tt>"PS/2"</tt> protocol for any PS/2 mouse 
 in these versions regardless of the brand of the mouse.
 
-FreeBSD versions 2.2.6 or later include the kernel-level
-support for these mice.
-Specify the <tt>"PS/2"</tt> or <tt>"Auto"</tt> protocol and 
-the X server will automatically make use of the kernel-level support.
-In fact, you may always specify <tt>"Auto"</tt> to any mouse in these
-versions unless the mouse is an old serial model which doesn't support PnP.
+FreeBSD versions 3.1 or later have support for USB mice.
+Specify the <tt>"Auto"</tt> protocol for the <tt>/dev/ums0</tt> device.
+(If the <tt>moused</tt> daemon is running for the USB mouse, 
+you must use <tt>/dev/sysmouse</tt> instead of <tt>/dev/ums0</tt>
+as explained above.) See the <em>ums(4)</em> manual page for details. 
 
 <sect1>FreeBSD(98) <p>
 The PS/2 mouse is not supported.
@@ -145,7 +173,7 @@ Use <tt>/dev/mouse</tt> for the <tt>"BusMouse"</tt> protocol
 and <tt>/dev/kdmouse</tt> for the <tt>"PS/2"</tt> protocol. 
 These protocols are untested but may work. 
 Please send success/failure reports to
-<it/&lt;michael.rohleder@stadt-frankfurt.de&gt;/.
+<email>michael.rohleder@stadt-frankfurt.de</email>.
 
 <sect1>Linux <p>
 All protocol types should work.
@@ -158,25 +186,47 @@ The PnP serial mouse support (the <tt>"Auto"</tt> protocol) is disabled in
 LynxOS, because of limited TTY device driver functionality.
 
 <sect1>NetBSD <p>
-NetBSD does not support extended PS/2 mouse protocols (<tt>"xxxPS/2"</tt>).
+NetBSD 1.3.x and former does not support extended PS/2 mouse protocols
+(<tt>"xxxPS/2"</tt>). 
 The PS/2 mouse device driver <tt>/dev/pms</tt> emulates the bus mouse.
 Therefore, you should always specify the <tt>"BusMouse"</tt> protocol for 
 any PS/2 mouse regardless of the brand of the mouse.
+<p>
+The <tt>"wsmouse"</tt> protocol introduced in NetBSD
+1.4 along with the wscons console driver is supported. You need to run binaries
+compiled on NetBSD 1.4 to have support 
+for it though. Use <tt>"/dev/wsmouse0"</tt> for the device. Refer to the 
+<em>wsmouse(4)</em> manual page for kernel configuration informations.
+<p>
+This driver also provides support for USB mices. See the
+<em>ums(4)</em> manual page for details. 
 
 <sect1>NetBSD/pc98 <p>
 The PS/2 mouse is not supported.
 
 <sect1>OpenBSD <p>
-OpenBSD does not support extended PS/2 mouse protocols (<tt>"xxxPS/2"</tt>).
+The raw PS/2 mouse device driver <tt>/dev/psm0</tt> uses the raw PS/2
+mouse protocol.
 
-The PS/2 mouse device driver <tt>/dev/pms</tt> emulates the bus mouse.
-Specify the <tt>"BusMouse"</tt> protocol for 
-any PS/2 mouse regardless of the brand of the mouse when using this device.
+OpenBSD 2.2 and earlier does not support extended PS/2 mouse protocols
+(<tt>"xxxPS/2"</tt>) .  Therefore, you should specify the
+<tt>"PS/2"</tt> protocol for any PS/2 mouse regardless of the brand of
+the mouse.
 
-The raw PS/2 mouse device driver <tt>/dev/psm</tt> uses the standard PS/2
-mouse protocol.
-Therefore, you should specify the <tt>"PS/2"</tt> protocol for 
-any PS/2 mouse regardless of the brand of the mouse when using this device.
+OpenBSD 2.3 and later support all extended PS/2 mouse protocols. 
+You can select the <tt>"Auto"</tt> protocol for PnP PS/2
+mice or any specific extended (<tt>"xxxPS/2"</tt>) protocol
+for non PnP mice.
+
+There is also a cooked PS/2 mouse device driver <tt>/dev/pms0</tt>
+which emulates the bus mouse.  Specify the <tt>"BusMouse"</tt>
+protocol for any PS/2 mouse regardless of the brand of the mouse when
+using this device.
+<p>
+XFree86 3.3.6 support USB mices on OpenBSD 2.6 and later though the
+generic Human Interface Device (hid) <tt>/dev/uhid*</tt>. Select the
+<tt>"usb"</tt> protocol and the <tt>/dev/uhid*</tt> instance
+corresponding to your mouse as the device name.
 
 <sect1>OS/2 <p>
 XFree86/OS2 always uses the native mouse driver of the operating system
@@ -220,7 +270,7 @@ The PC-98 version of PANIX supports the bus mouse with the
 
 <sect>Configuring Your Mouse <p>
 
-Before using the <tt>XF86Setup</tt> or <tt>xf86config</tt> programs
+Before using the <tt>xf86config</tt> program
 to set up mouse configuration, you must identify the interface type,
 the device name and the protocol type of your mouse.
 Blindly trying every possible combination of mouse settings 
@@ -290,7 +340,7 @@ a suitable protocol type, the server will print the following
 error message and abort.
 
 <verb>
-xf86SetupMouse: Cannot determine the mouse protocol
+<mousename>: cannot determine the mouse protocol
 </verb>
 
 If the X server generates the above error message, you need to 
@@ -300,7 +350,7 @@ Choose one from the following list:
 <itemize>
 	<item><tt>GlidePoint</tt>
 	<item><tt>IntelliMouse</tt>
-	<item><tt>Logictech</tt>
+	<item><tt>Logitech</tt>
 	<item><tt>Microsoft</tt>
 	<item><tt>MMHittab</tt>
 	<item><tt>MMSeries</tt>
@@ -339,8 +389,13 @@ but you find that not all features of the mouse is available, that is
 because the X server does not have native support for that model of mouse
 and is using a ``compatible'' protocol according to PnP information.
 
-If you suspect this is the case with your mouse, please send report to
-<it/&lt;XFree86@XFree86.Org&gt;/.
+If you suspect this is the case with your mouse, please send a report to
+<email>XFree86@XFree86.Org</email>.
+
+<tag>USB mouse</tag>
+If your mouse is connected to the USB port, it can either be supported 
+by the <tt>"Auto"</tt> protocol, or by an OS-specific protocol (see below), 
+or as a generic Human Interface Device by the <tt>"usb"</tt> protocol. 
 
 <tag>Standardized protocols</tag>
 Mouse device drivers in your OS may use the standardized protocol 
@@ -354,8 +409,20 @@ Please refer to the OS support section of this file for more information.
 
 <sect>XF86Config Options <p>
 
-The following new options are available for the <tt>Pointer</tt> section
-of the <tt>XF86Config</tt> file.
+The old <tt>Pointer</tt> section has been replaced by a more general
+<tt>InputDevice</tt> section.  The following is a minimal example
+of an <tt>InputDevice</tt> section for a mouse:
+
+<code>
+Section "InputDevice"
+	Identifier	"Mouse 1"
+	Driver		"mouse"
+	Option		"Device"	"/dev/mouse"
+	Option		"Protocol"	"Auto"
+EndSection
+</code>
+
+The <tt>mouse</tt> driver supports the following config file options:
 
 <sect1>Buttons <p>
 This option tells the X server the number of buttons on the mouse.
@@ -369,28 +436,49 @@ using the <tt>ZAxisMapping</tt> option below, you need to take account
 of those buttons into <tt>N</tt> too.
 
 <verb>
-	Buttons N
+	Option	"Buttons"	"N"
 </verb>
 
 <sect1>ZAxisMappping <p>
-This option maps the Z axis (wheel) motion to a pair of buttons or to
+This option maps the Z axis (wheel) motion to buttons or to
 another axis.
 
 <verb>
-	ZAxisMapping X
-	ZAxisMapping Y
-	ZAxisMapping N M
+	Option	"ZAxisMapping"	"X"
+	Option	"ZAxisMapping"	"Y"
+	Option	"ZAxisMapping"	"N1 N2"
+	Option	"ZAxisMapping"	"N1 N2 N3 N4"
 </verb>
 
 The first example will map the Z axis motion to the X axis motion.
 Whenever the user moves the wheel/roller, its movement is reported as
 the X axis motion.  When the wheel/roller stays still, the real X axis
-motion is reported as is.  The last example will map negative Z axis
-motion to the button <tt>N</tt> and positive Z axis motion to 
-the button <tt>M</tt>.  If this option is used and the buttons <tt>N</tt> 
-or <tt>M</tt> actually exists in the mouse, 
+motion is reported as is.  The third example will map negative Z axis
+motion to the button <tt>N1</tt> and positive Z axis motion to 
+the button <tt>N2</tt>.  If this option is used and the buttons <tt>N1</tt> 
+or <tt>N2</tt> actually exists in the mouse, 
 their actions won't be detected by the X server.
 
+The last example is useful for the mouse with two wheels of which
+the second wheel is used to generate horizontal scroll action,
+and the mouse which has a knob or a stick which can detect the horizontal
+force applied by the user.
+The motion of the second wheel will be mapped to the buttons <tt>N3</tt>,
+for the negative direction, and <tt>N4</tt>, for the positive direction.
+If the buttons <tt>N3</tt> and <tt>N4</tt> actually exist in this mouse,
+their actions won't be detected by the X server.
+
+NOTE #1: horizontal movement may not always be detected
+by the current version of the XFree86 X servers,
+because there appears to be no accepted standard as to how the horizontal
+direction is encoded in mouse data.
+
+NOTE #2: Some mice think left is the negative horizontal direction, 
+others may think otherwise.  
+Moreover, there are some mice whose two wheels are both mounted vertically,
+and the direction of the second vertical wheel does not match the
+first one's.
+
 Currently this option can not be set in the <tt>XF86Setup</tt> program.
 You need to edit the <tt>XF86Config</tt> file by hand to add this option.
 
@@ -399,83 +487,151 @@ The following option will set the mouse device resolution to <tt>N</tt>
 counts per inch, if possible:
 
 <verb>
-	Resolution N
+	Option	"Resolution"	"N"
 </verb>
 
 Not all mice and OSs can support this option.
 This option can be set in the <tt>XF86Setup</tt> program.
 
+<sect1>Drag Lock Buttons <p>
+Some people find it difficult or inconvenient to hold a trackball
+button down, while at the same time moving the ball. Drag lock buttons
+simulate the holding down of another button. When a drag lock button
+is  first pressed, its target buttons is "locked" down until the
+second time the lock button is released, or until the button itself
+is pressed and released. This allows the starting of a drag, the movement
+of the trackball, and the ending of the drag to be separate operations.
+
+<verb>
+	Option	"DragLockButtons"	"W X Y Z"
+</verb>
+
+This option consists of pairs of buttons. Each lock button number
+is followed by the number of the button that it locks. In the above,
+button number "W" is a drag lock button for button "X" and button number
+"Y" is a drag lock button for button "Z".
+
+It may not be desirable to use multiple buttons as drag locks.
+Instead, a "master drag lock button" may be defined. A master drag
+lock button acts as a "META" key. After a master lock button is released,
+the next button pressed is "locked" and not released until the
+second time the real button is released.
+
+<verb>
+	Option	"DragLockButtons"	"M"
+</verb>
+
+Since button "M" is unpaired it is a master drag lock button.
+
 <sect>Mouse Gallery <p>
 
+In all of the examples below, it is assumed that <tt>/dev/mouse</tt> is
+a link to the appropriate serial port or PS/2 mouse device.
+
 <sect1>MS IntelliMouse  (serial, PS/2) <p>
-This mouse has been supported since XFree86 3.3.
-However, support in 3.3.2 is slightly different;
-the wheel movement is recognized as the Z axis motion.  
-This behavior is not compatible with XFree86
-3.3, but is more consistent with the support for other mice with
+This mouse has a wheel which also acts as the button 2 (middle button).
+The wheel movement is recognized as the Z axis motion.  
+This behavior is not compatible with XFree86 versions prior to 3.3.2,
+but is more consistent with the support for other mice with
 wheels or rollers. 
 If you want to make the wheel behave like before,
-you can use the new option <tt>"ZAxisMapping"</tt> as described above. 
+you can use the <tt>"ZAxisMapping"</tt> option as described above. 
 <p>
 IntelliMouse supports the PnP COM device specification.
 <p>
 To use this mouse as a serial device:
 <verb>
-	Protocol "Auto" or "IntelliMouse"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "IMPS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"IMPS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the wheel won't work in this case):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
 </verb>
 
-<sect1>Kensington Thinking Mouse (serial, PS/2) <p>
-This mouse has four buttons.
-Thinking Mouse supports the PnP COM device specification.
+<sect1>MS IntelliMouse Explorer (PS/2, USB) <p>
+This mouse has a wheel which also acts as the button 2 (middle button).
+There are two side buttons; they are recognized as the buttons 4 and 5.
+The wheel movement is recognized as the Z axis motion.  
+<p>
+To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
+initialization:
+<verb>
+	Option	"Protocol"	"ExplorerPS/2"
+</verb>
+
+To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
+initialization (the wheel and the side buttons won't work in this case):
+<verb>
+	Option	"Protocol"	"PS/2"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports automatic
+PS/2 mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+To use this mouse as the USB device and the OS supports the generic
+HID protocol:
+<verb>
+	Option	"Protocol"	"usb"
+</verb>
+
+To use this mouse as the USB device and the OS supports automatic
+mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+<sect1>Kensington Thinking Mouse and Kensington Expert Mouse (serial, PS/2) <p>
+These mice have four buttons.
+The Kensington Expert Mouse is really a trackball.
+Both Thinking mice  support the PnP COM device specification.
 <p>
 To use this mouse as a serial device:
 <verb>
-	Protocol "Auto" or "ThinkingMouse"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"ThinkingMouse"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "ThinkingMousePS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"ThinkingMousePS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the third and the fourth buttons act as though they
 were the first and the second buttons):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
 </verb>
 
 <sect1>Genius NetScroll (PS/2) <p>
@@ -485,22 +641,19 @@ recognized as the Z axis motion.
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "NetScrollPS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"NetScrollPS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the roller and the fourth button won't work):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
 </verb>
 
 <sect1>Genius NetMouse and NetMouse Pro (serial, PS/2) <p>
@@ -514,29 +667,64 @@ When used as a serial mouse, they are compatible with MS IntelliMouse.
 <p>
 To use these mice as a serial device:
 <verb>
-	Protocol "Auto" or "IntelliMouse"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "NetMousePS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"NetMousePS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the "magic button" and the third button won't work):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports automatic
+PS/2 mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+<sect1>Genius NetScroll Optical (PS/2, USB) <p>
+This mouse has a wheel which also acts as the button 2 (middle button),
+and two side buttons which are recognized as the buttons 4 and 5.
+It is compatible with NetMouse and NetMouse Pro.
+<p>
+To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
+initialization:
+<verb>
+	Option	"Protocol"	"NetMousePS/2"
+</verb>
+
+To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
+initialization (the wheel and the side buttons won't work):
+<verb>
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
+</verb>
+
+To use this mouse as the USB device and the OS supports the generic
+HID protocol:
+<verb>
+	Option	"Protocol"	"usb"
+</verb>
+
+To use this mouse as the USB device and the OS supports automatic
+mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
 </verb>
 
 <sect1>ALPS GlidePoint (serial, PS/2) <p>
@@ -547,29 +735,25 @@ button in order to make this pad behave like the other pad products.)
 <p>
 To use this pad as a serial device:
 <verb>
-	Protocol "GlidePoint"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"GlidePoint"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "GlidePointPS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"GlidePointPS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization:
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
 </verb>
 
 <sect1>ASCII MieMouse (serial, PS/2) <p>
@@ -583,29 +767,29 @@ serial mouse, it is compatible with MS IntelliMouse.
 <p>
 To use this mouse as a serial device:
 <verb>
-	Protocol "Auto" or "IntelliMouse"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "NetMousePS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"NetMousePS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the knob and the third button won't work):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
 </verb>
 
 <sect1>Logitech MouseMan+ and FirstMouse+ (serial, PS/2) <p>
@@ -619,38 +803,301 @@ They have MS IntelliMouse compatible mode when used as a serial mouse.
 <p>
 To use these mice as a serial device:
 <verb>
-	Protocol "Auto" or "IntelliMouse"
-	Device   "/dev/xxxx" (where xxxx is a serial port)
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
 initialization:
 <verb>
-	Protocol "MouseManPlusPS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"MouseManPlusPS/2"
 </verb>
 
 To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
 initialization (the wheel and the fourth button won't work):
 <verb>
-	Protocol "PS/2"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"PS/2"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports automatic
+PS/2 mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+<sect1>IBM ScrollPoint (PS/2) <p>
+ScrollPoint has a "stick" in between the two buttons.
+This "stick" is the same as the stick-shaped pointing device often
+found on notebook computers, on which you move the mouse cursor by
+pushing the stick.
+The stick movement is recognized as the Z axis motion.  
+You can push the stick to right and left, as well as forward and
+backward.  Give four numbers to <tt>ZAxisMapping</tt> option
+to map movement along all these four directions to button actions.
+<p>
+This mouse is compatible with Logitech MouseMan+.
+To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
+initialization:
+<verb>
+	Option	"Protocol"	"MouseManPlusPS/2"
+</verb>
+
+To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
+initialization (the stick won't work):
+<verb>
+	Option	"Protocol"	"PS/2"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports automatic
+PS/2 mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+<sect1>8D ScrollMouse (serial, PS/2) <p>
+ScrollMouse, also known as GyroMouse, has a "stick" similar to
+IBM ScrollPoint.
+The stick movement is recognized as the Z axis motion.  
+You can push the stick to right and left, as well as forward and
+backward.  Give four numbers to <tt>ZAxisMapping</tt> option
+to map movement along all these four directions to button actions.
+<p>
+ScrollMouse supports the PnP COM device specification.  When used as a
+serial mouse, it is compatible with MS IntelliMouse.
+<p>
+To use this mouse as a serial device:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
+initialization:
+<verb>
+	Option	"Protocol"	"IMPS/2"
+</verb>
+
+To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
+initialization (the stick won't work):
+<verb>
+	Option	"Protocol"	"PS/2"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports automatic
+PS/2 mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+
+<sect1>A4 Tech 4D mice (serial, PS/2, USB) <p>
+A4 Tech produces quit a number of mice with one or two wheels.
+Their mice may have 2, 3, or 4 buttons.
+The wheels movement is recognized as the Z axis motion.  
+Give four numbers to <tt>ZAxisMapping</tt> option
+to map movement of both wheels to button actions.
+<p>
+4D mice support the PnP COM device specification.  When used as a
+serial mouse, it is compatible with MS IntelliMouse.
+<p>
+To use this mouse as a serial device:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
+or:
+<verb>
+	Option	"Protocol"	"IntelliMouse"
+</verb>
+
+To use this mouse as the PS/2 device and the OS supports PS/2 mouse 
+initialization:
+<verb>
+	Option	"Protocol"	"IMPS/2"
+</verb>
+
+To use this mouse as the PS/2 device but the OS does not support PS/2 mouse 
+initialization (the wheels won't work):
+<verb>
+	Option	"Protocol"	"PS/2"
 </verb>
 
 To use this mouse as the PS/2 device and the OS supports automatic
 PS/2 mouse detection:
 <verb>
-	Protocol "Auto"
-	Device   "/dev/xxxx"  (where xxxx is the PS/2 mouse device)
+	Option	"Protocol"	"Auto"
+</verb>
+
+To use this mouse as the USB device and the OS supports the generic
+HID protocol:
+<verb>
+	Option	"Protocol"	"usb"
 </verb>
 
+To use this mouse as the USB device and the OS supports automatic
+mouse detection:
+<verb>
+	Option	"Protocol"	"Auto"
+</verb>
 
+<sect>Configuration Examples <p>
+
+This section shows some example <tt>InputDevice</tt> section for 
+popular mice.  All the examples assume that the mouse is connected to 
+the PS/2 mouse port, and the OS supports the PS/2 mouse initialization.
+It is also assumed that <tt>/dev/mouse</tt> is
+a link to the PS/2 mouse port.
+
+Logitech MouseMan+ has 4 buttons and a wheel.  The following example
+makes the wheel movement available as the button 5 and 6.
+
+<code>
+Section "InputDevice"
+	Identifier	"MouseMan+"
+	Driver		"mouse"
+	Option		"Device"	"/dev/mouse"
+	Option		"Protocol"	"MouseManPlusPS/2"
+	Option		"Buttons"	"6"
+	Option		"ZAxisMapping"	"5 6"
+EndSection
+</code>
+
+You can change button number assignment using the <tt>xmodmap</tt>
+command AFTER you start the X server with the above configuration.
+You may not like to use the wheel as the button 2 and rather want
+the side button (button 4) act like the button 2.  You may also
+want to map the wheel movement to the button 4 and 5.
+This can be done by the following command:
 
 <verb>
-$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/mouse.sgml,v 1.1.2.8 1998/03/02 09:58:25 dawes Exp $
+	xmodmap -e "pointer = 1 6 3 2 4 5"
+</verb>
 
+After this command is run, the correspondence between the buttons and 
+button numbers will be as shown in the following table.
 
+<verb>
+Physical Buttons	Reported as:
+------------------------------------
+1 Left Button		  Button 1
+2 Wheel Button		  Button 6
+3 Right Button		  Button 3
+4 Side Button		  Button 2
+5 Wheel Negative Move	  Button 4
+6 Wheel Positive Move	  Button 5
+</verb>
 
-$Xorg: mouse.sgml,v 1.3 2000/08/17 19:51:07 cpqbld Exp $
+For the MS IntelliMouse Explorer which as a wheel and 5 buttons,
+you may have the following <tt>InputDevice</tt> section. 
+
+<code>
+Section "InputDevice"
+	Identifier	"IntelliMouse Explorer"
+	Driver		"mouse"
+	Option		"Device"	"/dev/mouse"
+	Option		"Protocol"	"ExplorerPS/2"
+	Option		"Buttons"	"7"
+	Option		"ZAxisMapping"	"6 7"
+EndSection
+</code>
+
+The IntelliMouse Explorer has 5 buttons, thus, you should give "7"
+to the <tt>Buttons</tt> option if you want to map the wheel movement
+to buttons (6 and 7).
+With this configuration, the correspondence between the buttons and
+button numbers will be as follows:
+
+<verb>
+Physical Buttons	Reported as:
+------------------------------------
+1 Left Button		  Button 1
+2 Wheel Button		  Button 2
+3 Right Button		  Button 3
+4 Side Button 1		  Button 4
+5 Side Button 2		  Button 5
+6 Wheel Negative Move	  Button 6
+7 Wheel Positive Move	  Button 7
 </verb>
+
+You can change button number assignment using <tt>xmodmap</tt>
+AFTER you started the X server with the above configuration.
+
+<verb>
+	xmodmap -e "pointer = 1 2 3 4 7 5 6"
+</verb>
+
+The above command will moves the side button 2 to the button 7 and
+make the wheel movement reported as the button 5 and 6.  See 
+the table below.
+
+<verb>
+Physical Buttons	Reported as:
+------------------------------------
+1 Left Button		  Button 1
+2 Wheel Button		  Button 2
+3 Right Button		  Button 3
+4 Side Button 1		  Button 4
+5 Side Button 2		  Button 7
+6 Wheel Negative Move	  Button 5
+7 Wheel Positive Move	  Button 6
+</verb>
+
+For the A4 Tech WinEasy mouse which has two wheels and 3 buttons,
+you may have the following <tt>InputDevice</tt> section.  
+
+<code>
+Section "InputDevice"
+	Identifier	"WinEasy"
+	Driver		"mouse"
+	Option		"Device"	"/dev/mouse"
+	Option		"Protocol"	"IMPS/2"
+	Option		"Buttons"	"7"
+	Option		"ZAxisMapping"	"4 5 6 7"
+EndSection
+</code>
+
+The movement of the first wheel is mapped to the button 4 and 5.  The
+second wheel's movement will be reported as the buttons 6 and 7.
+
+The Kensington Expert mouse is really a trackball. It has 4 buttons
+arranged in a rectangle around the ball.
+
+<code>
+Section "InputDevice"
+	Identifier  "DLB"
+	Driver      "mouse"
+	Option      "Protocol" "ThinkingMousePS/2"
+	Option      "Buttons" "3"
+	Option      "Emulate3Buttons"
+	Option      "Device" "/dev/mouse"
+	Option      "DragLockButtons" "2 1 4 3"
+EndSection
+</code>
+In this example, button 2 is a drag lock button for button
+number 1, and button 4 is a drag lock button for button 3.
+Since button 2 is above button 1 and button 4 is above button 3
+in the layout of this trackball, this is reasonable.
+
+Because button 2 is being used as a drag lock, it can not be
+used as an ordinary button. However, it can be activated by
+using the "Emulate3Buttons" feature. However, some people my
+be unable to press two buttons at the same time. They may
+prefer the following <tt>InputDevice</tt> section which
+defines button 4 as a master drag lock button, and leaves
+button 2 free for ordinary use.
+<code>
+Section "InputDevice"
+	Identifier  "MasterDLB"
+	Driver      "mouse"
+	Option      "Protocol" "ThinkingMousePS/2"
+	Option      "Buttons" "3"
+	Option      "Device" "/dev/mouse"
+	Option      "DragLockButtons" "4"
+EndSection
+</code>
+
 </article>