doc updates
diff --git a/docs/cmake.rst b/docs/cmake.rst
index 238132f..ace2167 100644
--- a/docs/cmake.rst
+++ b/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
-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`.
+For C++ codebases that already have an existing CMake-based build system, the
+following snippet should be a good starting point to create bindings across
+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
diff --git a/docs/faq.rst b/docs/faq.rst
index 45cb70e..f75498b 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -30,8 +30,24 @@
def increment(i):
i += 1 # nope..
-pybind11 is also affected by such language-level conventions, which means
-that binding ``increment`` or ``increment_ptr`` will also create Python functions that don't modify their arguments.
+pybind11 is also affected by such language-level conventions, which means that
+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.
+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); });
+