Input: yealink - convert documentation 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, 93 insertions, 71 deletions

diff --git a/Documentation/input/yealink.txt b/Documentation/input/yealink.txt
index 8277b76ec506..b231d8baf4bb 100644
--- a/Documentation/input/yealink.txt
+++ b/Documentation/input/yealink.txt
@@ -1,8 +1,12 @@
+===============================================
 Driver documentation for yealink usb-p1k phones
+===============================================
+
+Status
+======
 
-0. Status
-~~~~~~~~~
 The p1k is a relatively cheap usb 1.1 phone with:
+
   - keyboard            full support, yealink.ko / input event API
   - LCD                 full support, yealink.ko / sysfs API
   - LED                 full support, yealink.ko / sysfs API
@@ -14,10 +18,11 @@ The p1k is a relatively cheap usb 1.1 phone with:
 For vendor documentation see http://www.yealink.com
 
 
-1. Compilation (stand alone version)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Compilation (stand alone version)
+=================================
+
 Currently only kernel 2.6.x.y versions are supported.
-In order to build the yealink.ko module do
+In order to build the yealink.ko module do::
 
   make
 
@@ -26,26 +31,28 @@ the Makefile is pointing to the location where your kernel sources
 are located, default /usr/src/linux.
 
 
-1.1 Troubleshooting
-~~~~~~~~~~~~~~~~~~~
-Q: Module yealink compiled and installed without any problem but phone
-   is not initialized and does not react to any actions.
-A: If you see something like:
-   hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
-   in dmesg, it means that the hid driver has grabbed the device first. Try to
-   load module yealink before any other usb hid driver. Please see the
-   instructions provided by your distribution on module configuration.
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+:Q: Module yealink compiled and installed without any problem but phone
+    is not initialized and does not react to any actions.
+:A: If you see something like:
+    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
+    in dmesg, it means that the hid driver has grabbed the device first. Try to
+    load module yealink before any other usb hid driver. Please see the
+    instructions provided by your distribution on module configuration.
 
-Q: Phone is working now (displays version and accepts keypad input) but I can't
-   find the sysfs files.
-A: The sysfs files are located on the particular usb endpoint. On most
-   distributions you can do: "find /sys/ -name get_icons" for a hint.
+:Q: Phone is working now (displays version and accepts keypad input) but I can't
+    find the sysfs files.
+:A: The sysfs files are located on the particular usb endpoint. On most
+    distributions you can do: "find /sys/ -name get_icons" for a hint.
 
 
-2. keyboard features
-~~~~~~~~~~~~~~~~~~~~
+keyboard features
+=================
+
 The current mapping in the kernel is provided by the map_p1k_to_key
-function:
+function::
 
    Physical USB-P1K button layout       input events
 
@@ -60,14 +67,15 @@ function:
         7      8      9                 7, 8, 9,
         *      0      #                 *, 0, #,
 
-  The "up" and "down" keys, are symbolised by arrows on the button.
-  The "pickup" and "hangup" keys are symbolised by a green and red phone
-  on the button.
+The "up" and "down" keys, are symbolised by arrows on the button.
+The "pickup" and "hangup" keys are symbolised by a green and red phone
+on the button.
 
 
-3. LCD features
-~~~~~~~~~~~~~~~
-The LCD is divided and organised as a 3 line display:
+LCD features
+============
+
+The LCD is divided and organised as a 3 line display::
 
     |[]   [][]   [][]   [][]   in   |[][]
     |[] M [][] D [][] : [][]   out  |[][]
@@ -79,18 +87,19 @@ The LCD is divided and organised as a 3 line display:
     [] [] [] [] [] [] [] [] [] [] [] []
 
 
-Line 1  Format (see below)      : 18.e8.M8.88...188
-        Icon names              :   M  D  :  IN OUT STORE
-Line 2  Format                  : .........
-        Icon name               : NEW REP SU MO TU WE TH FR SA
-Line 3  Format                  : 888888888888
+  Line 1  Format (see below)    : 18.e8.M8.88...188
+          Icon names            :   M  D  :  IN OUT STORE
+  Line 2  Format                : .........
+          Icon name             : NEW REP SU MO TU WE TH FR SA
+  Line 3  Format                : 888888888888
 
 
 Format description:
   From a userspace perspective the world is separated into "digits" and "icons".
   A digit can have a character set, an icon can only be ON or OFF.
 
