Preparing to create a man page describing the parameters

that control the synaptics driver.

3 files changed, 189 insertions, 184 deletions

diff --git a/Makefile b/Makefile
index 8ab9370..cd93f8d 100644
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,7 @@ VERSION=0.14.2
 INSTALLED_X = $(DESTDIR)/usr/X11R6
 LOCAL_X = Xincludes/usr/X11R6
 BINDIR = $(DESTDIR)/usr/local/bin
-MANDIR = $(DESTDIR)/usr/local/man/man1
+MANDIR = $(DESTDIR)/usr/local/man
 
 ifeq ($(ARCH),)
   ARCH = $(shell /bin/arch)
@@ -78,12 +78,15 @@ all:: synaptics_drv.o synclient syndaemon
 
 install: $(BINDIR)/synclient $(BINDIR)/syndaemon $(INSTALLED_X)/$(LIBDIR)/modules/input/synaptics_drv.o install-man
 
-install-man: $(MANDIR)/synclient.1 $(MANDIR)/syndaemon.1
+install-man: $(MANDIR)/man1/synclient.1 $(MANDIR)/man1/syndaemon.1 $(MANDIR)/man5/synaptics.5
 
-$(MANDIR)/synclient.1: manpages/synclient.1
+$(MANDIR)/man1/synclient.1: manpages/synclient.1
 	install --mode=0644 -D $< $@
 
-$(MANDIR)/syndaemon.1: manpages/syndaemon.1
+$(MANDIR)/man1/syndaemon.1: manpages/syndaemon.1
+	install --mode=0644 -D $< $@
+
+$(MANDIR)/man5/synaptics.5: manpages/synaptics.5
 	install --mode=0644 -D $< $@
 
 $(BINDIR)/synclient : synclient
@@ -126,7 +129,7 @@ tags::
 	etags -o TAGS *.c *.h
 
 uninstall::
-	$(RM) $(BINDIR)/synclient $(BINDIR)/syndaemon $(INSTALLED_X)/lib/modules/input/synaptics_drv.o $(MANDIR)/synclient.1 $(MANDIR)/syndaemon.1
+	$(RM) $(BINDIR)/synclient $(BINDIR)/syndaemon $(INSTALLED_X)/lib/modules/input/synaptics_drv.o $(MANDIR)/man1/synclient.1 $(MANDIR)/man1/syndaemon.1 $(MANDIR)/man5/synaptics.5
 
 distribution : synaptics-$(VERSION).tar.bz2
 
@@ -145,7 +148,7 @@ synaptics-$(VERSION).tar.bz2 : FORCE
 	rm -rf $(DST)
 	mkdir $(DST) $(DST)/manpages $(DST)/script $(DST)/test $(DST)/docs
 	cp -a $(ALLFILES) $(DST)
-	cp -a manpages/{synclient.1,syndaemon.1} $(DST)/manpages/
+	cp -a manpages/{synclient.1,syndaemon.1,synaptics.5} $(DST)/manpages/
 	cp -a script/{usbmouse,usbhid} $(DST)/script/
 	cp -a test/{test-pad.c,testprotocol.c} $(DST)/test/
 	cp -a docs/tapndrag.dia $(DST)/docs/
diff --git a/README b/README
index 0479fce..e5df5d8 100644
--- a/README
+++ b/README
@@ -55,184 +55,8 @@ works on your computer.
 Parameters
 ----------
 
