clarify that C name specifications are not for everyday use

docs/src/userguide/external_C_code.rst

@@ -213,39 +213,57 @@ Cython, with the same syntax as used by C compilers on Windows, for example,::
 If ``__stdcall`` is used, the function is only considered compatible with
 other ``__stdcall`` functions of the same signature.
 
+
 Resolving naming conflicts - C name specifications
-----------------------------------------------------
+--------------------------------------------------
 
 Each Cython module has a single module-level namespace for both Python and C
 names.  This can be inconvenient if you want to wrap some external C functions
 and provide the Python user with Python functions of the same names.
 
-Cython provides a couple of different ways of solving this problem. The
-best way, especially if you have many C functions to wrap, is probably to put
-the extern C function declarations into a different namespace using the
-facilities described in the section on sharing declarations between Cython
-modules.
+Cython provides a couple of different ways of solving this problem.  The best
+way, especially if you have many C functions to wrap, is to put the extern
+C function declarations into a ``.pxd`` file and thus a different namespace,
+using the facilities described in the section on sharing declarations between
+Cython modules.  Writing them into a ``.pxd`` file allows their reuse across
+modules, avoids naming collisions in the normal Python way and even makes it
+easy to rename them on cimport.  For example, if your ``decl.pxd`` file
+declared a C function ``eject_tomato``::
 
-The other way is to use a C name specification to give different Cython and C
-names to the C function. Suppose, for example, that you want to wrap an
-external function called :func:`eject_tomato`. If you declare it as::
+    cdef extern from "myheader.h":
+        void eject_tomato(float speed)
 
-    cdef extern void c_eject_tomato "eject_tomato" (float speed)
+then you can cimport and wrap it in a ``.pyx`` file as follows::
 
-then its name inside the Cython module will be ``c_eject_tomato``, whereas its name
-in C will be ``eject_tomato``. You can then wrap it with::
+    from decl cimport eject_tomato as c_eject_tomato
 
     def eject_tomato(speed):
         c_eject_tomato(speed)
 
-so that users of your module can refer to it as ``eject_tomato``.
+or simply cimport the ``.pxd`` file and use it as prefix::
+
+    cimport decl
+
+    def eject_tomato(speed):
+        decl.eject_tomato(speed)
+
+For special cases where namespacing or renaming on import is not enough,
+e.g. when a name in C conflicts with a Python keyword, you can use a C name
+specification to give different Cython and C names to the C function at
+declaration time.  Suppose, for example, that you want to wrap an external
+C function called :func:`yield`.  If you declare it as::
+
+    cdef extern from "myheader.h":
+        void c_yield "yield" (float speed)
+
+then its Cython visible name will be ``c_yield``, whereas its name in C
+will be ``yield``.  You can then wrap it with::
 
-Another use for this feature is referring to external names that happen to be
-Cython keywords. For example, if you want to call an external function called
-print, you can rename it to something else in your Cython module.
+    def call_yield(speed):
+        c_yield(speed)
 
-As well as functions, C names can be specified for variables, structs, unions,
-enums, struct and union members, and enum values. For example,::
+As for functions, C names can be specified for variables, structs, unions,
+enums, struct and union members, and enum values.  For example::
 
     cdef extern int one "ein", two "zwei"
     cdef extern float three "drei"
@@ -257,8 +275,16 @@ enums, struct and union members, and enum values. For example,::
         first "alpha"
         second "beta" = 3
 
+Note that Cython will not do any validation or name mangling on the string
+you provide.  It will inject the bare text into the C code unmodified, so you
+are entirely on your own with this feature.  If you want to declare a name
+``xyz`` and have Cython inject the text "make the C compiler fail here" into
+the C file for it, you can do this using a C name declaration.  Consider this
+an advanced feature, only for the rare cases where everything else fails.
+
+
 Using Cython Declarations from C
-==================================
+================================
 
 Cython provides two methods for making C declarations from a Cython module
 available for use by external C code---public declarations and C API