man: more manpage tuning and polishing

1 files changed, 59 insertions, 45 deletions

diff --git a/man/joystick.man b/man/joystick.man
index 3696319..4158aa8 100644
--- a/man/joystick.man
+++ b/man/joystick.man
@@ -35,9 +35,7 @@ for playing legacy games, that have no native joystick support
 .B Do not use, if you want to
 - play games, that have native joystick support
 
-- use XI2 applications. The
-.B evdev(4)
-driver will suffice for those in most cases.
+- use XI2 applications. The evdev(4) driver will suffice for those in most cases.
 
 .PP
 You may mix above scenarios by setting the device 
@@ -79,7 +77,7 @@ are supported:
 .BI "Option \*qPath\*q \*q" string \*q
 Specifies the device through which the joystick can be accessed. This option is mandatory and there is no default setting.
 
-For Linux, joysticks are mostly accessible as
+In Linux, joysticks are usually accessible through
 .IR /dev/input/jsX " or " /dev/input/eventX .
 
 In *BSD, joysticks are usually recognized as 
@@ -93,21 +91,22 @@ is the time in milliseconds before a key starts repeating.
 is the number of times a key repeats per second.  Default: Xorg default
 .TP 7
 .BI "Option \*qDebugLevel\*q \*q" integer \*q
-If compiled with debugging information, controls the verbosity of the driver.
-The higher the DebugLevel, the more output is produced.
+Controls the verbosity of the driver for debugging purposes. The higher the DebugLevel, the more output is produced.
 Default: 0
 .TP 7
 .BI "Option \*qMapButton<number>\*q \*q" string \*q
-Sets the mapping of the joystick button to the desired action. Counting of buttons starts with 
+Sets the mapping of a joystick button to the desired action. Button counting starts with 
 .IR 1 ,
 Possible options are:
 .RS 7
 .TP 7
 .B "none"
-This joystick button won't do anything.
+Don't do anything
 .TP 7
 .BI "\*qbutton="<number> \*q
-The joystick button will generate a click with the specified button (starting with 1).
+Generate a pointer button event with button
+.I number
+(starting with 1).
 .TP 7
 .BI "\*qaxis="[<factor>]<axis> \*q
 Where
@@ -119,15 +118,15 @@ and
 .I <factor>
 is an optional amplifier of the axis, like
 .B -, +, -5, 0.4, 1.3, ...
-Use positive and negative values to control the direction. Default: 1.0
+Negative values invert the direction. Default: 1.0
 .TP 7
 .BI "\*qamplify="<factor> \*q
-Amplifies the movement of all axes by the given factor when pressed. Different
+Amplifies the movement of all axes by the given factor when this button is held down. Different
 factors can be combined.
 .TP 7
 .BI "\*qkey="<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
-When button is pressed, a series of keydown events with the specified scancode is
-generated. When the button is released, keyup events in the opposite
+When button is pressed, a series of keydown events with the specified scancodes is
+generated. When the button is released, matching keyup events in the opposite
 order are generated. You can specify up to 4 scancodes per button.
 
 See special section about key events below.
@@ -140,11 +139,15 @@ See special section about key events below.
 Disables either the generation of mouse events, key events or the generation of
 all X events by the driver. Press button again to allow the driver to generate 
 events again.
+
+You may also set the device
+.B floating
+from client space to prevent it from generating core events.
 .RE
 .PP
 .TP 7
 .BI "Option \*qMapAxis<number>\*q \*q" string \*q
-Sets the mapping of the axis to the desired action. Counting of axes starts with
+Sets the mapping of the axis to the desired action. Axis counting starts with
 .IR 1 ,
 the parameter may contain:
 .RS 7
@@ -158,7 +161,9 @@ can be one of:
 
 .TP 7
 .B \*qvaluator\*q