-The driver behavior can be configured with parameters. These
-parameters are options in the InputDevice section in the XFree86
-config file. See the INSTALL file for a working example. If you have
-the SHMConfig parameter enabled, these parameters can also be changed
-at runtime with the synclient program.
-
-Parameter:		Type:   Description:
-
-Device			String	Synaptics device
-Protocol		String	"auto-dev" (automatic, default), "psaux" (raw) or
-				"event" (linux 2.5 kernel events)
-SHMConfig		Bool	switch on/off shared memory for configuration
-LeftEdge		Int	coordinates for left edge
-RightEdge		Int	coordinates for right edge
-TopEdge			Int	coordinates for top edge
-BottomEdge		Int	coordinates for bottom edge
-FingerLow		Int	When finger pressure drops below this value, the
-				driver counts it as a release.
-FingerHigh		Int	When finger pressure goes above this value, the
-				driver counts it as a touch.
-MaxTapTime		Int	max. time (in milliseconds) for detecting a tap
-MaxTapMove		Int	max. movement of the finger for detecting a tap
-MaxDoubleTapTime	Int	max. time (in milliseconds) for detecting a double tap
-ClickTime		Int	the duration of the mouse click generated by tapping
-FastTaps		Bool	Makes the driver react faster to a single tap, but
-				also makes double clicks caused by double tapping slower.
-VertScrollDelta		Int	move distance of the finger for a scroll event
-HorizScrollDelta	Int	move distance of the finger for a scroll event
-EdgeMotionMinZ		Int	finger pressure at which minimum edge motion speed is set
-EdgeMotionMaxZ		Int	finger pressure at which maximum edge motion speed is set
-EdgeMotionMinSpeed	Int	slowest setting for edge motion speed
-EdgeMotionMaxSpeed	Int	fastest setting for edge motion speed
-EdgeMotionUseAlways	Bool	If on, edge motion is also used for normal movements,
-				if off, egde motion is used only when dragging
-Repeater		String	repeater device
-MinSpeed		Float	min. Speed factor
-MaxSpeed		Float	max. Speed factor
-AccelFactor		Float	acceleration factor
-UpDownScrolling		Bool	If on, the up/down buttons generate button 4/5 events.
-				If off, the up button generates a double click and
-				the down button generates a button 2 event.
-EmulateMidButtonTime	Int	max time (in milliseconds) for middle button emulation.
-TouchpadOff		Int	Switch off the touchpad. Valid values are:
-				0 : Touchpad is enabled
-				1 : Touchpad is switched off
-				2 : Only tapping is switched off
-GuestMouseOff		Bool	switch on/off guest mouse (often a stick)
-LockedDrags		Bool	If off, a tap and drag gesture ends when you release
-				the finger. If on, the gesture is active until you
-				tap a second time.
-RTCornerButton		Int	Which mouse button is reported on a right top corner tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-RBCornerButton		Int	Which mouse button is reported on a right bottom corner tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-LTCornerButton		Int	Which mouse button is reported on a left top corner tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-LBCornerButton		Int	Which mouse button is reported on a left bottom corner tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-TapButton1		Int	Which mouse button is reported on a non-corner one-finger tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-TapButton2		Int	Which mouse button is reported on a non-corner two-finger tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-TapButton3		Int	Which mouse button is reported on a non-corner three-finger tap
-				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
-CircularScrolling	Bool	If on, circular scrolling is used (see below)
-CircScrollDelta		Float	Move angle (radians) of finger to generate a scroll event
-CircScrollTrigger	Int	Trigger region on the touchpad to start circular scrolling
-				0=All Edges, 1=Top Edge, 2=Top Right Corner, 3=Right Edge,
-				4=Bottom Right Corner, 5=Bottom Edge, 6=Bottom Left Corner,
-				7=Left Edge, 8=Top Left Corner
-CircularPad	        Bool	Instead of being a rectangle, the edge is the ellipse
-				enclosed by the Left/Right/Top/BottomEdge parameters.
-				For circular touchpads.
-PalmDetect		Bool	If palm detection should be enabled
-PalmMinWidth		Int	Minimum width at which touch is considered a palm
-PalmMinZ		Int	Minimum finger pressure at which touch is considered a palm
-CoastingSpeed		Float	Coasting threshold scrolling speed. 0 disables coasting.
-
-The LeftEdge, RightEdge, TopEdge and BottomEdge parameters are used to
-define the edge and corner areas of the touchpad. The parameters split
-the touchpad area in 9 pieces, like this:
-
-        LeftEdge  RightEdge
-            v         v
-            |         |       Physical top edge
-          1 |    2    | 3
-        -------------------   TopEdge
-            |         |
-         4  |    5    | 6
-            |         |
-        -------------------   BottomEdge
-         7  |    8    | 9
-            |         |       Physical bottom edge
-        ^                 ^
-     Physical          Physical
-     left edge        right edge
-
-Coordinates to the left of LeftEdge are part of the left edge (areas
-1, 4 and 7), coordinates to the left of LeftEdge and above TopEdge
-(area 1) are part of the upper left corner, etc. A good way to find
-appropriate edge parameters is to enable the SHMConfig option and run
-"synclient -m 1" to see the x/y coordinates corresponding to different
-positions on the touchpad.
-
-A tap event happens when the finger is touched and released in a time
-interval shorter than MaxTapTime, and the touch and release
-coordinates are less than MaxTapMove units apart. A "touch" event
-happens when the Z value goes above FingerHigh, and an "untouch" event
-happens when the Z value goes below FingerLow.
-
-The MaxDoubleTapTime parameter has the same function as the MaxTapTime
-parameter, but for the second, third, etc tap in a tap sequence. If
-you can't perform double clicks fast enough (for example, xmms depends
-on fast double clicks), try reducing this parameter. If you can't get
-word selection to work in xterm (ie button down, button up, button
-down, move mouse), try increasing this parameter.
-
-The ClickTime parameter controls the delay between the button down and
-button up X events generated in response to a tap event. A too long
-value can cause undesirable autorepeat in scroll bars and a too small
-value means that visual feedback from the gui application you are
-interacting with is harder to see.
-
-The MinSpeed, MaxSpeed and AccelFactor parameters control the pointer
-motion speed. The speed value defines the scaling between touchpad
-coordinates and screen coordinates. When moving the finger very
-slowly, the MinSpeed value is used, when moving very fast the MaxSpeed
-value is used. When moving the finger at moderate speed, you get a
-pointer motion speed somewhere between MinSpeed and MaxSpeed. If you
-don't want any acceleration, set MinSpeed and MaxSpeed to the same
-value.
-
-The MinSpeed, MaxSpeed and AccelFactor parameters don't have any
-effect on scrolling speed. Scrolling speed is determined solely from
-the VertScrollDelta and HorizScrollDelta parameters. To disable
-vertical or horizontal scrolling, set VertScrollDelta or
-HorizScrollDelta to zero.
-
-When hitting an egde, movement can be automatically continued.
-If EdgeMotionUseAlways is false, edge motion is only used when
-dragging. With EdgeMotionUseAlways set to true, it is also used for
-normal cursor movements.
-
-Edge motion speed is calculated by taking into account the amount of
-pressure applied to the touchpad. The sensitivity can be adjusted
-using the EdgeMotion parameters. If the pressure is below
-EdgeMotionMinZ, EdgeMotionMinSpeed is used, and if the pressure is
-greater than EdgeMotionMaxZ, EdgeMotionMaxSpeed is used. For a
-pressure value between EdgeMotionMinZ and EdgeMotionMaxZ, the speed is
-increased linearly.
-
-Since most synaptics touchpad models don't have a button that
-corresponds to the middle button on a mouse, the driver can emulate
-middle mouse button events. If you press both the left and right mouse
-buttons at almost the same time (no more than EmulateMidButtonTime
-milliseconds apart) the driver generates a middle mouse button event.
-
-Circular scrolling acts like a scrolling wheel on the trackpad.
-Scrolling is engaged when a drag starts in the given CircScrollTrigger
-region, which can be all edges, a particular side, or a particular
-corner. Once scrolling is engaged, moving your finger in clockwise
-circles around the trackpad will generate scroll down events and
-counter clockwise scroll up events. Lifting your finger will disengage
-circular scrolling. Use tight circles near the center of the pad for
-fast scrolling and large circles for better control. When used
-together with vertical scrolling, hitting the upper or lower right
-corner will seamlessly switch over from vertical to circular
-scrolling.
-
-Coasting is enabled by setting the CoastingSpeed parameter to a
-non-zero value. When coasting is enabled, horizontal/vertical
-scrolling can continue after the finger is released from the
-lower/right edge of the touchpad. The driver computes the scrolling
-speed corresponding to the finger speed immediately before the finger
-leaves the touchpad. If this scrolling speed is larger than the
-CoastingSpeed parameter (measured in scroll events per second), the
-scrolling will continue with the same speed in the same direction
-until the finger touches the touchpad again.
+See the synaptics(5) manual page for a description of the available
+driver parameters.
 
 
 FAQ
