Clarify documentation regarding "cdef public"

docs/src/userguide/external_C_code.rst

@@ -339,42 +339,57 @@ Public Declarations
 ---------------------
 
 You can make C types, variables and functions defined in a Cython module
-accessible to C code that is linked with the module, by declaring them with
-the public keyword::
+accessible to C code that is linked together with the Cython-generated C file,
+by declaring them with the public keyword::
 
     cdef public struct Bunny: # public type declaration
         int vorpalness
 
     cdef public int spam # public variable declaration
 
-    cdef public void grail(Bunny *): # public function declaration
-        print "Ready the holy hand grenade"
+    cdef public void grail(Bunny *) # public function declaration
 
 If there are any public declarations in a Cython module, a header file called
 :file:`modulename.h` file is generated containing equivalent C declarations for
 inclusion in other C code.
 
-Users who are embedding Python in C with Cython need to make sure to call Py_Initialize()
-and Py_Finalize(). For example, in the following snippet that includes :file:`modulename.h`::
+A typical use case for this is building an extension module from multiple
+C sources, one of them being Cython generated (i.e. with something like
+``Extension("grail", sources=["grail.pyx", "grail_helper.c"])`` in ``setup.py``.
+In this case, the file ``grail_helper.c`` just needs to add
+``#include "grail.h"`` in order to access the public Cython variables.
+
+A more advanced use case is embedding Python in C using Cython.
+In this case, make sure to call Py_Initialize() and Py_Finalize().
+For example, in the following snippet that includes :file:`grail.h`:
+
+.. code-block:: c
 
     #include <Python.h>
-    #include "modulename.h"
+    #include "grail.h"
 
-    void grail() {
+    int main() {
         Py_Initialize();
-        initmodulename();
+        initgrail();
         Bunny b;
         grail(b);
         Py_Finalize();
     }
 
-Any C code wanting to make use of these declarations will need to be linked,
-either statically or dynamically, with the extension module.
+This C code can then be built together with the Cython-generated C code
+in a single program (or library).
 
 If the Cython module resides within a package, then the name of the ``.h``
 file consists of the full dotted name of the module, e.g. a module called
 :mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
 
+.. NOTE::
+
+    On some operating systems like Linux, it is also possible to first
+    build the Cython extension in the usual way and then link against
+    the resulting ``.so`` file like a dynamic library.
+    Beware that this is not portable, so it should be avoided.
+
 .. _api:
 
 C API Declarations