doc updates

docs/cmake.rst

@@ -1,11 +1,26 @@
+Build systems
+#############
+
+Building with setuptools
+========================
+
+For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
+has kindly provided an example project which shows how to set up everything,
+including automatic generation of documentation using Sphinx. Please refer to
+the [pbtest]_ repository.
+
+.. [pbtest] https://github.com/pybind/pbtest
+
 .. _cmake:
 
 Building with CMake
 ===================
 
-The following snippet should be a good starting point to create bindings across
+For C++ codebases that already have an existing CMake-based build system, the
-platforms. It assumes that the code is located in a file named :file:`example.cpp`,
+following snippet should be a good starting point to create bindings across
-and that the pybind11 repository is located in a subdirectory named :file:`pybind11`.
+platforms. It assumes that the code is located in a file named
+:file:`example.cpp`, and that the pybind11 repository is located in a
+subdirectory named :file:`pybind11`.
 
 .. code-block:: cmake
 

docs/faq.rst

@@ -30,8 +30,24 @@ provided by the caller -- in fact, it does nothing at all.
     def increment(i):
         i += 1 # nope..
 
-pybind11 is also affected by such language-level conventions, which means
+pybind11 is also affected by such language-level conventions, which means that
-that binding ``increment`` or ``increment_ptr`` will also create Python functions that don't modify their arguments.
+binding ``increment`` or ``increment_ptr`` will also create Python functions
+that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types in
+a custom type that does allow modifications. 
+
+An other alternative involves binding a small wrapper lambda function that
+returns a tuple with all output arguments (see the remainder of the
+documentation for examples on binding lambda functions). An example:
+
+.. code-block:: cpp
+
+    int foo(int &i) { i++; return 123; }
+
+and the binding code
+
+.. code-block:: cpp
+
+   m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
 
-Although inconvenient, one workaround is to encapsulate the immutable types
-in a custom type that does allow modifications.