diff --git a/manpages/synaptics.5 b/manpages/synaptics.5
new file mode 100644
index 0000000..42610fc
--- /dev/null
+++ b/manpages/synaptics.5
@@ -0,0 +1,178 @@
+The driver behavior can be configured with parameters. These
+parameters are options in the InputDevice section in the XFree86
+config file. See the INSTALL file for a working example. If you have
+the SHMConfig parameter enabled, these parameters can also be changed
+at runtime with the synclient program.
+
+Parameter:		Type:   Description:
+
+Device			String	Synaptics device
+Protocol		String	"auto-dev" (automatic, default), "psaux" (raw) or
+				"event" (linux 2.5 kernel events)
+SHMConfig		Bool	switch on/off shared memory for configuration
+LeftEdge		Int	coordinates for left edge
+RightEdge		Int	coordinates for right edge
+TopEdge			Int	coordinates for top edge
+BottomEdge		Int	coordinates for bottom edge
+FingerLow		Int	When finger pressure drops below this value, the
+				driver counts it as a release.
+FingerHigh		Int	When finger pressure goes above this value, the
+				driver counts it as a touch.
+MaxTapTime		Int	max. time (in milliseconds) for detecting a tap
+MaxTapMove		Int	max. movement of the finger for detecting a tap
+MaxDoubleTapTime	Int	max. time (in milliseconds) for detecting a double tap
+ClickTime		Int	the duration of the mouse click generated by tapping
+FastTaps		Bool	Makes the driver react faster to a single tap, but
+				also makes double clicks caused by double tapping slower.
+VertScrollDelta		Int	move distance of the finger for a scroll event
+HorizScrollDelta	Int	move distance of the finger for a scroll event
+EdgeMotionMinZ		Int	finger pressure at which minimum edge motion speed is set
+EdgeMotionMaxZ		Int	finger pressure at which maximum edge motion speed is set
+EdgeMotionMinSpeed	Int	slowest setting for edge motion speed
+EdgeMotionMaxSpeed	Int	fastest setting for edge motion speed
+EdgeMotionUseAlways	Bool	If on, edge motion is also used for normal movements,
+				if off, egde motion is used only when dragging
+Repeater		String	repeater device
+MinSpeed		Float	min. Speed factor
+MaxSpeed		Float	max. Speed factor
+AccelFactor		Float	acceleration factor
+UpDownScrolling		Bool	If on, the up/down buttons generate button 4/5 events.
+				If off, the up button generates a double click and
+				the down button generates a button 2 event.
+EmulateMidButtonTime	Int	max time (in milliseconds) for middle button emulation.
+TouchpadOff		Int	Switch off the touchpad. Valid values are:
+				0 : Touchpad is enabled
+				1 : Touchpad is switched off
+				2 : Only tapping is switched off
+GuestMouseOff		Bool	switch on/off guest mouse (often a stick)
+LockedDrags		Bool	If off, a tap and drag gesture ends when you release
+				the finger. If on, the gesture is active until you
+				tap a second time.
+RTCornerButton		Int	Which mouse button is reported on a right top corner tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+RBCornerButton		Int	Which mouse button is reported on a right bottom corner tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+LTCornerButton		Int	Which mouse button is reported on a left top corner tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+LBCornerButton		Int	Which mouse button is reported on a left bottom corner tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+TapButton1		Int	Which mouse button is reported on a non-corner one-finger tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+TapButton2		Int	Which mouse button is reported on a non-corner two-finger tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+TapButton3		Int	Which mouse button is reported on a non-corner three-finger tap
+				0=No action, 1=Left Button, 2=Middle Button, 3=Right Button
+CircularScrolling	Bool	If on, circular scrolling is used (see below)
+CircScrollDelta		Float	Move angle (radians) of finger to generate a scroll event
+CircScrollTrigger	Int	Trigger region on the touchpad to start circular scrolling
+				0=All Edges, 1=Top Edge, 2=Top Right Corner, 3=Right Edge,
+				4=Bottom Right Corner, 5=Bottom Edge, 6=Bottom Left Corner,
+				7=Left Edge, 8=Top Left Corner
+CircularPad	        Bool	Instead of being a rectangle, the edge is the ellipse
+				enclosed by the Left/Right/Top/BottomEdge parameters.
+				For circular touchpads.
+PalmDetect		Bool	If palm detection should be enabled
+PalmMinWidth		Int	Minimum width at which touch is considered a palm
+PalmMinZ		Int	Minimum finger pressure at which touch is considered a palm
+CoastingSpeed		Float	Coasting threshold scrolling speed. 0 disables coasting.
+
+The LeftEdge, RightEdge, TopEdge and BottomEdge parameters are used to
+define the edge and corner areas of the touchpad. The parameters split
+the touchpad area in 9 pieces, like this:
+
+        LeftEdge  RightEdge
+            v         v
+            |         |       Physical top edge
+          1 |    2    | 3
+        -------------------   TopEdge
+            |         |
+         4  |    5    | 6
+            |         |
+        -------------------   BottomEdge
+         7  |    8    | 9
+            |         |       Physical bottom edge
+        ^                 ^
+     Physical          Physical
+     left edge        right edge
+
+Coordinates to the left of LeftEdge are part of the left edge (areas
+1, 4 and 7), coordinates to the left of LeftEdge and above TopEdge
+(area 1) are part of the upper left corner, etc. A good way to find
+appropriate edge parameters is to enable the SHMConfig option and run
+"synclient -m 1" to see the x/y coordinates corresponding to different
+positions on the touchpad.
+
+A tap event happens when the finger is touched and released in a time
+interval shorter than MaxTapTime, and the touch and release
+coordinates are less than MaxTapMove units apart. A "touch" event
+happens when the Z value goes above FingerHigh, and an "untouch" event
+happens when the Z value goes below FingerLow.
+
+The MaxDoubleTapTime parameter has the same function as the MaxTapTime
+parameter, but for the second, third, etc tap in a tap sequence. If
+you can't perform double clicks fast enough (for example, xmms depends
+on fast double clicks), try reducing this parameter. If you can't get
+word selection to work in xterm (ie button down, button up, button
+down, move mouse), try increasing this parameter.
+
+The ClickTime parameter controls the delay between the button down and
+button up X events generated in response to a tap event. A too long
+value can cause undesirable autorepeat in scroll bars and a too small
+value means that visual feedback from the gui application you are
+interacting with is harder to see.
+
+The MinSpeed, MaxSpeed and AccelFactor parameters control the pointer
+motion speed. The speed value defines the scaling between touchpad
+coordinates and screen coordinates. When moving the finger very
+slowly, the MinSpeed value is used, when moving very fast the MaxSpeed
+value is used. When moving the finger at moderate speed, you get a
+pointer motion speed somewhere between MinSpeed and MaxSpeed. If you
+don't want any acceleration, set MinSpeed and MaxSpeed to the same
+value.
+
+The MinSpeed, MaxSpeed and AccelFactor parameters don't have any
+effect on scrolling speed. Scrolling speed is determined solely from
+the VertScrollDelta and HorizScrollDelta parameters. To disable
+vertical or horizontal scrolling, set VertScrollDelta or
+HorizScrollDelta to zero.
+
+When hitting an egde, movement can be automatically continued.
+If EdgeMotionUseAlways is false, edge motion is only used when
+dragging. With EdgeMotionUseAlways set to true, it is also used for
+normal cursor movements.
+
+Edge motion speed is calculated by taking into account the amount of
+pressure applied to the touchpad. The sensitivity can be adjusted
+using the EdgeMotion parameters. If the pressure is below
+EdgeMotionMinZ, EdgeMotionMinSpeed is used, and if the pressure is
+greater than EdgeMotionMaxZ, EdgeMotionMaxSpeed is used. For a
+pressure value between EdgeMotionMinZ and EdgeMotionMaxZ, the speed is
+increased linearly.
+
+Since most synaptics touchpad models don't have a button that
+corresponds to the middle button on a mouse, the driver can emulate
+middle mouse button events. If you press both the left and right mouse
+buttons at almost the same time (no more than EmulateMidButtonTime
+milliseconds apart) the driver generates a middle mouse button event.
+
+Circular scrolling acts like a scrolling wheel on the trackpad.
+Scrolling is engaged when a drag starts in the given CircScrollTrigger
+region, which can be all edges, a particular side, or a particular
+corner. Once scrolling is engaged, moving your finger in clockwise
+circles around the trackpad will generate scroll down events and
+counter clockwise scroll up events. Lifting your finger will disengage
+circular scrolling. Use tight circles near the center of the pad for
+fast scrolling and large circles for better control. When used
+together with vertical scrolling, hitting the upper or lower right
+corner will seamlessly switch over from vertical to circular
+scrolling.
+
+Coasting is enabled by setting the CoastingSpeed parameter to a
+non-zero value. When coasting is enabled, horizontal/vertical
+scrolling can continue after the finger is released from the
+lower/right edge of the touchpad. The driver computes the scrolling
+speed corresponding to the finger speed immediately before the finger
+leaves the touchpad. If this scrolling speed is larger than the
+CoastingSpeed parameter (measured in scroll events per second), the
+scrolling will continue with the same speed in the same direction
+until the finger touches the touchpad again.