Bug 48885

Description of Problem:

The gpm documentation is incomplete, incorrect, or unclear
(call it what you like) with regards to the use of mice
of the type "Genius NetMouse" and "Genius Netmouse Pro".

Such mouse types connected to a serial instead of a PS/2
port behave as "IntelliMouse" devices (a decoder called
"ms3" in gpm), not "metmouse" as stated in the docs.

How Reproducible: 100% (here)

Steps to Reproduce:
1. Connect a serial Genius NetMouse (Pro) to a linux box.
2. Configure gpm as type "netmouse" on the corresponding
   serial port.
3. Restart gpm, e.g.
   $ gpm -k
   $ gpm -t netmouse -m /dev/ttyS0

Actual Results:

root@sunshine:~ # gpm -t netmouse -m /dev/mouse
root@sunshine:~ # netmouse: No acknowledge (got 77)
gpm: oops() invoked from gpm.c(998)
mouse initialization failed: No such file or directory

Expected Results:

At least both mouse buttons and the thumb button (button 3)
should work as expected, without error messages when
invoking gpm.

Additional Information:

This description template isn't helping me much, I'm trying
to describe a documentation error.  ;-)

The documentation source file doc.gpm says:
[...]
@item ms3
        A decoder for the new serial IntelliMouse devices, the ones
        with three buttons and a protocol incompatible with older
        ones. The wheel is currently unused.

@item imps2
        ``IntelliMouse'' on the ps/2 port.

@item netmouse
        Decodes the ``Genius NetMouse'' type of devices.
[...]

Correct might be:
[...]
@item ms3
        A decoder for the new serial IntelliMouse devices, the ones
        with three buttons and a protocol incompatible with older
        ones. The ``Genius NetMouse'' type of devices also uses this
        protocol when connected as a serial mouse. The wheel is
        currently unused.

@item imps2
        ``IntelliMouse'' on the ps/2 port.           
                                          
@item netmouse                                          
        Decodes the ``Genius NetMouse'' type of devices on the
        ps/2 port. For serial ``Netmouse'' devices, use the
        ``ms3'' decoder.
[...]

Just to go sure you belive me, check http://www.xfree86.org/4.0.1/mouse6.html#30
for the X11 interpretation of things.

This documentation bug kept me riddled for months. I nearly bought
a new mouse instead.  ;-)

Furthermore (additional bug report? naaa), the gpm program "mouse-test"
isn't packaged by you. Furtherfurthermore (...), this program fails on
this Genius mouse type.

Furthermore, I've adapted the included contrib/imwheel.patch to actually
work with RedHat's patched source. This fixes some little ditties, perhaps
you'd like to include it to enable imwheel use of gpm (i.e. for /dev/gpmdata
for busmice). I think it even enables the wheel on IntelliMice (see
documentation extract above), but you'd better ask imwheel's author.

Thanks for listening,
happy mousing,
Moritz