While developing a patch for bug 598820, I found the following behavior (introduced in commit 46dee1da on 2009-10-26 by Peter Hutterer):

When the [x] Enable mouse clicks with touchpad checkbox is toggled on, gnome-settings-daemon always assigns button 1 or 3 to one-finger tap and 3 or 1 to two-finger tap, depending on the Mouse Orientation setting. This is intended to reverse the X button mapping which normally maps 1 to 1 and 3 to 3, but switches them around for Left-handed mouse orientation.

Right-handed:
One-finger tap -- physical button 1 (left) -- logical button 1 (primary)
Two-finger tap -- physical button 3 (right) -- logical button 3 (secondary)

Left-handed:
One-finger tap -- physical button 3 (right) -- logical button 1 (primary)
Two-finger tap -- physical button 1 (left) -- logical button 3 (secondary)

So taps always map to the primary and secondary logical buttons.

This works as intended in the simple case when the X button map is only changed by the gnome-settings-daemon itself, which is limited to these two maps -- identity for right-handed and "swap 1 and 3" for left-handed.

However, as soon as the user sets a non-trivial button map where the values 1 and 3 are not on their usual places, taps will not map correctly.

Example: The user has a touchpad with hardware left and right buttons, and since he is accustomed to taps always mapping to primary and secondary buttons, wishes to use the hardware buttons to navigate Back and Forward in browser. He invokes xinput set-button-map to install the following button map: 8 2 9 4 5 6 7 1 3 10 11 12 (swapping 8/1 and 9/3).

Expected behavior:
Left hardware button -- physical button 1 -- logical button 8 (Back)
Right hardware button -- physical button 3 -- logical button 9 (Forward)
One-finger tap -- [...] -- logical button 1 (primary)
Two-finger tap -- [...] -- logical button 3 (secondary)

Actual behavior:
Left and right hardware buttons -- as expected
One-finger tap -- physical button 1 -- logical button 8 (Back)
Two-finger tap -- physical button 3 -- logical button 9 (Forward)

To do the right thing, g-s-d needs to analyze the current X button map, search it for the values 1 and 3, and pass the appropriate indexes to the "Synaptics Tap Action" property. A patch follows.