doc: Split docs.rst into multiple files.

doc/acknowledgments.rst

@@ -0,0 +1,12 @@
+Acknowledgments
+===============
+
+Written by Daniel Wallin and Arvid Norberg. © Copyright 2003.
+All rights reserved.
+
+Evan Wies has contributed with thorough testing, countless bug reports
+and feature ideas.
+
+This library was highly inspired by Dave Abrahams' Boost.Python_ library.
+
+.. _Boost.Python: http://www.boost.org/libraries/python

doc/basic-usage.rst

@@ -0,0 +1,70 @@
+Basic usage
+===========
+
+To use luabind, you must include ``lua.h`` and luabind's main header file::
+
+    extern "C"
+    {
+        #include "lua.h"
+    }
+
+    #include <luabind/luabind.hpp>
+
+This includes support for both registering classes and functions. If you just
+want to have support for functions or classes you can include
+``luabind/function.hpp`` and ``luabind/class.hpp`` separately::
+
+    #include <luabind/function.hpp>
+    #include <luabind/class.hpp>
+
+The first thing you need to do is to call ``luabind::open(lua_State*)`` which
+will register the functions to create classes from Lua, and initialize some
+state-global structures used by luabind. If you don't call this function you
+will hit asserts later in the library. There is no corresponding close function
+because once a class has been registered in Lua, there really isn't any good
+way to remove it. Partly because any remaining instances of that class relies
+on the class being there. Everything will be cleaned up when the state is
+closed though.
+
+.. Isn't this wrong? Don't we include lua.h using lua_include.hpp ?
+
+Luabind's headers will never include ``lua.h`` directly, but through
+``<luabind/lua_include.hpp>``. If you for some reason need to include another
+Lua header, you can modify this file.
+
+
+Hello world
+-----------
+
+::
+
+    #include <iostream>
+    #include <luabind/luabind.hpp>
+
+    void greet()
+    {
+        std::cout << "hello world!\n";
+    }
+
+    extern "C" int init(lua_State* L)
+    {
+        using namespace luabind;
+
+        open(L);
+
+        module(L)
+        [
+            def("greet", &greet)
+        ];
+
+        return 0;
+    }
+
+::
+
+    Lua 5.0  Copyright (C) 1994-2003 Tecgraf, PUC-Rio
+    > loadlib('hello_world.dll', 'init')()
+    > greet()
+    Hello world!
+    >
+

doc/build-options.rst

@@ -0,0 +1,72 @@
+Build options
+=============
+
+There are a number of configuration options available when building luabind.
+It is very important that your project has the exact same configuration 
+options as the ones given when the library was build! The exceptions are the
+``LUABIND_MAX_ARITY`` and ``LUABIND_MAX_BASES`` which are template-based 
+options and only matters when you use the library (which means they can 
+differ from the settings of the library).
+
+The default settings which will be used if no other settings are given
+can be found in ``luabind/config.hpp``.
+
+If you want to change the settings of the library, you can modify the 
+config file. It is included and used by all makefiles. You can change paths
+to Lua and boost in there as well.
+
+LUABIND_MAX_ARITY
+    Controls the maximum arity of functions that are registered with luabind. 
+    You can't register functions that takes more parameters than the number 
+    this macro is set to. It defaults to 5, so, if your functions have greater 
+    arity you have to redefine it. A high limit will increase compilation time.
+
+LUABIND_MAX_BASES
+    Controls the maximum number of classes one class can derive from in 
+    luabind (the number of classes specified within ``bases<>``). 
+    ``LUABIND_MAX_BASES`` defaults to 4. A high limit will increase 
+    compilation time.
+
+LUABIND_NO_ERROR_CHECKING
+    If this macro is defined, all the Lua code is expected only to make legal 
+    calls. If illegal function calls are made (e.g. giving parameters that 
+    doesn't match the function signature) they will not be detected by luabind
+    and the application will probably crash. Error checking could be disabled 
+    when shipping a release build (given that no end-user has access to write 
+    custom Lua code). Note that function parameter matching will be done if a 
+    function is overloaded, since otherwise it's impossible to know which one 
+    was called. Functions will still be able to throw exceptions when error 
+    checking is disabled.
+
+    If a function throws an exception it will be caught by luabind and 
+    propagated with ``lua_error()``.
+
+LUABIND_NO_EXCEPTIONS
+    This define will disable all usage of try, catch and throw in luabind. 
+    This will in many cases disable run-time errors, when performing invalid 
+    casts or calling Lua functions that fails or returns values that cannot 
+    be converted by the given policy. luabind requires that no function called 
+    directly or indirectly by luabind throws an exception (throwing exceptions 
+    through Lua has undefined behavior).
+
+    Where exceptions are the only way to get an error report from luabind, 
+    they will be replaced with calls to the callback functions set with
+    ``set_error_callback()`` and ``set_cast_failed_callback()``.
+
+LUA_API
+    If you want to link dynamically against Lua, you can set this define to 
+    the import-keyword on your compiler and platform. On Windows in Visual Studio 
+    this should be ``__declspec(dllimport)`` if you want to link against Lua 
+    as a dll.
+
+LUABIND_DYNAMIC_LINK
+    Must be defined if you intend to link against the luabind shared
+    library.
+
+LUABIND_NO_RTTI
+    You can define this if you don't want luabind to use ``dynamic_cast<>``.
+    It will disable `Object identity`_.
+
+NDEBUG
+    This define will disable all asserts and should be defined in a release 
+    build.