* policy/names.text: New file.

devel/policy/names.text

@@ -0,0 +1,127 @@
+[This is currently a collection of information in an unedited state.
+ Someone will change this soon.]
+
+The C names for Scheme primitives *always* obey a fixed name
+translation scheme:
+
+scm_XXX where XXX is translated from the Scheme name, except that
+
+ - becomes _
+ ! becomes _x
+ ? becomes _p
+ % becomes sys_
+
+If there's a C variant of something provided at the Scheme level (like
+the current scm_internal_dynamic_wind), it has the prefix scm_c_
+instead of scm_.
+
+A function named scm_c_FOO serves the same purpose as the function
+named scm_FOO, except that its interface is tailored for use from C,
+while scm_FOO is tailored for use from Scheme, and is probably
+exported as a Scheme primitive.
+
+For example, scm_FOO might expect Scheme procedures as arguments,
+while scm_c_FOO might take C function pointers and a passthrough
+value.
+
+
+If there's a C function with global scope which is only intended to be
+used internally in libguile, it has the prefix scm_i_.
+
+String literals with global scope has the prefix scm_s_.  (Greg
+introduced the prefix s_scm_ but this has to change to scm_s_ since
+s_scm_ trespasses the user's namespace.)
+
+Not correct: Those names have module-local scope and does not trespass
+user name space.
+
+Keywords with global scope has the prefix scm_k_.
+
+Symbols with global scope has the prefix scm_sym_.
+
+Variable bindings with global scope has the prefix scm_var_.
+
+Names, in general, have an internal left-to-right order of increasing
+specificity: scm_ is least specific.  It is often followed by some
+type, like `stack', and, finally, the operation.  Example:
+scm_stack_length.
+
+There are exceptions, though:
+
+* If a name is already established at the Scheme level, this defines
+  the C name through the translation scheme.
+
+* According to the rule, we should have `SCM_SMOB_DATA_SET', but we
+  instead have `SCM_SET_SMOB_DATA'.  Generally, `set' should be placed
+  as far left as possible:
+
+  `port-filename'       scm_port_filename
+  `set-port-filename!'  scm_set_port_filename_x
+
+  SCM_SMOB_DATA
+  SCM_SET_SMOB_DATA
+
+* Guile has a lot of history with lots of different strange names.
+  Perhaps a major name overhaul can be done at the same time as we go
+  through Guile's interfaces to checks soundness and theoretical
+  properties such as type safety.  We *should* be a bit careful with
+  name changes in order not to break existing application code.
+
+> Further, I'd love it if macros to create scheme values from C values would
+> be named SCM_MAKE_... more consitently.  Currently, we have SCM_MAKICHAR
+> (OK, this one's been made deprecated), SCM_MAKINUM and others.
+
+I agree.
+
+> Also, some macros are used for symbols or keywords.  The best solution
+> would be to use a similar naming scheme for these also.
+> 
+> It's good to talk about improving guile's API.  A clean, consistent and
+> beautiful api is, in my belief, important for guile's attractivity, and
+> makes learning it easier.  
+
+Yes!
+
+There are still some open points:
+
+scm_c_XXX : 
+    Only used for C-level variants of a scm_XXX schene primitive, or
+    rather to be used for everything that is not a scheme primitive?
+
+scm_i_XXX :
+    Only for internal _functions_ or rather for everything that is
+    internal?  For example, scm_sym_ is for symbols that may be used by
+    users, while scm_i_sym_ is used for guile internally?  Otherwise we
+    can't distinguish between C variables holding symbols that are part of
+    the official API and internally used C variables holding symbols.
+
+what about boolean variables/constants? scm_bool_?  This would fit nicely
+    with the current macro names SCM_BOOL_T and SCM_BOOL_F.
+
+what about number variables/constants? scm_num_?  There is at least a
+    SCM_MAKINUM(0) somewhere...
+
+scm_s_, scm_k_, scm_sym_, scm_var_:
+    What about macro variants of these?  At least, some symbols and
+    constants are represented as macros.
+
+Macros in general:
+    Should internally used macros be called SCM_I_xxx, thus following the
+    above scheme?
+
+    How do scheme-level names translate if there are macros that do the
+    same thing?  set-car! --> SCM_SETCAR, thus, the '!' is dropped and the
+    intermediate '-' is dropped.  However, this is not done
+    consistently:  sometimes intermediate '-' are _not_ dropped. 
+
+    Currently it seem that:
+
+    - becomes sometimes _ and sometimes nothing 
+    ! becomes nothing
+    ? becomes P for single-word xxx, _P otherwise
+    % becomes I don't know what.
+
+
+I would prefer if both worlds (functions/variables and macros) were using
+similar schemes as far as possible.  (I even dislike the _P/P
+distinction, but I know that I am strange :-)