More scribbling

diff --git a/admin/cl-packages.org b/admin/cl-packages.org
index cb1b14ce70eae164519deb37134b3aaa2a626f4c..abba9c4c7396113ea5cb25a5bee0ac613e53e7e8 100644 (file)
--- a/admin/cl-packages.org
+++ b/admin/cl-packages.org
@@ -4,82 +4,83 @@
 * Common Lisp Packages for Emacs
 
 This is an experimental implementation of CL packages for Emacs.
-The question is if it is possible to add CL packages to Emacs with
-reasonable effort and reasonable compatibility.
 
-I answer this with yes.
+The question of the experiment is if it is possible to add CL packages
+to Emacs with reasonable effort and reasonable compatibility.
 
 Note that this branch is only known to build and run under macOS 12.6.
 I don't have other systems.
 
-
-
+** Overview
 There are two packages defined at present.  The keyword package, named
 "keyword" or "" contains keywords, the Emacs package, with name
 "emacs" contains all other symbols.
 
-Please see a description of the CL package system for what you can do
-with it.  Not everything might yet be implemented.
+Please see a description of the CL package system on the web for what
+you can do with it.  Not everything might yet be implemented.
 
 And bugs, for sure, and so on...
 
-** Implementation notes
+** Problems Found and Approaches to Solving Them
 
-*** No pure space support
-The branch contains a patch by Stefan Monnier that makes it no longer
-use pure space. I didn't want to deal with pure space.
-Note that a small fix in init_vectors is needed for making Stefan's
-patch work.
+Here are the main problems found, and how I approached them.
 
-*** New type Lisp_Package, changes in Lisp_Symbol
-There is a new Lisp data type Lisp_Package defined in lisp.h.
+*** Keywords
+In CL, keywords are symbols in the keyword package.  The leading colon
+of a keyword is not part of its symbol name, but a package prefix.
+The keyword package has a nickname that is an empty string.
 
-Struct Lisp_Symbol has lost its interned flag and its next pointer.
-All symbols now have a package.  Uninterned symbols have a nil
-package.  Keywords have the keyword package.  Other symbols currently
-are in the Emacs package.
+In Emacs, keywords are just symbols whose names start with a colon,
+and that is expected in a ton of places.
 
-*** Obarrays removed
-Obarrays have been removed completely, except for the variable
-Vobarray which is now set to the Emacs package.
+Solution:
 
-obarray.el has been changed to use packages.  Some places in lisp/
-using make-vector for an obarray were changed to use make-package.
+- Internally, keyword names don't contain the colon, which is TRT.
+- symbol-name returns a name with colon for keywords.
+- cl-symbol-name returns the symbol name as-is.
+- intern and intern-soft when called with a name starting with a colon
+  interpret that as wanting a keyword.
 
-*** Keywords
-Keywords are symbols in the keyword package, which has the nickname
-"".  Keywords no longer contain the colon as part of their symbol name.
+*** Package Prefixes
+Existing code contains symbols like GUI:xyz which look like GUI is a
+pracke prefix.
 
-Old:
+** Implementation notes
+*** No pure space support
+The branch contains a patch by Stefan Monnier that makes it no longer
+use pure space.
 
-#+begin_src
-(symbol-name :hansi)
- -> ":hansi"
-#+end_src
+I didn't want to deal with pure space.  Note that a small fix in
+init_vectors is needed for making Stefan's patch work.
 
-New:
-#+begin_src
-(symbol-name :hansi)
- -> "hansi"
-(symbol-package :hansi
- -> <PACKAEG "keyword">
-#+end_src
+*** New type Lisp_Package
+There is a new Lisp data type Lisp_Package defined in lisp.h.
 
-A workaround for existing code that does something like
+***  Lisp_Symbol
+Struct Lisp_Symbol has lost its interned flag and its next pointer.
+The interned flag was an implementation detail necessary because there
+were no packages.  the next pointer was only necessary for the obarray
+implementation of symbol tables.
 
-#+begin_src
-(intern ":hansi")
-#+end_src
+All symbols now have a package.  Uninterned symbols have a nil
+package.
 
-is currently implemented and produces a keyword as it did before. The
-preferred way is to
+Keywords have the keyword package.  Other symbols currently are in the
+Emacs package.  Keyword symbol names do not contain the colon.
 
-#+begin_src
-(intern "hansi" :keyword)
-(intern "hansi" "KEYWORD")
-#+end_src
+*** Obarray
+Obarrays have been removed, to be able to remove Lisp_Symbol::next
+whose sole purpose was to support obarray's hash collision lists.
+
+Legacy code is supported by the following
 
-or something.
+- The variable 'obarray' still exists.  Its value is now the Emacs
+  package.
+- intern, intern-soft, unintern, mapatoms still accept vectors (former
+  obarrays).  When called with a vector, they secretly create and use
+  packages.  This is done because legacy code uses make-vector instead
+  of obarray-make to create obarrays.
+- obarray.el has been changed accordingly.
 
 *** Predefined packages
 
@@ -107,6 +108,8 @@ With package-prefix nil
 Use a file-local package-prefix to enable it.
 
 *** Printer
+*** Shorthands
+Are currently not supported.
 
 The printer prints package prefixes if necessary, which is the case if
 *package* is different from a symbol's package.
@@ -122,3 +125,12 @@ Without:
   'GUI:hansi
   -> unknown package GUI
 #+end_src
+
+
+** Ideas / Todo
+
+- Buffer-local *package*, package-prefixes
+- make_package: allow specifying a start size for symbol hash-table
+- shorthands
+- Add (declare (ignore ...)) goddam :-).
+- Offer cl-symbol-name for sanity.