[Patch] Documenting pointer acceleration

[Peter Hutterer]

On Thu, Dec 10, 2009 at 10:24:20PM +0100, Simon Thum wrote:
> since some users complained about the absence of ptr accel from local
> docs, I made an attempt to update it a bit. It's not much, but I figured
>  that's better than nothing.
> 
> I'm open to suggestions though, in particular, I'd like to know where
> people look first when they seek this kind of information.

I'd be good if you could ask the users that complained ;)
 
> In general, is it reasonable to point to the wiki from a man page? That
> one's separate if the answer is no.

My gut feeling is no, especially since that page doesn't change that much
anymore, does it?
It might be worth adding it as a simple text description to $docdir.

> From 84ceba932e93c0b2467be696c9878c4d9c59312b Mon Sep 17 00:00:00 2001
> From: Simon Thum <simon.thum at gmx.de>
> Date: Sun, 18 Oct 2009 15:10:56 +0200
> Subject: [PATCH 1/2] xinput: clarify role of set-ptr-feedback
> 
> ---
>  man/xinput.man |    5 ++++-
>  1 files changed, 4 insertions(+), 1 deletions(-)
> 
> diff --git a/man/xinput.man b/man/xinput.man
> index fbf445e..d78cb32 100644
> --- a/man/xinput.man
> +++ b/man/xinput.man
> @@ -39,7 +39,10 @@ Change the mode of \fIdevice\fP.
>  .PP
>  .TP 8
>  .B --set-ptr-feedback \fIdevice\fP \fIthreshold\fP \fInum\fP \fIdenom\fP
> -Change the acceleration of \fIdevice\fP.
> +Change the pointer acceleration parameters of \fIdevice\fP. The xset man page
> +has more detials. For X.org 1.7
            ^^^ typo     ^^ X.Org X Server 1.7

> +and above, there are additional device properties pertaining pointer
> +acceleration (\fIDevice Accel ...\fP).
>  .PP
>  .TP 8
>  .B --set-integer-feedback \fIdevice\fP \fIindex\fP \fIvalue\fP
> -- 
> 1.6.4.4

This isn't overly informative. It should clarify what role the properties
play in light of the --set-ptr-feedback options, e.g. whether
--set-ptr-feedback changes the properties and the other way round.


> From b09538fc5328ad0678bf6351b95fb20bfa1101e9 Mon Sep 17 00:00:00 2001
> From: Simon Thum <simon.thum at gmx.de>
> Date: Sun, 18 Oct 2009 17:49:41 +0200
> Subject: [PATCH] xset: update info about pointer acceleration
> 
> ---
>  xset.man |   18 +++++++++++++-----
>  1 files changed, 13 insertions(+), 5 deletions(-)
> 
> diff --git a/xset.man b/xset.man
> index 0377640..a4fb267 100644
> --- a/xset.man
> +++ b/xset.man
> @@ -192,9 +192,10 @@ abbreviated to 'm'.
>  The parameters for the mouse are `acceleration' and `threshold'.
>  The acceleration can be specified as an integer, or as a simple
>  fraction.
> -The mouse, or whatever pointer the machine is connected to,
> -will go `acceleration' times as fast when it travels more than `threshold'
> -pixels in a short time.  This way, the mouse can be used for precise
> +By default the mouse (or whatever) pointer will
> +go `acceleration' times as fast when it travels more than `threshold'
> +pixels in 10 ms, including a small transition range.
> +This way, the mouse can be used for precise
>  alignment when it is moved slowly, yet it can be set to travel across
>  the screen in a flick of the wrist when desired.  One or both
>  parameters for the 
> @@ -208,8 +209,15 @@ If the `threshold' parameter is provided and 0, the `acceleration'
>  parameter will be used in the exponent of a more natural and continuous
>  formula, giving precise control for slow motion but big reach for fast
>  motion, and a progressive transition for motions in between.
> -Recommended `acceleration' value in this case is 3/2 to 2, but not
> +Recommended `acceleration' value in this case is 3/2 to 3, but not
>  limited to that range.
> +
> +In the X.org server 1.6 and above, the behaviour described so far is linked to
> +the default profile. There are other profiles (i.e. functions determining pointer
> +acceleration depending on device velocity) and additional settings, so the above
> +description may be inaccurate in non-default cases. In X.org server 1.7, these are
                    ^^ s/be inaccurate/not apply/        ^ the
> +available as input device properties (see xinput).
> +
>  .PP
>  .TP 8
>  .B p
> @@ -280,7 +288,7 @@ These settings will be reset to default values when you log out.
>  Note that not all X implementations are guaranteed to honor all of these
>  options.
>  .SH "SEE ALSO"
> -X(__miscmansuffix__), Xserver(1), xmodmap(1), xrdb(1), xsetroot(1)
> +X(__miscmansuffix__), Xserver(1), xmodmap(1), xrdb(1), xsetroot(1), xinput(1)
>  .SH AUTHOR
>  Bob Scheifler, MIT Laboratory for Computer Science
>  .br
> -- 
> 1.6.4.4

Cheers,
  Peter