Documentation: Initial libMML documentation.

Doc/sphinx/index.rst

@@ -31,6 +31,7 @@ Contents:
     referencesimba.rst
     docdoc.rst
     todo.rst
+    libmml.rst
     pymml.rst
 
 

Doc/sphinx/libmml.rst

@@ -0,0 +1,11 @@
+
+.. _lib-mml:
+
+libMML
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+    libmml/intro.rst
+

Doc/sphinx/libmml/intro.rst

@@ -0,0 +1,61 @@
+libMML
+======
+
+libMML is short for the library to the Mufasa Macro Library.
+
+
+Why libMML?
+-----------
+
+One of the first questions that rise are probably *why* libMML and *what* is
+libMML exactly?
+
+libMML is a loadable C-like library that provides most of the MML functionality.
+For the ones that do not know, MML is the core component for Simba that does all
+the *computational* and *algorithmic* work. See :ref:`mml-ref` for more
+information.
+
+To summarize, the MML covers:
+
+    -   Targetting specific windows and getting the window information such as
+        their bitmaps and dimensions.
+    -   Controlling the mouse and keyboard.
+    -   Finding colours, bitmaps and dtms.
+    -   Text recognition (OCR)
+    -   Accessing files and sockets in an unified manner
+
+Hopefully the *what* part of the question has mainly been covered by now. If
+you're literate in computer science the *why* question has also been answered as
+soon as it was mentioned that is was a loadable library - which is also implied
+by its name. Exporting the MML into a loadable library allows virtually any
+program to load it and just use all the MML functionality.
+
+Design (issues)
+---------------
+
+libMML itself should not be too complex. It should simply translate the OOP MML
+to a non-OOP C-type library and convert datatypes when required (see below as to
+why). libMML is basically just a codebase that calls MML functions and passes
+the result along in a slightly different format. In simple cases such as
+MoveMouse the integers are simply passed; since there's do not differ, but in
+the case of arrays of any type we have to copy the arrays to a C format - at
+least until MML internally will no longer use Free Pascal (managed) arrays.
+
+As previously mentioned, libMML is a *C*-type library; this is mentioned
+explicitly because MML is written in Free Pascal (Object Pascal) which has quite
+a few different datatypes. Strings are typically not compatible, and arrays are
+managed in Pascal whereas they are not in C which makes it hard to just *pass*
+the array along. One of the problems we have to cope with when writing libMML is
+converting datatypes to C-compatible datatypes. C-compatible datatypes are
+supported by most programming languages and thus the best way to go when making
+a universal MML library.
+
+libMML use cases
+----------------
+
+Theoretically libMML can be loaded by any programming language; but typically
+each programming languages has it's own kind of programming practices and thus
+write - again - their own wrapper around libMML. This is what is being done with
+*pyMML*, the python libMML wrapper. It is still as much in development as libMML
+is, but the functionality exposed by libMML is succesfully used.
+

Doc/sphinx/pymml.rst

@@ -6,7 +6,6 @@ Python MML
 .. toctree::
     :maxdepth: 2
 
-    pymml/mml.rst
     pymml/mouse.rst
     pymml/color.rst