Move most of the README's and other docs into the new docs directory.

19 files changed, 1054 insertions, 0 deletions

diff --git a/docs/ClientHamr/README b/docs/ClientHamr/README
new file mode 100644
index 0000000..c82b1ba
--- /dev/null
+++ b/docs/ClientHamr/README
@@ -0,0 +1,7 @@
+Refer to - http://www.infinitegrid.org/drupal/content/ClientHamr
+
+ClientHamr is the concept that we can apply the unix philosophy to the
+viewer.  Use individual tools that are good at their job to split off
+bits of the big bad blob that is the viewer.  Using standard protocals
+and tools where we can.
+
diff --git a/docs/ClientHamr/README.BVJ b/docs/ClientHamr/README.BVJ
new file mode 100644
index 0000000..456154a
--- /dev/null
+++ b/docs/ClientHamr/README.BVJ
@@ -0,0 +1,7 @@
+Refer to - http://www.infinitegrid.org/drupal/content/BVJ
+
+BVJ is extensions to the BVH animation format used by SL technology. 
+It's in the ClientHamr section coz on the server side, they are just
+dealt with as blobs to be sent to the viewers.  This may change if we
+implement animating link sets, and interaction with the sim physics.
+
diff --git a/docs/ClientHamr/README.GuiLua b/docs/ClientHamr/README.GuiLua
new file mode 100644
index 0000000..f60d7b2
--- /dev/null
+++ b/docs/ClientHamr/README.GuiLua
@@ -0,0 +1,581 @@
+GuiLua is basically a redo of my ancient Java based matrix-RAD system,
+but using Lua and EFL.  Lua is entirely different from Java, and Lua
+doesn't run in web browsers, so this version has similar concepts, and
+similar names, it's not exactly the same.  It's more accurate to say
+this is in the spirit of matrix-RAD.
+
+The ultimate goal is for the various ClientHamr parts to be able to
+either host their own UI, or have it hosted in the in world 3D window. 
+Matrix-RAD's ability to run either server or client side, with no change
+to the code, is great for this sort of thing.  If I can manage the
+ability to "tear off" windows, in other words, pull them out of the 3D
+window to be real windows, then that's something people have been asking
+for from LL forever.
+
+Stdin/out might be good to use.  Extantz starts up "client" programs,
+with a "use stdin/out" argument, the clients pass skang commands (open
+this internal window with these widgets) to extantz through their
+stdout, extantz passes skang commands (these values where set by these
+widgets) back through their stdin.  With no "use stdin/out" argument,
+the programs host their own UI.  Perhaps extantz can just pass the UI
+skang stuff back to the client, which will mean "draw your own window",
+to support the "tear off" feature.  If I remember skang had suitable
+serialization stuff to support this.  Lua does anyway.  B-)
+
+Naturally, like matrix-RAD, all this UI stuff can happen across a socket
+as well as through stdin/out.  Should be transparent to the user proggy.
+
+I can redesign skang to be more Lua like, to take advantage of Lua's
+meta language capabilities.  Since no one used skang anyway, I can get
+away with this.  Also should add a Lua friendly wrapper around nails, so
+that addons for Extantz can be supplied entirely as Lua scripts.  In
+other words, LuaSL scripts.  On top of all that, should also allow
+access to the Edje Lua stuff I've already written, but drag it outside
+of an edje file.
+
+This pretty much means that GuiLua should be a shared library, coz in
+the ClientHamr use case, several programs are gonna be using it at once. 
+Should also be separate modules for development stuff like the skin
+editor, which could be just another proggy using GuiLua.
+
+Initially GuiLua can wrap elementary / evas, with the goal of wrapping
+NAWS, just like matrix-RAD was originally planned.  Then I can put off
+writing NAWS for another decade.  lol
+
+Might be nice to have a wrapper that is a web server that generates
+standard HTML forms.  No JavaScript, no HTML5, just plain old,
+compatible with everything, HTML forms.
+
+
+Design notes
+------------
+
+Edje Lua does not wrap elementary widgets, and is not likely to due to
+elementary being compiled after edje.  Smart objects and swallows
+probably can deal with that though, I'm not familiar enough with them to
+know.  Eo on the other hand allegedly offers introspection, which was
+always the corner stone of matrix-RAD.  So access to elementary widgets
+via Eo might be possible.  That's kinda the entire hook I'm hoping will
+help to make matrix-RAD style stuff work as well as it did there. 
+Apparently when they promised introspection with Eo, they meant compile
+time, not run time.
+
+Edje Lua is restricted to scripts in edje files, AND sandboxed to those
+edje files as well.  We want to step outside that sandbox, and run stand
+alone Lua scripts, as well as GuiLua / LuaSL scripts internal to
+extantz.  Some merging of LuaSL and Edje Lua, leaving room for GuiLua,
+would be great, but I might have to convince Raster.  Note that the
+socket idea wont work in sandboxed edje Lua scripts, unless the socket
+is in C code, that uses edje messages as the internal transport.
+
+Just so it's easier to find, I'll repeat a bit from the Enlightenment
+mailing list here, the result of discussions with raster and other
+interested parties -
+
+"First step is to write edje functions for generically bundling up one
+or more Lua tables into a message, sending that message, then unpacking
+it again. This will be able to be done from edje, from C, and from Lua
+directly. Perhaps adding that as one more edje messege type.  This is
+for sending Lua tables between threads.  A later addition will be to
+send them through the 'net, probably as eet.
+
+Host apps can register arbitrary functions with edje Lua, using a more
+generic version of the code I already wrote for letting edje register
+lua functions.  These host functions are by default not thread safe.
+Edje puts a wrapper function around the host app, and registers that
+wrapper function with Lua.  The wrapper function, when called from Lua,
+does this -
+
+ecore_thread_main_loop_begin();
+call the host app callback();
+ecore_thread_main_loop_end();
+
+The first alternative, which the host app must request, is for the
+wrapper function to use the table message functions to marshal the
+arguments, send it to the main thread, wait for the response (or do
+something else), then unmarshal the result before sending it back to
+Lua.
+
+The second alternative, which the host app must REALLY request, is for
+the host app to say "I'm REALLY going out of my way to be threadsafe,
+just call me direct".  No edje wrapper function, BUT the host app still
+has to use edje to register this function.
+
+The first two might be done this way -
+
+host_cb = edje_lua2_functions_add(...);
+edje_lua2_function_marshal_set(host_cb, function);
+
+The last one could be -
+
+host_cb = edje_lua2_threadsafe_function_add(...);
+
+Note the difference between _functions_ and _function_.  The first call
+registers an entire metatable full of functions, in the same way that
+edje does for it's functions.  These are the default sort of
+functions.  The second call references one of those previously
+registered functions, and makes it marshal arguments and results.  The
+third one registers a single function, but it could be added to an
+existing metatable registered by the first function."
+
+and -
+
+"We are actually half way there.  Anticipating that there would be way
+more edje and evas stuff to add to the edje Lua API in the future, I
+created generic wrapper functions to make that easier.  Implementing
+this would mean exposing those static functions, and writing more of
+these generic wrapper stuff.
+
+Lua already provides a mechanism for this sort of thing, but we
+currently sandbox that out.  We can provide a very limited version of
+the package module, that only lets the Lua script load modules that the
+host app explicitly provides.  This keeps edje Lua in it's strictly
+sandboxed state."
+
+Raster also wants to thread lots of edje, likely including having edje
+Lua scripts as threads, much like I'm doing with LuaSL already.  Plus
+LuaJIT SPEEEEED!!.  B-)
+
+
+Skang notes
+-----------
+
+So, what will this variation of skang look like?  For a start, the
+syntax will have to be more Lua like, so that's a real basic change. 
+Can't use a space as an argument separator, Lua allows only ',' and
+';'.  Strings can still use single or double quotes.
+
+The magic "_123" system I used before to specify "position / size in
+characters instead of pixels" just wont work in Lua.  Using _ as a table
+name with a meta table means that this syntax now becomes "_.123", which
+is kinda acceptable.  Note that _.123 is syntax sugar for _["123"], so
+I'm not sure if using a number there works.  An alternative is to just
+use a string -
+
+foo = widget.label(0, "1", 100, 0, 'Text goes here")
+
+Uses as many characters, and ends up being a value instead of an index,
+which is the right thing to do.  While on this subject, anything less
+than 1, but more than 0, can be used as a percentage, maybe combined
+with "character" mode (this is a new thing) -
+
+foo = widget.label(0, "0.1", 0.5, 0, 'Text goes here")
+
+This could even allow relative placement as mentioned in the skang TODO -
+
+foo = widget.label(0, "otherWidget+0.1", 0.5, 0, 'Text goes here")
+
+
+"widget" would be a table with functions for dealing with widgets.  It
+would include metatable stuff for widget set introspection.  So
+"widget.label" would introspect in our widget set for a widget type of
+"label", and return a widget type table.  So we could do -
+
+foo = widget.label(0, "0.1", 0.5, 0, 'Text goes here :")
+foo:colour(255, 255, 255, 0, 0, 100, 255, 0)
+foo:hide()
+foo:action("skang.load(some/skang/file.skang)")
+
+Also allow access via table elements -
+
+foo.action = "skang.load('some/skang/file.skang')"
+foo.colour.r = 123
+foo.look('some/edje/file/somewhere.edj')
+foo.help = 'This is a widget for labelling some foo.'
+
+We can use the concat operator (..) to append things to widgets, like
+adding choices in a drop down, rows in a grid, etc.
+
+Hmm, need a skang table as well -
+
+skang.module(Evas)
+skang.module(Elementary)
+skang.clear()
+skang.load('some/skang/file.skang')
+
+
+I don't think we need variable introspection as much, since in this case
+Lua is both the skang and the underlaying language, the variables can
+just be accessed directly.  Not sure on this, need to experiment.  This
+is what we normally need variable introspection for -
+
+foo = 'bar'     -- Using the metatable to override '=' to set the actual value of the widget, say the text of a label or edit widget.
+bar = foo       -- The reverse of the above.  Though perhaps these can't be done?
+foo = foo .. 'stuff' .. 'more stuff' .. 'another line of the dropdown or whatever'
+
+OK, first two can't be done, metatable only overides that for table elements.  The third one can only be (I might be wrong there) -
+
+foo.value = 'stuff' .. 'more stuff'
+foo.value = foo.value .. 'another line of the dropdown or whatever'
+
+Skang relied on the use of the set command to make sure that any
+matching widgets and variables got updated.  And the get command.
+
+foo:set('stuff')
+bar = foo:get()
+
+On the other hand, given the module / package stuff mentioned below, and
+some metatable magic, we could do -
+
+local other = require('otherPackageName')
+other.foo = 'stuff'
+bar = other.foo
+
+Sooo, how does that squeeze into a "skang" file?
+
+#!skang myApp.skang     -- This is Lua, so this might not work.
+-- There's an implied local this = require('myApp')
+-- There's an implied local skang = require('skang')
+local widget = require('EvasWidgets')
+local other = require('otherPackageName')
+skang.clear
+skang.window(200, 200, "G'day planet.")
+quitter = widget.button('Quit', 0.5, 0.5, 0.5, 0.5)
+quitter:action('quit')   -- 'quit' is looked up in ThingSpcae.commands, and translated into the Lua 'skang.quit()'.
+other.foo = 'stuff'
+this.bar = other.foo
+
+
+Original Skang infrastructure
+-----------------------------
+
+Skang starts with a Thing as the base.  In Java it's a base object for
+everything else, with a bunch of methods and elements.  We can probably
+use a Thing metatable and replicate most of it.  The widget used in the
+previous section is built on top of Thing.  Things are stored in
+ThingSpace, which is a BonsaiTree of LeafLike Things.  Java's version of
+multiple inheritance was used.  Commands are a Thing.
+
+ThingSpace is per users session.  classCache stores cached class
+lookukps, command stores commands, module stores loaded modules, param
+stores variables and their values, widget stores widgets and their value
+/ state.
+
+Skanglet is a generated mapping between actual methods / variables in a
+class, and skang.  Each method or variable that ends up in the skanglet
+was marked by special javadoc tags.  It also included some meta data
+like version and the default skang.  For variables it defined -
+
+"Name", "Field/Method()", "Required", "Shortcut", "Default", "Help text"
+
+... and for methods -
+
+"Name", "Method", "Syntax", "Help text"
+
+In both cases the "Name" was the skang name, it could be different from
+the Java name specified in the second field.  Likely we can do away with
+the need to generate these skanglet files, and just add stuff to the
+Thing.  Modules wrap Skanglets, and takes care of loading them into ThingSpace.
+
+Module are used for -
+    loading the Skanglet for the Thing currently running (match java class name to skang file name).
+    loading the AWT interface in skang files.
+    loading OTHER skanglet based Things
+    loading Squeal, StuffSkang, and Who from java when needed.
+
+So in Lua, we can use the package system.  First require(moduleName) to
+load up the skang module.  Require can return a table, the Lua package
+called ends with "return someTable".  See LuaLSL for an example.  This
+package is actually run, so it can figure out what to put in the
+returned table.  So for instance it could use inlined methods and such -
+
+local skang = require('skang')
+local result = {};
+result.author = 'onefang'
+result.version = '0.72 alpha 2004-11-19 16:28:00'
+local foo
+-- The first argument would be the name of a local variable / method.  Which could be accessed via _G?
+-- Not sure if we could use a global foo, AND use it directly.
+result.foo = skang.newParam('foo', "Required", "Shortcut", "Default", "Help text")
+result.func = skang.newCommand('arg1_type,arg2_type', 'Help Text', function (arg1, arg2)
+...
+end)
+return result;
+
+
+Stuff is the base class used to track database rows and other multi
+value things.  Would still need to deal with variable sub things, though
+that's likely just using tables.  SquealStuff is the database version,
+using Squeal as the database driver wrapper.  Squeal could wrap
+esskyuehl?
+
+
+The pre tokenized structure thingy I had planned in the TODO just wont
+work, as it uses symbols.  On the other hand, we will be using Lua
+tables anyway.  B-)
+
+
+NAWS
+----
+
+NAWS was always planned, but never actually written.  Though some stuff
+was kinda prototyped, especially UberMatrix stuff.  I think this time
+around, NAWS should be written in C, based on pure Evas + Edje.  Perhaps
+with direct support for introspection?  After EO settles down, I might
+use that to.
+
+
+Edje_Lua notes
+--------------
+
+Edje_Lua is sandboxed firmly inside of edje files.  This makes it
+unsuitable for our use, as we want to step outside that sandbox. 
+However, we still want to wrap Lua around EFL stuff, preferably using
+the same API.  Raster fought against using this new eolian stuff to
+generate edje_lua2.c, and seems to be against having a "no sandbox" flag
+in edje_lua2.c.  For now I'll let q66 go ahead with his Edje Lua via
+LuaJIT FFI conversion that uses a variation of eolian written in Lua. 
+Seems like much more work than my way of doing it.  shrugs
+
+Unfortunately, this might not be ready soon enough for me, AND it might
+not even be suitable.  While I agree that LuaJIT FFI stuff might be a
+good idea, if I read the docs correctly FFI simply wraps around C
+headers and libraries directly, making it less suitable for sandboxes
+and other environments where you want to wrap those library functions
+differently.
+
+So, I might have to go ahead with my own plan anyway.  On the other
+hand, for skang, I want to wrap things a bit differently.  Might be best
+to do that wrapping C side.  In other words, the skang and widget Lua
+packages get written in C, and are different from edje_lua2.c.
+
+On the gripping hand, there might be use in including edje_lua2.c style
+bindings in GuiLua as an edje package, evas package, elementary package,
+etc.  This could be done by going ahead with my plans to modify
+edje_lua2.c to include the "no sandbox" flag, then compile it with that
+flag turned on to produce a standard Lua package.  Then get eolian to
+produce evas_lua.c, elementary_lua.c, etc.
+
+Another idea worth investigating is to rewrite edje_lua2.c to use
+introspection directly to figure out it's "combined set and get" style
+bindings.
+
+
+Introspected EFL notes
+----------------------
+
+See below for the basic EO notes, where I come to the conclusion that
+the other EFL devs wont be adding introspection to EO themselves.  It's
+all too hard they say.  Pffft
+
+So, I might have to do this myself, call it "entro"....
+
+Write a patch against eolian that outputs introspection data.  That data
+is C code for a hash of EO class names.  Each hash points to a data
+structure that includes a hash of method names for that class, and a
+pointer to the class description.  Each of those hashes points to a data
+structure that includes an array of argument types and names.  The
+method ID should be in that structure to, and maybe even the doc text. 
+Might even include an Eo internal data structure that links Op IDs to
+that method structure (I dunno what they call that).  The final output
+is a library of that C code, that includes functions for doing the
+actual introspection.
+
+See?  Not to hard at all, all described in a paragraph. lol
+
+One function we could include is a way to "compile" eo_do arguments. 
+That would be an array (va_list actually) of method ID's followed by the
+arguments for that method.  Some of those arguments might be pointers to
+memory structures, so this is not suitable for storing on disk. 
+Instead, it could be used for "compiling" commonly used code or hot
+paths to get the introspection overhead out of the way early.  Could
+also compile parameterized versions, with numbered place holders that
+get filled in later.  Certainly we need a Lua interface to eo_do of some
+sort.
+
+In the same way that Java skang cached the results of introspection in
+ThingSpace.CLASS, we could use cache introspection lookups to speed
+things up.  Not a great saving, one hash lookup versus two.  Caching the
+"class.method" string that points to the method structure for any method
+we have used already.
+
+NAWS could use the compile function to create eo_do commands needed to
+create each of it's widget types, and the window.  Yes, I know, NAWS
+only has two "widget types".  B-)
+
+
+For quick and dirty early testing, I'll probably write a widget package
+that has hard coded mappings between some basic "label", "button", etc.
+and ordinary elementary widgets.  Proper introspection can come later.
+
+
+LuaJIT FFI notes
+----------------
+
+LuaJIT 2.0 FFI needs to have cleaned up versions of C header files
+included in the Lua scripts that use it.  This is messy.  Version 2.1
+(or perhaps 3.0) has on it's road map to include a C pre processor,
+which should help that problem.
+
+
+EO notes
+--------
+
+tl;dr - eo introspection doesn't actually exist, even though it was
+"promised" years ago, but looks trivial to add.  On the other hand, the
+other EFL devs seem to be fighting against it, so I might need to write
+my own.  sigh
+
+object = eo_add(EVAS_OBJ_LINE_CLASS, canvas);
+    evas_line.eo.h      -> #define EVAS_OBJ_LINE_CLASS evas_obj_line_class_get()
+                        -> const Eo_Class *evas_obj_line_class_get(void) EINA_CONST;
+    evas_line.eo.c      -> EO_DEFINE_CLASS(evas_obj_line_class_get, &_evas_line_class_desc, EVAS_OBJ_CLASS, NULL);
+    Eo.h                -> EO_DEFINE_CLASS is a macro that basically wraps eo_class_new(), and returns it's result.
+
+So Eo_Class is the type of a class, but it's A) opaque, B) deprecated! 
+It includes a pointor to the Eo_Class_Description, which includes the
+actual name.  I'm not seeing anywhere the names of the get/set
+paramaters being passed into the system, or any way to look up a class
+based on name.  Not even a way to get to the public Eo_Class_Description
+from the opaque Eo_Class.
+
+Eo_Class_Description is at least public.  It includes
+Eo_Op_Description's and Eo_Event_Description's.  Eo_Op_ and Eo_Event_
+include the name and documentation of the op / event.  The macro used to
+generate Eo_Op_ does NOT pass the name, just the ID number as a string. 
+There is also Eo_Op_Func_Description, which does not include a name, it
+seems to be generated in the constructor.  The same Eo_Op_ ID number is
+used to index it.  Seems to be no direct link between Eo_Class and
+Eo_Op_func_, just the same Eo_Op_ ID numbers used internally somehow.
+
+eo_do(obj, evas_obj_line_xy_set(200, 200, 300, 300));
+    evas_line.eo.h      -> #define evas_obj_line_xy_set(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), EO_TYPECHECK(Evas_Coord , x1), EO_TYPECHECK(Evas_Coord , y1), EO_TYPECHECK(Evas_Coord , x2), EO_TYPECHECK(Evas_Coord , y2)
+                           #define EVAS_OBJ_LINE_ID(sub_id) (EVAS_OBJ_LINE_BASE_ID + sub_id)
+                           extern EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID;
+
+                           enum
+                           {
+                              EVAS_OBJ_LINE_SUB_ID_XY_SET,
+                              EVAS_OBJ_LINE_SUB_ID_XY_GET,
+                              EVAS_OBJ_LINE_SUB_ID_LAST
+                           };
+    evas_line.eo.c      -> EAPI Eo_Op EVAS_OBJ_LINE_BASE_ID = EO_NOOP;
+                            static void _gen_evas_line_class_constructor(Eo_Class *klass)
+                            {
+                               const Eo_Op_Func_Description func_desc[] = {
+                                    EO_OP_FUNC(EO_BASE_ID(EO_BASE_SUB_ID_CONSTRUCTOR), _eo_obj_evas_line_constructor),
+                                    EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_SET), _eo_obj_evas_line_xy_set),
+                                    EO_OP_FUNC(EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), _eo_obj_evas_line_xy_get),
+                                    EO_OP_FUNC_SENTINEL
+                               };
+                               eo_class_funcs_set(klass, func_desc);
+                            }
+
+                            static void
+                            _eo_obj_evas_line_xy_set(Eo *obj, void *_pd, va_list *list)
+                            {
+                               Evas_Coord x1 = va_arg(*list, Evas_Coord);
+                               Evas_Coord y1 = va_arg(*list, Evas_Coord);
+                               Evas_Coord x2 = va_arg(*list, Evas_Coord);
+                               Evas_Coord y2 = va_arg(*list, Evas_Coord);
+                               _evas_line_xy_set(obj, _pd, x1, y1, x2, y2);
+                            }
+
+                            void _evas_line_xy_set(Eo *obj, Evas_Line_Data *pd, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
+
+    evas_object_line.c  -> EOLIAN static void _evas_line_xy_set(Eo *eo_obj, Evas_Line_Data *_pd, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2)
+
+
+Evas_Object_Line *o = eo_data_scope_get(obj, EVAS_OBJ_LINE_CLASS);
+Evas_Object_Line *o = eo_data_ref(obj, EVAS_OBJ_LINE_CLASS);
+
+
+.. evas_line.eo
+
+class Evas_Line (Evas_Object)
+{
+   legacy_prefix: evas_object_line;
+   eo_prefix: evas_obj_line;
+   properties {
+      xy {
+         set {
+            /*@
+            @since 1.8
+
+            Sets the coordinates of the end points of the given evas line object. */
+         }
+         get {
+            /*@
+            Retrieves the coordinates of the end points of the given evas line object.
+            second end point. */
+         }
+         values {
+            Evas_Coord x1; /*@ The X coordinate of the first point. */
+            Evas_Coord y1; /*@ The Y coordinate of the first point. */
+            Evas_Coord x2; /*@ The X coordinate of the second point. */
+            Evas_Coord y2; /*@ The Y coordinate of the second point. */
+         }
+      }
+   }
+   implements {
+      Eo_Base::constructor;
+   }
+
+}
+
+... evas_line.eo.c
+
+EAPI void
+evas_object_line_xy_set(Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2)
+{
+   eo_do((Eo *) obj, evas_obj_line_xy_set(x1, y1, x2, y2));
+   return ;
+}
+
+
+static const Eo_Class_Description _evas_line_class_desc = {
+     EO_VERSION,
+     "Evas_Line",
+     EO_CLASS_TYPE_REGULAR,
+     EO_CLASS_DESCRIPTION_OPS(&EVAS_OBJ_LINE_BASE_ID, _evas_line_op_desc, EVAS_OBJ_LINE_SUB_ID_LAST),
+     _evas_line_event_desc,
+     sizeof(Evas_Line_Data),
+     _gen_evas_line_class_constructor,
+     NULL
+};
+
+
+skang vs edje vs LL shit
+------------------------
+
+EDJE
+Verbose, complex.
+Used to place and decorate widget parts.
+Can be used to place entire widgets through externals and swallows.
+Basic parts relative to each other.
+Signals and messages.
+Embryo scripts.
+Lua scripts (sandboxed).
+
+
+SKANG
+Tight, simple.
+Used to place widgets, and describe actions.
+Can include some really basic scripting.
+Widgets in a fixed position, but included stuff for relative placement in the TODO.
+Automated associations between widget name and variable (and method?) via introspection.
+Actions.
+Looks (could easily be extended to edje groups).
+Extensible.
+Can be used to pass values around.
+
+
+LL SHIT
+Verbose, even worse, XML, more crap than is needed.
+Menus.
+Windows with widgets relative to each other.
+    Basically nested rectangles.
+Manual association of widgets to methods.
+Can include tool tip string, enabled, visible, hover cursor, bounding rectangle?, mouse opaque?, tab groups, font (name, size, style, and alignment).
+    More stuff, typically hidden in the OO somewhere.  sigh
+Generally uses fixed image and colour names, which skins overide.
+Skins can also overide the XML files.
+Translations provide override XML files that need only override the text bits.
+
+
+old notes
+---------
+
+See if it's possible to disable the Emerald/Phoenix/Firestorm LSL bridge
+when connecting to OpenSim.  Actually, they finally came to their senses
+and support OpenSim now, so that should be sorted already.
diff --git a/docs/ClientHamr/README.IAE b/docs/ClientHamr/README.IAE
new file mode 100644
index 0000000..8c0e46c
--- /dev/null
+++ b/docs/ClientHamr/README.IAE
@@ -0,0 +1,3 @@
+Refer to - http://www.infinitegrid.org/drupal/content/InworldAnimationEditor
+
+IAE is an idea to put an animation editor in world, much like the link set editor.
diff --git a/docs/ClientHamr/README.XMPP b/docs/ClientHamr/README.XMPP
new file mode 100644
index 0000000..53058b2
--- /dev/null
+++ b/docs/ClientHamr/README.XMPP
@@ -0,0 +1,4 @@
+Viewer integration with XMPP, and using it for as many services as it can.
+
+XMPP / jabber is a good protocol to base presence, IM, groups, and other
+related stuff on.  We should do so.
diff --git a/docs/ClientHamr/README.bGod b/docs/ClientHamr/README.bGod
new file mode 100644
index 0000000..ec48d61
--- /dev/null
+++ b/docs/ClientHamr/README.bGod
@@ -0,0 +1,5 @@
+A front end to grid admin tools, though generally OS/SL specific tools.
+
+The name is a reference to SL's god mode, and the Men at Work song "Be
+Good Johnny", which itself is a reference to Chuck Berry's "Johnny B.
+Goode".
diff --git a/docs/ClientHamr/README.extantz b/docs/ClientHamr/README.extantz
new file mode 100644
index 0000000..5fb1d5f
--- /dev/null
+++ b/docs/ClientHamr/README.extantz
@@ -0,0 +1,24 @@
+Extantz is the main virtual world front end.  Also, during this
+experimental phase of development, this will be a test bed for all the
+GUI stuff.  Eventually lots of it will be split off to separate
+programs.
+
+Extantz is a made up word.  The challenge was to find a word beginning
+with E, is as traditional with EFL (Enlightenment Foundation Library)
+projects, that has not been done to death, and thus has some reasonable
+chance to turn up in google searches.  It also helps if it somehow or
+other reflects what the project actually is.  lol
+
+Extant means "still existing, surviving", or the more archaic meaning,
+from it's original Latin roots "standing out, be visible, exist".
+
+Extent means "an area or volume, the range over which a thing extends"
+among other things.
+
+So I hope to invoke thoughts of a volume that exists and stands out.  In
+other words, virtual worlds.  Meh, I'm not that artsy, it needed a name. 
+lol
+
+Extantz will handle all the 3D rendering.  The other parts can use nails
+to control the world that is rendered, and GuiLua to present their UI
+on top of the rendered world.
diff --git a/docs/ClientHamr/README.libpurple b/docs/ClientHamr/README.libpurple
new file mode 100644
index 0000000..4e14b9b
--- /dev/null
+++ b/docs/ClientHamr/README.libpurple
@@ -0,0 +1,4 @@
+Viewer integration with libpurple, using it for generic IM services.
+
+Libpurple is a modular IM system, we could just add a libpurple based IM
+system to the viewer, and use that for the XMPP integration.
diff --git a/docs/ClientHamr/README.mumble b/docs/ClientHamr/README.mumble
new file mode 100644
index 0000000..1010f18
--- /dev/null
+++ b/docs/ClientHamr/README.mumble
@@ -0,0 +1,5 @@
+Viewer integration with mumble and whisper, and using it for as many
+audio services as it can.
+
+Mumble is a voice system designed for networked 3D game usage.  Sounds
+perfect, just what we need.  B-)
diff --git a/docs/ClientHamr/README.woMan b/docs/ClientHamr/README.woMan
new file mode 100644
index 0000000..1b3bbe0
--- /dev/null
+++ b/docs/ClientHamr/README.woMan
@@ -0,0 +1,148 @@
+WoMan is a virtual world account and viewer manager, mostly of the SL
+(Second Life) variety since that's my focus.  Most SL style virtual
+world viewers can be invoked with options to start them logging on, and
+skipping the login screen.  So this project aims to be that login
+screen, doing all the things that can be done from the meta-impy login
+screen, plus more.  Once the user hits the login button, woMan figures
+out what parameters to pass to what viewer, then starts it up and gets
+out of the way.  Following the ClientHamr philosophy of breaking the
+viewer up into modules that do simpler tasks, and do them well.  So that
+means that meta-impy will eventually loose it's login screen, to be
+replaced by woMan.
+
+WoMan starts off looking like any other viewers login screen, showing
+the login page of the default, or last visited grid, a small menu at the
+top with the usual functions, and the usual login buttons at the bottom. 
+Added to that will be a better grid manager, with proper user
+management, suitable for people with more than one account per grid. 
+The user will have the ability to choose a virtual world viewer to be
+the default, and even to associate a particular viewer with a particular
+grid.  This is useful, for instance, for grids that have their own
+custom viewers, but the user wants to use a more generic viewer for all
+the other grids.  Or if the user wants to use one viewer for OpenSim
+grids, but another for LL (Linden Labs) grids.  Coz perhaps their chosen
+viewer is not TPVP (Third Party Viewer Policy, an LL thing) compliant,
+and LL are just more anal than the rest of the universe.
+
+NOTE: since I started this, LL in their *cough* infinite wisdom *cough*,
+decided that support of OpenSIm was a Really Bad Thing, so their viewers
+are no longer capable of dealing with other grids.  LL have even gone as
+far as try to get other viewers to not support other grids.  As far as
+woMan is concerned, this just means that LL viewers, and viewers that
+drank the LL koolaid, are less functional.  shrugs
+
+The grid manager will also include some sort of search capability, as is
+currently being discussed by various people in the OpenSim universe. 
+There might even be several search systems in place, so supporting
+existing ones, and the ability to add more might be useful.  WoMan
+should be the only thing registered to handle hop:// and other such URLs
+in whatever web browsers you are using.  Though most viewers want to
+register themselves, so tends to be that which ever one you started up
+last, or first, gets that privilege.  That's a whole can of worms, sane
+policy and code should help.
+
+It might be useful to have woMan be able to download viewers,
+including checking for updates and offering to download them.  As well
+as updates to common things like viewer tag definition files.
+
+WoMan, unlike the LL viewer code base, will be designed for relogging. 
+Once the viewer it starts quits (or crashes), WoMan, which was still
+running, can pop again and let the user relog, or log to some other
+grid, or same grid as different a user, or even same grid as same user
+with a different viewer.
+
+Viewers can be made woMan aware, like meta-impy will be (since it's
+handing it's login screen functionality to woMan).  A few more things
+make sense to be added in this case.  For instance, you might want to
+have some or all of your LMs (LandMarks) be usable at the log in
+screen, so you can log directly to them.  The user might want the choice
+when they HG (HyperGrid teleport) to actually start up a new viewer and
+just login to the other grid instead (if they already have an account
+there).  While HGed to some new grid, the user might want to add that
+grid to the woMan grid manager at a simple click of a button, perhaps
+complete with an LM for their current position.  The grid searching
+capabilities mentioned earlier might be needed while in world. 
+Certainly the grid manager functions in meta-impy will be handled by
+woMan, even if in world.
+
+In order to display the login page of a grid, which is a web page, a web
+browser will be built into woMan.  It could be used to display web
+pages within an woMan aware viewer.  Though perhaps not for MOAP
+(Media On A Prim), unless woMan grows the ability to incorporate
+itself into the viewers 3D landscape as part of a prim.  Which is a good
+idea, then meta-impy no longer needs a web browser.  Though other things
+in the viewer are implemented as web pages, and LL are moving more stuff
+to the web.
+
+One of the things on the login screen is the menu option to start up the
+preferences window and change the viewers preferences.  Viewers use XML
+files that not only store the preferences, but also a description of
+them.  The preferences window and it's various parts are also stored as
+XML files.  There is a bit missing that is in the viewer source code
+that ties all of this together.  So it might not be possible to do this
+for all viewers.  WoMan aware viewers can naturally provide the
+missing bits to woMan, even if not running, or even pass that entire
+functionality to woMan, just like meta-impy will do.
+
+For the purposes of keeping resource usage low, it should be possible
+for the user to configure woMan to go away when it starts a viewer. 
+Might be a good idea even for woMan aware viewers, that can start it
+up again if it's functionality is needed while in world.  Note this "go
+away" means to stop running and free up any resources it was using;
+which is different from the "gets out of the way" it usually does, still
+running, just not on screen.
+
+
+The problem with the web.
+-------------------------
+
+At least that's the theory.  In practice, a web browser takes up almost
+one third of the viewer, and is only used for three things.  Login
+pages, simple built in browser window, and MOAP (Media On A Prim).  For
+the first two full blown web browsers are massive overkill.  MOAP is not
+supported by meta-impy yet anyway.
+
+WebKit is a pain to compile at the moment, for reasons I wont go into
+right now.  At the opposite of the spectrum is dillo, which is not quite
+up to spec enough for login pages that have fancy stuff.  There does not
+appear to be any middle ground.  So right now, I'll work on using random
+web browsers as external windows.  That will suffice for everything but
+MOAP, which I can leave until later.  Just discovered netsurf, a little
+smaller than dillo, but perhaps better featured?  Might be useful.
+
+The web is a bloated mess, so it's not surprising that a fully featured
+web browser component like WebKit is also a bloated mess.
+
+
+Design.
+-------
+
+A thin window on the left.
+
+Menus across the top.
+View tabs.
+    Grids  Accounts  Viewers  Landmarks
+
+Grids tab is the grid manager, though you can also drill down / tree out
+the accounts list per grid.
+
+Accounts shows accounts, though can drill down to grid list per account. 
+Also consider launching thin viewers, text only ones and such.  The
+account view is almost a natural for extending into a IM style thingy.
+
+Viewers lists the installed viewers, can install more, and allows
+preferences editing.  It can handle viewer installs, upgrades, even
+compiling them from source.
+
+Landmarks manages LMs from viewers, or log in spots, or SLURLs etc.
+
+A user configurable web browser can open up to fill the right of the
+screen.
+
+Log file management features, including viewer stdout, check if only
+Linux viewers do that.  Including chat logs.
+
+Dillo and uzbl can insert themselves into the windows of others.  Should
+check that out.  Netsurf is allegedly easy to port to things, might be
+able to port it to EFL.
+
diff --git a/docs/ClientHamr/WindowSharing.txt b/docs/ClientHamr/WindowSharing.txt
new file mode 100644
index 0000000..1ccd3bb
--- /dev/null
+++ b/docs/ClientHamr/WindowSharing.txt
@@ -0,0 +1,84 @@
+EnLichtIrrnment.  B-)
+
+Elementary and Irrlicht don't like to share windows.
+
+Irrlicht can be told to create a device from a pre existing window, but this is Windows only.
+    Perhaps it already works for Linux, just the docs are out of date?
+    It works, sorta.
+
+IVideoDriver::getExposedVideoData() can provide a structure with raw OS level window pointers.
+    This implies that it's theoretically possible to create a device from things other than Windows windows.
+    Wont provide any valid info when using the software renderer.
+
+Elementary can provide an Ecore_Wl_Window or an Ecore_X_Window of one of it's windows.  elm_win_wl_window_get() and elm_win_xwindow_get().
+
+Ecore_evas can provide an Ecore_Window with ecore_evas_window_get().
+
+Ecore_X_Window ecore_x_window_new()
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=2&t=31350&sid=0eb6d64c84ec7043fd48103f8e63e930 may help.  A little.
+
+
+"For using OpenGL with an Evas canvas, there is two possibilities in my
+opinion. Either put the canvas in a texture and give it to the 3D
+engine, or use EvasGL API and make the 3D engine integrate inside
+Evas. It is possible to have a direct rendering path with EvasGL and
+so have a fastest possible path.
+--
+Cedric BAIL"
+
+
+Apparently Irrlicht's method of providing an external window actually works.  Mostly. -
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=7&t=32647
+http://sourceforge.net/tracker/index.php?func=detail&aid=2655876&group_id=74339&atid=540676
+
+Though seems that bug was marked as a duplicate with the duplicate having a better patch, but NO FUCKING LINK to that duplicate.  What a horrid bug tracker.
+
+
+There is also this which gives clues -http://irrlicht.sourceforge.net/forum/viewtopic.php?f=9&t=26506
+
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=2&t=39872
+http://irrlicht.sourceforge.net/forum//viewtopic.php?t=39719
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=9&t=35197
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=2&t=46087
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=9&t=42450
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=9&t=35251
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=5&t=15338
+http://irrlicht.sourceforge.net/forum//viewtopic.php?f=7&t=12697
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=5&t=44599
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=5&t=18941 I think is ancient and might just be similar to what's in there already.
+
+---------------------------------------------------------
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=26141
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=33845
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=35984
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=34527
+
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=38656 may be of some interest.
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=30943
+http://irrlicht.sourceforge.net/forum/viewtopic.php?f=4&t=46983 where the question I want is not answered.
+
+---------------------------------------------------------
+
+I could run sed over COpenGLDriver.cpp to turn it into CEvasGLDriver.cpp, then tweak it a bit.
+
+evas_gl_make_current(gld->evasgl, gld->sfc, gld->ctx);
+glFoo() -> glapi->glFoo()
+
+
+Hmm, there will be some source files with random gl() calls, and I'd
+need to tweak a few other things to suit.  So this wont be a clean "just
+drop in this source file" patch.  B-(
+
+Probably a lot easier to just figure out what what brand of glue to use
+to get Irrlicht using Evas created GL surface and context.
diff --git a/docs/README.Bookie b/docs/README.Bookie
new file mode 100644
index 0000000..1a49f27
--- /dev/null
+++ b/docs/README.Bookie
@@ -0,0 +1,33 @@
+Shared dynamic libraries is a bit of an issue for cross platform code. 
+LL viewers deal with it by including their own copies of the libraries
+they use.  This bypasses the idea of sharing them, and thus uses too
+much resources.  On the other hand, it seems to be the Windows way of
+doing things, lots of Windows packages I have seen include their own
+copies of libraries.  Mac Os X seems to do the same, each application is
+installed as it's own directory, filled with it's own copies of
+libraries.  Not a lot of sharing going on.  Linux and the BSDs do the
+right thing, most libraries are actually shared.  Except that LL viewers
+STILL bring their own libraries.
+
+I think the main difference is having a proper package management
+system.  Apt, RPM, and portage (I think) can track dependencies on
+libraries, install the libraries automatically, and even have different
+versions of libraries installed side by side.  Without this, the OS has
+no official way of tracking library dependencies, so every one has to
+supply their own.  Sure Mac OS X has had a few package systems ported to
+it, but none of them are the official one, so developers can't rely on
+them.
+
+SledjHamr has to deal with this, and try to do so in some sort of smart
+way.  As usual, the right way to do things is generally to do the
+opposite of what LL does.  lol
+
+Bookie should be a sub system that probes the OS, trying to see if
+there's some sort of OS store of libraries, and try to find reasonable
+versions of the libraries needed in that.  If not found, it could invoke
+an OS specific method of installing a suitable library.  If that fails,
+it can download a SledjHamr specific version into the SledjHamr
+installed directory.  So it tries to do the right thing first, and
+gradually fallsback to doing the wrong thing like LL does.
+
+That's the theory, in practice, gonna be a pain.
diff --git a/docs/README.HamrSpace b/docs/README.HamrSpace
new file mode 100644
index 0000000..a2e19cf
--- /dev/null
+++ b/docs/README.HamrSpace
@@ -0,0 +1 @@
+Inventory server.
diff --git a/docs/README.Lspace b/docs/README.Lspace
new file mode 100644
index 0000000..a86de96
--- /dev/null
+++ b/docs/README.Lspace
@@ -0,0 +1 @@
+Sim contents server, which is pretty much a web server.
diff --git a/docs/README.LuaSL b/docs/README.LuaSL
new file mode 100644
index 0000000..1444948
--- /dev/null
+++ b/docs/README.LuaSL
@@ -0,0 +1,100 @@
+Refer to - http://www.infinitegrid.org/drupal/content/LuaSL_New_scripting_engine
+
+LuaSL is a Lua based LSL scripting engine that will aim for LSL
+compatability first, then adding Lua extensions.  It aims to replace the
+woeful XEngine from OpenSim, and at a later stage, be the basis for a
+client side scripting engine.
+
+To compile this, you will need Enlightenment Foundation Libraries (EFL)
+installed in either /opt/e17 or /usr.  These are typical places it get's
+installed in.  You will also need flex.  The rest of the dependencies
+are in the ../libraries directory.
+
+
+Design.
+-------
+
+The basic design will be made up as I go along, but so far I have this -
+
+A parser parses an LSL script, validating it and reporting errors.
+
+A translator takes the result of the parse, and converts it into Lua
+source.  Each LSL script becomes a Lua state.  LSL states are handled as
+Lua tables, with each LSL state function being a table function in a
+common metatable.  LL and OS functions are likely to be C or Lua
+functions.  Careful testing should be done with LuaJIT FFI, sandboxing,
+and performance testing.
+
+The Lua source is compiled by the Lua compiler.
+
+LuaJIT is used as the Lua compiler, library, and runtime.
+
+Luaproc is used to start up operating system threads and hand Lua states
+between them.  Luaproc messaging is also being used, but might need to
+change to edje messaging.  Note - luaproc has been extensively rewritten
+for this project, mostly converting it to use EFL.  That rewrite
+substantially shrunk the source code.  More might be rewritten in
+future.
+
+THIS IS WHERE WE ARE RIGHT NOW.
+
+Nails will be used to pump commands in and out of the LuaSL system. 
+Incoming commands invoke LSL events via the LuaSL state metatable.  LL
+and OS functions that impact the world will be converted to nails
+commands sent to the command pump.
+
+Initialy, since this is the first thing being written, a nails command
+pump client needs to be installed into OpenSim's C# stuff.  Though it
+might be possible to talk directly to ROBUST instead.  Think I'll try
+the ROBUST route, see how far I can get.  That's the general principle
+applying in all of this - try to avoid C# and see how for we can get. 
+lol
+
+On the other hand, might be better to leverage the existing C#
+implementations of LSL functions, just to get things up and running
+quickly.  To that end, a protocol involving exchanging snippets of Lua
+over a network socket has been developed, and the next step is to write
+the C# side.  sigh
+
+A watchdog thread should be used to make sure no LuaSL script spends
+forever processing any event.
+
+Some form of serialization will need to be created for saving script
+state during shutdowns, passing script state to other threads /
+processes / computers.  Aparently Lua is good at this.
+
+There will have to be a MySQL (and maybe SQLite) client in the system,
+so we can talk directly to the local sim database.  Esskyuehl may be
+suitable, though it's still in the prototype stage.
+
+Email, HTTP, and XML-RPC might need to be dealt with by us.  A ROBUST
+client will be needed to.  Azy might be suitable, but it's also in
+prototype.
+
+An object is a file system directory, full of LSL scripts as text files,
+notecards as text files, animations as BVH (or later BVJ) files, etc. 
+There will be some sort of metadata in place.  This could be created by
+our own OpenSim compatible cache module.
+
+
+Test harness.
+-------------
+
+I'll build a test harness.  It will be based on EFL Edje Lua, with
+buttons for triggering LSL events, SL style dialogs, and other goodies.
+
+The initial goal will be to run standard MLP scripts.  They have minimal
+interface to the world, and exercise quite a bit of the rest of LSL. 
+They are also quite common, and sometimes responsible for a lot of the
+script running load.
+
+Later I should add stock standard OpenCollar scripts from SL.  They are
+a bitch to get working under OpenSim, so would be good compatability
+tests.
+
+Various eina logging domains might be used to handle whisper, say, shout,
+etc.
+
+Performance testing will have to be done on 5000 scripts, to see how
+that compares against XEngine.
+
diff --git a/docs/README.REST b/docs/README.REST
new file mode 100644
index 0000000..2981827
--- /dev/null
+++ b/docs/README.REST
@@ -0,0 +1,2 @@
+REST is probaly good to apply to the web server part.  Alice wants JSON
+to, but see nails.
diff --git a/docs/README.WTF b/docs/README.WTF
new file mode 100644
index 0000000..67e55c7
--- /dev/null
+++ b/docs/README.WTF
@@ -0,0 +1,5 @@
+Refer to - http://www.infinitegrid.org/drupal/content/OMG_WTF_BBQ
+
+This is where we deal with systems to keep track of where in the web
+assets are, and to cache them.
+
diff --git a/docs/README.libraries b/docs/README.libraries
new file mode 100644
index 0000000..a26fda1
--- /dev/null
+++ b/docs/README.libraries
@@ -0,0 +1,31 @@
+There are some base libraries that should be used in common.  Notable
+the Enlightenment Foundation Libraries (EFL), Irrlicht, lemon, LuaJIT,
+and luaproc.  Other external open source projects that we just use
+directly should go here to.  Makes it easy to compile it all.
+
+Note that in some cases, there might be changes.  Such changes should be
+documented, and marked with "// onefang changes".
+
+EFL has been released, so not including that anymore.  You can find it
+in distro repos, PPA's, etc.  Or http://enlightenment.org/
+
+Irrlicht has been slightly modified to get it to use externally created
+GL stuff, and not use their internal copies of bzip, jpeglib, libpng,
+and zlib.
+
+Lemon is from http://www.hwaci.com/sw/lemon/.
+
+LuaJIT 2.0 has been released for Ubuntu 13.04 and later, try using
+https://launchpad.net/~mwild1/+archive/ppa for 12.04.  Not including
+that anymore.
+
+luaproc has been hacked up a bit, and will continue to be hacked up. 
+Merged it into LuaSL, so it's no longer here.
+
+--------------------------------------------------------------------
+
+These are the libraries written for the SledjHamr project.
+
+LumbrJack is a library of logging stuff, coz every one wants to log.
+
+Runnr is for running Lua scripts.  Named (sorta) after a friend of mine.
diff --git a/docs/README.nails b/docs/README.nails
new file mode 100644
index 0000000..7db2662
--- /dev/null
+++ b/docs/README.nails
@@ -0,0 +1,9 @@
+Refer to - http://www.infinitegrid.org/drupal/content/Nails
+
+Nails bangs it all together, mostly via the command pump.
+
+
+Not sure where else to put this, but nails I think is the bit that
+drives the network traffic the most -
+
+http://gettys.wordpress.com/2013/07/10/low-latency-requires-smart-queuing-traditional-aqm-is-not-enough/