-  Format specifier
+  Format specifier::
+
     '8' :  Generic 7 segment digit with individual addressable segments
 
     Reduced capability 7 segment digit, when segments are hard wired together.
@@ -105,9 +114,11 @@ Format description:
           elements.
 
 
-4. Driver usage
-~~~~~~~~~~~~~~~
-For userland the following interfaces are available using the sysfs interface:
+Driver usage
+============
+
+For userland the following interfaces are available using the sysfs interface::
+
   /sys/.../
            line1        Read/Write, lcd line1
            line2        Read/Write, lcd line2
@@ -118,38 +129,43 @@ For userland the following interfaces are available using the sysfs interface:
            show_icon    Write, display the element by writing the icon name.
 
            map_seg7     Read/Write, the 7 segments char set, common for all
-                        yealink phones. (see map_to_7segment.h)
+                        yealink phones. (see map_to_7segment.h)
 
            ringtone     Write, upload binary representation of a ringtone,
-                        see yealink.c. status EXPERIMENTAL due to potential
+                        see yealink.c. status EXPERIMENTAL due to potential
                         races between async. and sync usb calls.
 
 
-4.1 lineX
-~~~~~~~~~
-Reading /sys/../lineX will return the format string with its current value:
+lineX
+~~~~~
+
+Reading /sys/../lineX will return the format string with its current value.
 
-  Example:
-  cat ./line3
-  888888888888
-  Linux Rocks!
+  Example::
+
+    cat ./line3
+    888888888888
+    Linux Rocks!
 
 Writing to /sys/../lineX will set the corresponding LCD line.
+
  - Excess characters are ignored.
  - If less characters are written than allowed, the remaining digits are
    unchanged.
  - The tab '\t'and '\n' char does not overwrite the original content.
  - Writing a space to an icon will always hide its content.
 
-  Example:
-  date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
+  Example::
+
+    date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
 
   Will update the LCD with the current date & time.
 
 
-4.2 get_icons
-~~~~~~~~~~~~~
-Reading will return all available icon names and its current settings:
+get_icons
+~~~~~~~~~
+
+Reading will return all available icon names and its current settings::
 
   cat ./get_icons
   on M
@@ -172,45 +188,51 @@ Reading will return all available icon names and its current settings:
      RINGTONE
 
 
-4.3 show/hide icons
-~~~~~~~~~~~~~~~~~~~
+show/hide icons
+~~~~~~~~~~~~~~~
+
 Writing to these files will update the state of the icon.
 Only one icon at a time can be updated.
 
 If an icon is also on a ./lineX the corresponding value is
 updated with the first letter of the icon.
 
-  Example - light up the store icon:
-  echo -n "STORE" > ./show_icon
+  Example - light up the store icon::
 
-  cat ./line1
-  18.e8.M8.88...188
-               S
+    echo -n "STORE" > ./show_icon
 
-  Example - sound the ringtone for 10 seconds:
-  echo -n RINGTONE > /sys/..../show_icon
-  sleep 10
-  echo -n RINGTONE > /sys/..../hide_icon
+    cat ./line1
+    18.e8.M8.88...188
+                  S
 
+  Example - sound the ringtone for 10 seconds::
+
+    echo -n RINGTONE > /sys/..../show_icon
+    sleep 10
+    echo -n RINGTONE > /sys/..../hide_icon
+
+
+Sound features
+==============
 
-5. Sound features
-~~~~~~~~~~~~~~~~~
 Sound is supported by the ALSA driver: snd_usb_audio
 
 One 16-bit channel with sample and playback rates of 8000 Hz is the practical
 limit of the device.
 
-  Example - recording test:
-  arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
+  Example - recording test::
+
+    arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
 
-  Example - playback test:
-  aplay foobar.wav
+  Example - playback test::
 
+    aplay foobar.wav
+
+
+Credits & Acknowledgments
+=========================
 
-6. Credits & Acknowledgments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   - Olivier Vandorpe, for starting the usbb2k-api project doing much of
-        the reverse engineering.
+    the reverse engineering.
   - Martin Diehl, for pointing out how to handle USB memory allocation.
   - Dmitry Torokhov, for the numerous code reviews and suggestions.
-