Documentation: More detailed mouse documentation.

And a few additions to the documentation standards.

Doc/sphinx/docdoc.rst

@@ -66,6 +66,28 @@ The titles of all major sections have all words capitalized. (The ones with
 The minor sections and subsections (---) and (~~~) have only the first word and
 Simba specific words (like Simba itself) capitalized.
 
-Try to stick to the Python documentation standards. 
+Try to stick to the Python documentation standards.
 ( http://docs.python.org/using/index.html )
 
+References
+----------
+
+Sphinx has references, most of the .rst files contain labels and references.
+
+A label looks something like this:
+
+.. code-block:: python
+
+    .. _<X>-<Y>:
+
+Where X is either the name of file or folder; and Y is the name of the
+file/function if X is a folder. For referring to specific functions for example,
+use:
+
+.. code-block:: python
+
+    .. _scriptref-movemouse:
+
+To define a label for the MoveMouse function. Labels are always placed right
+above section/chapter declarations.
+

Doc/sphinx/scriptref/mouseandkeyboard.rst

@@ -1,6 +1,9 @@
 Mouse and Keyboard
 ==================
 
+Simba contains several functions to manipulate the mouse and keyboard.
+Features range from clicking and moving the mouse to faking keypresses.
+
 Types
 -----
 
@@ -27,15 +30,43 @@ list.
 Mouse Functions
 ---------------
 
+Simba's coordinate system is similar to most computer coordinate systems.
+Coordinate *(0, 0)* is the top-left part of your selected window (the desktop by
+default). To get to point *(5, 0)* we move five pixels to the right; to get to
+*(5, 5)* we move five pixels to the right, and five pixels down.
+
+Recall that the first value is *x*, the second value is *y*: *(x, y)*
+
+..
+    TODO: Picture?
+
 MoveMouse
 ~~~~~~~~~
 
+.. _scriptref-movemouse:
+
 .. code-block:: pascal
-   
+
     procedure MoveMouse(x, y: integer);
 
 MoveMouse moves the mouse pointer to the specified x and y coordinates.
 
+The following example will move the mouse to position *(10, 10)*; relative
+to the selected client. (To get to point (10, 10) visually, recall that (0, 0)
+is the *top left* part and to get to (10, 10) we move 10 pixels to the right,
+and ten pixels down.
+
+.. code-block:: pascal
+
+    Program MouseMove;
+
+    begin
+      MoveMouse(10, 10);
+    end.
+
+
+.. _scriptref-getmousepos:
+
 GetMousePos
 ~~~~~~~~~~~
 
@@ -43,9 +74,23 @@ GetMousePos
 
     procedure GetMousePos(var x, y: integer);
 
-GetMousePos returns the current position of the mouse in x and
-y.
+GetMousePos returns the current position of the mouse in x and y.
 
+The following example moves the mouse 1 pixel to the right, relative to its
+current position:
+
+.. code-block:: pascal
+
+    Program MouseMoveRelative;
+
+    var x, y: integer;
+
+    begin
+      GetMousePos(x, y);
+      MoveMouse(x + 1, y);
+    end.
+
+.. _scriptref-holdmouse:
 
 HoldMouse
 ~~~~~~~~~
@@ -54,9 +99,14 @@ HoldMouse
 
     procedure HoldMouse(x, y: Integer; clickType: TClickType);
 
-HoldMouse holds the given mouse button (clickType) down at the specified
-x, y coordinate. If the mouse if not at the given x, y yet, the mouse position
-will be set to x, y.
+HoldMouse holds the given mouse button specified by clickType down at the
+specified *(x, y)* coordinate. If the mouse if not at the given
+(*x, y)* yet, the mouse position will be set to *(x, y)*.
+
+..
+    TODO: Example
+
+.. _scriptref-releasemouse:
 
 ReleaseMouse
 ~~~~~~~~~~~~
@@ -69,6 +119,11 @@ HoldMouse holds the given mouse button (clickType) down at the specified
 x, y coordinate. If the mouse if not at the given x, y yet, the
 mouse position will be set to x, y.
 
+..
+    TODO: Example
+
+.. _scriptref-clickmouse:
+
 ClickMouse
 ~~~~~~~~~~
 
@@ -77,7 +132,9 @@ ClickMouse
     procedure ClickMouse(x, y: Integer; clickType: Integer):
 
 ClickMouse performs a click with the given mouse button (clickType) at the
-specified x, y coordinate.
+specified *(x, y)* coordinate. This ``click`` equals an immediate click, with no
+wait between holding down and releasing the mouse button. To create a more
+human-like effect, use the HoldMouse and ReleaseMouse functions.
 
 Keyboard Functions
 ------------------
@@ -85,18 +142,22 @@ Keyboard Functions
 Keyboard functions are obviously used to manipulate the keyboard input. It can
 also be used to read states of specific keys.
 
+.. _scriptref-keydown:
 
 KeyDown
 ~~~~~~~
 
-
 .. code-block:: pascal
 
     procedure KeyDown(key: Word);
 
 KeyDown sends a request to the Operating System to "fake" an event that
-causes the ``key`` to be "down".
+causes the keyboard ``key`` to be "down".
 
+..
+    TODO: Example
+
+.. _scriptref-keyup:
 
 KeyUp
 ~~~~~
@@ -108,8 +169,10 @@ KeyUp
 KeyDown sends a request to the Operating System to "fake" an event that
 causes the ``key`` to be "up".
 
+..
+    TODO: Example
 
-.. _virtualkeys:
+.. _scriptref-virtualkeys:
 
 Keyboard Virtual Keys
 ---------------------