Input: docs - update joystick documentation a bit

Consolidate use instructions and userspace API notes into the same chapter;
remove completely obsolete references, move into a separate subdirectory.

Signed-off-by: Dmitry Torokhov <[e-mail]>

Documentation/input/index.rst

···
 The Linux Input Documentation
 =============================
 
-Core API
-========
+Contents:
 
 .. toctree::
    :maxdepth: 2
···
    input
    input-programming
    event-codes
-   joystick
-   joystick-api
+   joydev/index
    multi-touch-protocol
    gamepad
    gameport-programming

Documentation/input/joydev/index.rst

···
+.. include:: <isonum.txt>
+
+======================
+Linux Joystick support
+======================
+
+:Copyright: |copy| 1996-2000 Vojtech Pavlik <[e-mail]> - Sponsored by SuSE
+
+.. class:: toc-title
+
+	Table of Contents
+
+.. toctree::
+	:maxdepth: 3
+	:numbered:
+
+	joystick
+	joystick-api

Documentation/input/joystick-api.rst Documentation/input/joydev/joystick-api.rst

···
-==========================
-Joystick API Documentation
-==========================
+=====================
+Programming Interface
+=====================
 
 :Author: Ragnar Hojland Espinosa <[e-mail]> - 7 Aug 1998
+
+Introduction
+============
+
+.. important::
+   This document describes legacy ``js`` interface. Newer clients are
+   encouraged to switch to the generic event (``evdev``) interface.
+
+The 1.0 driver uses a new, event based approach to the joystick driver.
+Instead of the user program polling for the joystick values, the joystick
+driver now reports only any changes of its state. See joystick-api.txt,
+joystick.h and jstest.c included in the joystick package for more
+information. The joystick device can be used in either blocking or
+nonblocking mode, and supports select() calls.
+
+For backward compatibility the old (v0.x) interface is still included.
+Any call to the joystick driver using the old interface will return values
+that are compatible to the old interface. This interface is still limited
+to 2 axes, and applications using it usually decode only 2 buttons, although
+the driver provides up to 32.
 
 Initialization
 ==============
···
 Open the joystick device following the usual semantics (that is, with open).
 Since the driver now reports events instead of polling for changes,
 immediately after the open it will issue a series of synthetic events
-(JS_EVENT_INIT) that you can read to check the initial state of the
+(JS_EVENT_INIT) that you can read to obtain the initial state of the
 joystick.
 
 By default, the device is opened in blocking mode::
···
 
 .. note::
 
- As for version 1.2.8, the queue is circular and able to hold 64
+ As of version 1.2.8, the queue is circular and able to hold 64
  events. You can increment this size bumping up JS_BUFF_SIZE in
  joystick.h and recompiling the driver.
 

Documentation/input/joystick-parport.rst

···
 
 .. _joystick-parport:
 
-===================================
-Linux Joystick parport drivers v2.0
-===================================
+==============================
+Parallel port Joystick Drivers
+==============================
 
 :Copyright: |copy| 1998-2000 Vojtech Pavlik <[e-mail]>
 :Copyright: |copy| 1998 Andree Borrmann <[e-mail]>
···
 happen include burning your parallel port, and/or the sticks and joystick
 and maybe even more. Like when a lightning kills you it is not our problem.
 
-Intro
-=====
+Introduction
+============
 
 The joystick parport drivers are used for joysticks and gamepads not
 originally designed for PCs and other computers Linux runs on. Because of
···
 for two more interfaces.
 
 PC parallel port pinout
------------------------
+=======================
 
 ::
 

Documentation/input/joystick.rst Documentation/input/joydev/joystick.rst

···
 .. include:: <isonum.txt>
 
-============================
-Linux Joystick driver v2.0.0
-============================
-
-:Copyright: |copy| 1996-2000 Vojtech Pavlik <[e-mail]> - Sponsored by SuSE
-
-
-Disclaimer
-==========
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the Free
-Software Foundation; either version 2 of the License, or (at your option)
-any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
-or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-more details.
-
-You should have received a copy of the GNU General Public License along
-with this program; if not, write to the Free Software Foundation, Inc., 59
-Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-Should you need to contact me, the author, you can do so either by e-mail
-- mail your message to <[e-mail]>, or by paper mail: Vojtech Pavlik,
-Simunkova 1594, Prague 8, 182 00 Czech Republic
-
-For your convenience, the GNU General Public License version 2 is included
-in the package: See the file COPYING.
-
-Intro
-=====
+Introduction
+============
 
 The joystick driver for Linux provides support for a variety of joysticks
 and similar devices. It is based on a larger project aiming to support all
 input devices in Linux.
 
-Should you encounter any problems while using the driver, or joysticks
-this driver can't make complete use of, I'm very interested in hearing about
-them. Bug reports and success stories are also welcome.
+The mailing list for the project is:
 
-The input project website is at:
+	[e-mail]
 
-	http://atrey.karlin.mff.cuni.cz/~vojtech/input/
-
-There is also a mailing list for the driver at:
-
-	[e-mail]
-
-send "subscribe linux-joystick Your Name" to subscribe to it.
+send "subscribe linux-input" to [e-mail] to subscribe to it.
 
 Usage
 =====
···
 For basic usage you just choose the right options in kernel config and
 you should be set.
 
-inpututils
-----------
+Utilities
+---------
 
-For testing and other purposes (for example serial devices), a set of
-utilities is available at the abovementioned website. I suggest you download
-and install it before going on.
+For testing and other purposes (for example serial devices), there is a set
+of utilities, such as ``jstest``, ``jscal``, and ``evtest``,
+usually packaged as ``joystick``, ``input-utils``, ``evtest``, and so on.
+
+``inputattach`` utility is required if your joystick is connected to a
+serial port.
 
 Device nodes
 ------------
 
-For applications to be able to use the joysticks,
-you'll have to manually create these nodes in /dev::
+For applications to be able to use the joysticks, device nodes should be
+created in /dev. Normally it is done automatically by the system, but
+it can also be done by hand::
 
     cd /dev
     rm js*
···
 
 This way, after the next reboot your joystick will remain calibrated. You
 can also add the ``jscal -p`` line to your shutdown script.
-
 
 HW specific driver information
 ==============================
···
 Game console and 8-bit pads and joysticks
 -----------------------------------------
 
+These pads and joysticks are not designed for PCs and other computers
+Linux runs on, and usually require a special connector for attaching
+them through a parallel port.
+
 See :ref:`joystick-parport` for more info.
 
 SpaceTec/LabTec devices
···
 :Q: My joystick doesn't work with Quake / Quake 2. What's the cause?
 :A: Quake / Quake 2 don't support joystick. Use joy2key to simulate keypresses
     for them.
-
-Programming Interface
-=====================
-
-The 1.0 driver uses a new, event based approach to the joystick driver.
-Instead of the user program polling for the joystick values, the joystick
-driver now reports only any changes of its state. See joystick-api.txt,
-joystick.h and jstest.c included in the joystick package for more
-information. The joystick device can be used in either blocking or
-nonblocking mode and supports select() calls.
-
-For backward compatibility the old (v0.x) interface is still included.
-Any call to the joystick driver using the old interface will return values
-that are compatible to the old interface.  This interface is still limited
-to 2 axes, and applications using it usually decode only 2 buttons, although
-the driver provides up to 32.