improvements for the getting started tutorial based on iz's feedback.

docs/source/features.rst

@@ -89,7 +89,7 @@ Explanations for a few categories are below (rest are self-explanatory).
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+
 | tables                    |      ~      |     ~      |     ✔    |    ✔    |     ✔    |     ✔     |     ~     |        ✔       |     ✔    |     ✗    |     ✗     |        ~        |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+
-| table chaining            |      ~      |     ~      |     ✔    |    ✔    |     ✔    |     ✔     |     ✗     |        ✔       |     ✔    |     ✗    |     ✗     |        ~        |
+| table chaining            |      ~      |     ~      |     ~    |    ✔    |     ✔    |     ✔     |     ✗     |        ✔       |     ✔    |     ✗    |     ✗     |        ~        |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+
 | arbitrary keys            |      ~      |     ✔      |     ✔    |    ✔    |     ✔    |     ✔     |     ✗     |        ~       |     ✔    |     ✗    |     ✗     |        ✗        |
 +---------------------------+-------------+------------+----------+---------+----------+-----------+-----------+----------------+----------+----------+-----------+-----------------+
@@ -145,6 +145,7 @@ Plain C -
 kaguya -
 
 * Probably the closest in implementation details and interface to Sol itself
+* member variables are automatically turned into ``obj:x( value )`` to set and ``obj:x()`` to get
 * Inspired coroutine support for Sol
 * Library author (satoren) is a nice guy!
 * C++11/14, or boostified (which makes it C++03 compatible)
@@ -167,6 +168,7 @@ lua-intf -
 * Macro-based registration (strange pseudo-language)
 * Fairly fast in most regards
 * Registering classes/"modules" in using C++ code is extremely verbose
+* In order to chain lookups, one has to do ``mykey.mykey2`` on the ``operator[]`` lookup (e.g., you can't nest them arbitrarily, you have to pre-compose the proper lookup string) (fails miserably for non-string lookups!).
 * Not too shabby!
 
 Selene -
@@ -204,6 +206,8 @@ luabind -
 * One of the older frameworks, but has many people updating it and providing "deboostified" versions
 * Strange in-lua keywords and parsing to allow for classes to be written in lua
 	- not sure if good feature; vendor lock-in to that library to depend on this specific class syntax?
+* Comprehensive lua bindings (can even bind "properties")
+* Wonky table support: no basic conversion functions on ``luabind::object``; have to push object then use lua API to get what you want
 
 lua-api-pp -
 
@@ -225,7 +229,8 @@ SLB3 -
 oolua -
 
 * The syntax for this library is thicker than a brick. No, seriously. `Go read the docs`_ 
-* The worst in terms of how to use it: may have docs, but the DSL (despite using C++11) is extraordinarily crappy with thick, hard-to-debug/hard-to-error-check macros (and seems not to compile on VS 2015 Update 2 properly for Userdata bindings?)
+* The worst in terms of how to use it: may have docs, but the DSL (despite using C++11) is extraordinarily crappy with thick, hard-to-debug/hard-to-error-check macros
+    - Same problem as lua-api-pp: cannot have the declaration macros anywhere but the toplevel namespace
 * Supports not having exceptions or rtti turned on (shiny!)
 * Poor RAII support: default-construct-and-get style (requires some form of initalization to perform a ``get`` of an object, and it's hard to extend)
 

docs/source/tutorial/getting-started.rst

@@ -3,17 +3,20 @@ getting started
 
 Let's get you going with Sol! To start, you'll need to use a lua distribution of some sort. Sol doesn't provide that: it only wraps the API that comes with it, so you can pick whatever distribution you like for your application. There are lots, but the two popular ones are `vanilla Lua`_ and speedy `LuaJIT`_ . We recommend vanilla Lua if you're getting started, LuaJIT if you need speed and can handle some caveats: the interface for Sol doesn't change no matter what Lua version you're using.
 
-After that, make sure you grab either the `single header file release`_, or just perform a clone of the `github repository here`_ and set your include paths up so that you can get at ``sol.hpp`` somehow. We recommend the single-header-file release, since it's easier to move around, manage and update if you commit it with some form of version control.
+After that, make sure you grab either the `single header file release`_, or just perform a clone of the `github repository here`_ and set your include paths up so that you can get at ``sol.hpp`` somehow. We recommend the single-header-file release, since it's easier to move around, manage and update if you commit it with some form of version control. If you use the github release, you *must* update submodules in order to make sure Optional is present in the repository: clone with:
 
-.. note::
-	
-	If you get an avalanche of errors (particularly referring to ``auto``), you may not have enabled C++14 / C++17 mode for your compiler. Add one of ``std=c++14``, ``std=c++1z`` OR ``std=c++1y`` to your compiler options. By default, this is always-on for VC++ compilers in Visual Studio and friends, but g++ and clang++ require a flag (unless you're on `GCC 6.0`_).
+>>> git clone https://github.com/ThePhD/sol2.git
+>>> git submodule update --init
+
+or, just run
+
+>>> git clone --recursive https://github.com/ThePhD/sol2.git
 
 When you're ready, try compiling this short snippet:
 
 .. code-block:: cpp
 	:linenos:
-	:caption: the first snippet
+	:caption: test.cpp: the first snippet
 	:name: the-first-snippet
 
 	#include <sol.hpp> // or #include "sol.hpp", whichever suits your needs
@@ -28,6 +31,16 @@ When you're ready, try compiling this short snippet:
 		return 0;
 	}
 
+Using this simple command line:
+
+>>> g++ -std=c++14 test.cpp -llua -I"path/to/lua/include" -L"path/to/lua/lib"
+
+Or using your favorite IDE / tool after setting up your include paths and library paths to lua according to the documentation of the Lua distribution you got. Remember your  linked lua library (``-llua``) and include / library paths will depend on your OS, file system, Lua distribution and your installation / compilation method of your Lua distribution.
+
+.. note::
+	
+	If you get an avalanche of errors (particularly referring to ``auto``), you may not have enabled C++14 / C++17 mode for your compiler. Add one of ``std=c++14``, ``std=c++1z`` OR ``std=c++1y`` to your compiler options. By default, this is always-on for VC++ compilers in Visual Studio and friends, but g++ and clang++ require a flag (unless you're on `GCC 6.0`_).
+
 If this works, you're ready to start! The first line creates the ``lua_State`` and will hold onto it for the duration of the scope its declared in (e.g., from the opening ``{`` to the closing ``}``). It will automatically close / cleanup that lua state when it gets destructed. The second line opens a single lua-provided library, "base". There are several other libraries that come with lua that you can open by default, and those are included in the :ref:`sol::lib<lib-enum>` enumeration.
 
 If you're interested in integrating Sol with a project that already uses some other library or Lua in the codebase, check out the :doc:`existing example<existing>` to see how to work with Sol when you add it to a project!