-Send extra valuator events for this axis. The valuators will be numbered ascending, starting with 2 (valuator 0 and 1 are reserved for pointer movement). The range of the valuators is always 
+Send extra valuator events for this axis. The valuators will be numbered ascending, starting with 2 (valuator 0 and 1 are reserved for pointer movement). Please consider using the evdev(4) input driver if you are only interested in XI2 features.
+
+The range of the valuators is always 
 .IR -32767 " to " 32768 .
 Neither
 .B mode
@@ -183,17 +188,17 @@ is an optional amplifier of the axis, like
 .B -, +, -5, 0.4, 1.3, ...
 Negative values will invert the movement. Default: 1.0
 .TP 7
-.BI "\*qkeylow= "<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
+.BI "\*qkeylow="<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
 .TP 7
 .BI "\*qkeyhigh="<scancode>[,<scancode>[,<scancode>[,<scancode>]]]
 When the axis is moved out of the deadzone, a series of keydown events according 
-to the direction of the movement is generated. When the axis is released, keyup 
-events will be generated. You can specify up to 4 scancodes for each direction. 
+to the direction of the movement is generated. When the axis is released, matching keyup 
+events in opposite order will be generated. You can specify up to 4 scancodes for each direction.
 
 .B keylow
-defines the keys to be generated when the axis is moved in negative direction (ie. left or up),
+defines the keys to be generated when the axis is moved in negative direction (left or up),
 .B keyhigh
-defines the keys to be generated when the axis is moved in positive direction (ie. right or down).
+defines the keys to be generated when the axis is moved in positive direction (right or down).
 
 If 
 .B mode
@@ -266,17 +271,17 @@ The default configuration is as follows:
 .SH "ACCELERATED AXIS CONFIGURATION"
 .B Accelerated
 mode should be selected, if the axis is a
-.IR pad ,
-which reports only three states: negative, center, positive. It will produce a smooth acceleration of the movement
-when the axis is deflected. The speed will be affected by the factor of the axis, but not the acceleration speed.
+.IR "directional pad" ,
+which reports only three states: negative, center, positive. It will result in smoothly accelerated movement
+when the axis is deflected. An optional factor will affect the acceleration and final speed.
 
-This example will set up the axis as scrolling vertically inverted, with half of the speed:
+This example will set up the axis as scrolling vertically inverted, with half the speed:
 .nf
 .BI "  Option \*qMapAxis1\*q     \*q" "mode=accelerated axis=-0.5zy" \*q
 .fi
 
-This example maps four buttons to the four half axes, so you can use them like a pad. The movement will get half
-the normal speed:
+This example maps four buttons to the four pointer directions, so you can use the buttons like a d-pad. The movement will be accelerated
+with half the normal speed:
 .nf
 .BI "  Option \*qMapButton1\*q     \*q" "axis=+0.5x" \*q
 .BI "  Option \*qMapButton2\*q     \*q" "axis=-0.5x" \*q
@@ -285,15 +290,11 @@ the normal speed:
 .fi
 
 .SH "ABSOLUTE AXIS CONFIGURATION"
-With the
+In
 .B absolute
-axis mode, the position of the cursor will be fixed to the position, according to the deflection of the axis.
-This fixed position is calculated around the previous position of the cursor. You can specify the range in pixels,
-the cursor can move. The default range is the
-.I width
-of the screen, when mapped to the x-axis and the
-.I height
-of the screen, when mapped to the y-axis. This mode can be combined with the other modes without problems.
+axis mode, the
+.I position of the cursor will match the
+.I position of the configured axis, but relative to the previous position of the cursor. You can specify the range in which the cursor can move. The default range is the screen size.
 
 In this example the first axis gets a range from left to the right of the screen. The second axis gets a
 total range of 200 pixels, 100 to the top and 100 to the bottom:
@@ -303,15 +304,13 @@ total range of 200 pixels, 100 to the top and 100 to the bottom:
 .fi
 
 .SH "GENERATING KEY EVENTS"
