From 008196b04edfdc0e1ef91fd90da14dbdb3714987 Mon Sep 17 00:00:00 2001 From: Merlijn Wajer Date: Sun, 17 Jul 2011 19:36:21 +0200 Subject: [PATCH] Documentation: Initial libMML documentation. --- Doc/sphinx/index.rst | 1 + Doc/sphinx/libmml.rst | 11 +++++++ Doc/sphinx/libmml/intro.rst | 61 +++++++++++++++++++++++++++++++++++++ Doc/sphinx/pymml.rst | 1 - 4 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 Doc/sphinx/libmml.rst create mode 100644 Doc/sphinx/libmml/intro.rst diff --git a/Doc/sphinx/index.rst b/Doc/sphinx/index.rst index aec03f4..28e48ef 100644 --- a/Doc/sphinx/index.rst +++ b/Doc/sphinx/index.rst @@ -31,6 +31,7 @@ Contents: referencesimba.rst docdoc.rst todo.rst + libmml.rst pymml.rst diff --git a/Doc/sphinx/libmml.rst b/Doc/sphinx/libmml.rst new file mode 100644 index 0000000..607a244 --- /dev/null +++ b/Doc/sphinx/libmml.rst @@ -0,0 +1,11 @@ + +.. _lib-mml: + +libMML +========== + +.. toctree:: + :maxdepth: 2 + + libmml/intro.rst + diff --git a/Doc/sphinx/libmml/intro.rst b/Doc/sphinx/libmml/intro.rst new file mode 100644 index 0000000..fdd6020 --- /dev/null +++ b/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. + diff --git a/Doc/sphinx/pymml.rst b/Doc/sphinx/pymml.rst index 664ee22..63838f9 100644 --- a/Doc/sphinx/pymml.rst +++ b/Doc/sphinx/pymml.rst @@ -6,7 +6,6 @@ Python MML .. toctree:: :maxdepth: 2 - pymml/mml.rst pymml/mouse.rst pymml/color.rst