Input: convert gamepad specification into ReST format

This file require minimum adjustments to be a valid ReST file.
Do it, in order to be able to parse it with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

1 files changed, 63 insertions, 31 deletions

diff --git a/Documentation/input/gamepad.txt b/Documentation/input/gamepad.txt
index 3f6d8a5e9cdc..1bc4555c0ccb 100644
--- a/Documentation/input/gamepad.txt
+++ b/Documentation/input/gamepad.txt
@@ -1,15 +1,19 @@
-                            Linux Gamepad API
-----------------------------------------------------------------------------
+-----------------
+Linux Gamepad API
+-----------------
 
-1. Intro
-~~~~~~~~
+:Author: 2013 by David Herrmann <dh.herrmann@gmail.com>
+
+
+Intro
+~~~~~
 Linux provides many different input drivers for gamepad hardware. To avoid
 having user-space deal with different button-mappings for each gamepad, this
 document defines how gamepads are supposed to report their data.
 
-2. Geometry
-~~~~~~~~~~~
-As "gamepad" we define devices which roughly look like this:
+Geometry
+~~~~~~~~
+As "gamepad" we define devices which roughly look like this::
 
             ____________________________              __
            / [__ZL__]          [__ZR__] \               |
@@ -35,6 +39,7 @@ As "gamepad" we define devices which roughly look like this:
                       Menu Pad
 
 Most gamepads have the following features:
+
   - Action-Pad
     4 buttons in diamonds-shape (on the right side). The buttons are
     differently labeled on most devices so we define them as NORTH,
@@ -58,8 +63,9 @@ Most gamepads have the following features:
     Many devices provide force-feedback features. But are mostly just
     simple rumble motors.
 
-3. Detection
-~~~~~~~~~~~~
+Detection
+~~~~~~~~~
+
 All gamepads that follow the protocol described here map BTN_GAMEPAD. This is
 an alias for BTN_SOUTH/BTN_A. It can be used to identify a gamepad as such.
 However, not all gamepads provide all features, so you need to test for all
@@ -85,75 +91,101 @@ devices that report a small subset of the events.
 No other devices, that do not look/feel like a gamepad, shall report these
 events.
 
-4. Events
-~~~~~~~~~
+Events
+~~~~~~
+
 Gamepads report the following events:
 
-Action-Pad:
+- Action-Pad:
+
   Every gamepad device has at least 2 action buttons. This means, that every
   device reports BTN_SOUTH (which BTN_GAMEPAD is an alias for). Regardless
   of the labels on the buttons, the codes are sent according to the
   physical position of the buttons.
+
   Please note that 2- and 3-button pads are fairly rare and old. You might
   want to filter gamepads that do not report all four.
-    2-Button Pad:
+
+    - 2-Button Pad:
+
       If only 2 action-buttons are present, they are reported as BTN_SOUTH and
       BTN_EAST. For vertical layouts, the upper button is BTN_EAST. For
       horizontal layouts, the button more on the right is BTN_EAST.
-    3-Button Pad:
+
+    - 3-Button Pad:
+
       If only 3 action-buttons are present, they are reported as (from left
       to right): BTN_WEST, BTN_SOUTH, BTN_EAST
       If the buttons are aligned perfectly vertically, they are reported as
       (from top down): BTN_WEST, BTN_SOUTH, BTN_EAST
-    4-Button Pad:
+
+    - 4-Button Pad:
+
       If all 4 action-buttons are present, they can be aligned in two
       different formations. If diamond-shaped, they are reported as BTN_NORTH,
       BTN_WEST, BTN_SOUTH, BTN_EAST according to their physical location.
       If rectangular-shaped, the upper-left button is BTN_NORTH, lower-left
       is BTN_WEST, lower-right is BTN_SOUTH and upper-right is BTN_EAST.
 
-D-Pad:
+- D-Pad:
+
   Every gamepad provides a D-Pad with four directions: Up, Down, Left, Right
   Some of these are available as digital buttons, some as analog buttons. Some
   may even report both. The kernel does not convert between these so
   applications should support both and choose what is more appropriate if
   both are reported.
-    Digital buttons are reported as:
+
+    - Digital buttons are reported as:
+
       BTN_DPAD_*
-    Analog buttons are reported as:
+
+    - Analog buttons are reported as:
+
       ABS_HAT0X and ABS_HAT0Y
-      (for ABS values negative is left/up, positive is right/down)
 
-Analog-Sticks:
+  (for ABS values negative is left/up, positive is right/down)
+
+- Analog-Sticks:
+
   The left analog-stick is reported as ABS_X, ABS_Y. The right analog stick is
   reported as ABS_RX, ABS_RY. Zero, one or two sticks may be present.
   If analog-sticks provide digital buttons, they are mapped accordingly as
   BTN_THUMBL (first/left) and BTN_THUMBR (second/right).
-    (for ABS values negative is left/up, positive is right/down)
 
-Triggers:
+  (for ABS values negative is left/up, positive is right/down)
+
+- Triggers:
+
   Trigger buttons can be available as digital or analog buttons or both. User-
   space must correctly deal with any situation and choose the most appropriate
   mode.
+
   Upper trigger buttons are reported as BTN_TR or ABS_HAT1X (right) and BTN_TL
   or ABS_HAT1Y (left). Lower trigger buttons are reported as BTN_TR2 or
   ABS_HAT2X (right/ZR) and BTN_TL2 or ABS_HAT2Y (left/ZL).
+
   If only one trigger-button combination is present (upper+lower), they are
   reported as "right" triggers (BTN_TR/ABS_HAT1X).
-    (ABS trigger values start at 0, pressure is reported as positive values)
 
-Menu-Pad:
+  (ABS trigger values start at 0, pressure is reported as positive values)
+
+- Menu-Pad:
+
   Menu buttons are always digital and are mapped according to their location
   instead of their labels. That is:
-    1-button Pad: Mapped as BTN_START
-    2-button Pad: Left button mapped as BTN_SELECT, right button mapped as
-                  BTN_START
+
+    - 1-button Pad:
+
+      Mapped as BTN_START
+
+    - 2-button Pad:
+
+      Left button mapped as BTN_SELECT, right button mapped as BTN_START
+
   Many pads also have a third button which is branded or has a special symbol
   and meaning. Such buttons are mapped as BTN_MODE. Examples are the Nintendo
   "HOME" button, the XBox "X"-button or Sony "PS" button.
 
-Rumble:
-  Rumble is advertised as FF_RUMBLE.
+- Rumble:
 
-----------------------------------------------------------------------------
-  Written 2013 by David Herrmann <dh.herrmann@gmail.com>
+  Rumble is advertised as FF_RUMBLE.