-Providing a \*qkey=<scancode>[,<scancode>[...]]\*q option will generate X Events with the specified scancodes
-when the joystick button is pressed or the axis changed its position. When the button/axis is released, the keys are released in the reverse order.
+Providing a \*qkey=<scancode>[,<scancode>[...]]\*q option will generate X Events with specified scancodes. When the button/axis is released, the keys will be released in opposite order.
 
-To lookup keycodes for KeySyms, you can use
+If you want a certain KeySym, look up the matching scancode using
 .BR "xmodmap -pk" .
-You can use unused keycodes and map them to a KeySym of your choice using xmodmap(1).
+The scancodes depend on the configured keyboard layout. You can also use unused keycodes and map them to a KeySym of your choice using xmodmap(1).
 
-You can specify up to 4 scancodes per joystick button/axis, which is useful to use modificators. Make sure you use modificators
-that are necessary to get a certain keysym.
+You can specify up to 4 scancodes per joystick button/axis, which can be used for modificators to get the KeySym you want.
 
 Examples:
 .nf
@@ -324,13 +323,15 @@ when the button is pressed.
 .nf
 .BI "  Option \*qMapButton1\*q     \*q" "key=50,40" \*q
 .fi
-will generate a Shift_L+d which will be an uppercase 
+will generate a 
+.I "Shift_L+d"
+which will result in an uppercase 
 .IR d .
 
 .nf
 .BI "  Option \*qMapButton1\*q     \*q" "key=65" \*q
 .fi
-is for the  
+will result in a
 .IR "space " key.
 
 .nf
@@ -343,11 +344,17 @@ will map the first and third axis to the arrow keys
 .IR left " and " right
 and the second and fourth axis to the arrow keys
 .IR up " and " down .
+
 The keys for the first two axes will be generated in an interval according to the value of the axis. The autorepeat speed of the first axis will be half the speed of that of the second axis.
 The keys for the third and fourth axis are generated once when the axis moves out of the deadzone and when it moves back into the deadzone. X.Org will autorepeat those keys according to current keyboard settings.
 
 .SH "XI2 Events"
-If you only care about raw events instead of using the joystick as a mouse replacement, don't forget to unmap and add valuators to all axes and map the remaining buttons:
+If you only care about raw valuator events instead of using the joystick to control the cursor, consider using the evdev(4)
+input driver. If you still use the
+.B joystick
+driver for raw events, make sure to unmap all axes/buttons and add the
+.B valuator
+option to the axes:
 
 .nf
 .BI "  Option  \*qMapAxis1\*q      \*q" "mode=none valuator" \*q
@@ -363,17 +370,24 @@ If you only care about raw events instead of using the joystick as a mouse repla
 \ \ ...
 .fi
 
+Remember, that valuators 0 and 1 are reserved for pointer movement, additional axes will start with valuator 2.
+
 You might also want to set the device "floating" to stop it from reporting core events:
 .nf
 .BI "  Option  \*qFloating\*q      \*q" "true" \*q
 .fi
 
 .SH "NOTES"
+It is not recommended to enable the
+.B joystick
+input driver by default unless explicitely requested by the user.
+
 Configuration through
 .I InputClass
-sections is recommended in X servers 1.8 and later. See xorg.conf.d(5) for more details. An example xorg.conf.d snipped is provided in 
+sections is recommended in X servers 1.8 and later. See xorg.conf.d(5) for more details. An example xorg.conf.d(5) snipped is provided in 
 .I ${sourcecode}/config/50-joystick-all.conf
 
+
 Configuration through hal fdi files is recommended in X servers 1.5,
 1.6 and 1.7. An example hal policy file is still provided in 
 .I ${sourcecode}/config/50-x11-input-joystick.fdi
@@ -384,6 +398,6 @@ to be placed in
 .SH "SEE ALSO"
 __xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), xorg.conf.d(5), Xserver(__appmansuffix__), X(__miscmansuffix__), xmodmap(1)
 .SH AUTHORS
-Sascha Hlusiak (2007-2011),
+Sascha Hlusiak (2007-2012),
 .fi
 Frederic Lepied (1995-1999)