Thu Mar 8 05:15:58 UTC 2012 pix@kepibu.org
* Rename notes.org to README.org
diff -rN -u old-portaCL/README.org new-portaCL/README.org
--- old-portaCL/README.org 1970-01-01 00:00:00.000000000 +0000
+++ new-portaCL/README.org 2013-06-15 10:34:12.000000000 +0000
@@ -0,0 +1,119 @@
+#+TITLE: PortaCL: Easing the Creation of CL Portability Libraries
+
+* Rationale
+
+Sometimes you want to do something based upon *features*. Often, that results
+in lots of reader conditionals, and a final reader conditional duplicating and
+negating all previous conditionals. Ew!
+
+* API
+
+** ASDF Components: port-file, port-module
+
+It's not uncommon for a portability library to include something like:
+ :(:file
+ : #+sbcl "port-sbcl"
+ : #+clisp "port-clisp"
+ : #-(or sbcl clisp) (error "not supported"))
+port-file and port-modules allow you to specify things more like so:
+ :(:port-file "port-~A")
+or, less positionally,
+ :(:port-file "port-~/implementation/")
+
+Whether such magical divinations are a good thing is left to you to decide.
+
+port-file and port-module both also support specification of an :alternate-file,
+which if specified will be used in place of throwing a not-implemented error.
+E.g., for use if only one or two implementations need special behavior.
+
+You can also specify :not-found-condition, the condition type which will be
+thrown if no applicable file is found. (e.g., you might prefer 'not-supported
+instead, or 'not-necessary if a missing component is okay).
+
+** Condition: not-implemented
+
+Useful for indicating a particular thing is not implemented.
+
+This is the default condition thrown when an implementation-specific ASDF
+component is not found.
+
+** Condition: not-supported
+
+A particular thing is not implemented and won't be. E.g., because the lisp
+implementation lacks the necessary features.
+
+** Condition: not-necessary
+
+If this thing is not implemented, it didn't need to be.
+
+When specified as the :not-found-condition in a defsystem form, will cause
+operations on the component to be considered successful even if the component
+could not be found.
+
+** Function: featurep feature-expression
+
+Given a feature expression, returns true if that expression is true.
+
+see [[http://www.lispworks.com/documentation/HyperSpec/Body/24_aba.htm][CLHS 24.1.2.1]] for details.
+
+** Macro: define-feature-test test-name-or-names lambda-list [documentation] &body
+
+Defines a feature test which shall return true if the given feature expressions apply.
+
+see [[http://repo.kepibu.org/portaCL/feature-tests.lisp][feature-tests.lisp]] for usage examples.
+
+** Macro: feature-cond ([feature-conditional] [clause]+)*
+
+A macro version of #+foo (thing) #+bar (thing2) #-(or foo bar) (no-thing), with
+all the caveats and shortcomings that implies.
+
+** Macro: feature-ecase ([[feature-conditional] [clause]+]+)
+
+feature-case, except always includes a final (error 'not-implemented).
+
+* Future Ideas
+
+** ASDF component enhancements
+*** platform / operating system
+
+It might be useful to also offer up the operating system for interpolation into
+port-files. (e.g., via ~/platform/ or ~/operating-system/).
+
+*** shared-implementation support
+
+It might also be useful to offer a way to specify that certain implementations
+should be treated just like another implementation. E.g.,
+ :(:port-file "port-~a" :treat-as (:ecl :sbcl))
+could be used by usocket, instead of futzing with :alternate-file.
+
+** Other porting styles?
+
+Per-file implementation is not the only possible or used porting approach.
+Perhaps some others should also be supported?
+
+ * SLIME's defimplementation
+ * Xach's CLOS-based approach
+ * Any others?
+
+* Bugs
+
+ * ASDF systems sometimes try to recursively load themselves a couple
+ hundred times. (Though I've seen that even without loading portaCL, so
+ may not be entirely my bug...)
+ * Constructs similar to the ones below will result in an incorrect
+ package-error:
+ :(list #+(or) #+package:notexported a b c)
+ :(list #+(or) #+notapackage:foo a b c)
+ NOTE: this bug is shared by the standard readers of at least SBCL,
+ Clisp, and Lispworks; but not by Allegro.
+
+* see also
+
+[[http://www.cliki.net/trivial-features][trivial-features]]
+ smooths out the unnecessary differences between implementation *features*
+[[http://common-lisp.net/project/alexandria/][alexandria]]
+ implements a #'featurep which exactly matches that used by the standard's
+ #+/#- readmacros.
+[[http://common-lisp.net/project/cl-syntax-sugar/][cl-syntax-sugar]]
+ Offers a feature-case reader which is almost certainly more useful than
+ portaCL's feature-cond macro.
diff -rN -u old-portaCL/notes.org new-portaCL/notes.org
--- old-portaCL/notes.org 2013-06-15 10:34:12.000000000 +0000
+++ new-portaCL/notes.org 1970-01-01 00:00:00.000000000 +0000
@@ -1,119 +0,0 @@
-#+TITLE: PortaCL: Easing the Creation of CL Portability Libraries
-
-* Rationale
-
-Sometimes you want to do something based upon *features*. Often, that results
-in lots of reader conditionals, and a final reader conditional duplicating and
-negating all previous conditionals. Ew!
-
-* API
-
-** ASDF Components: port-file, port-module
-
-It's not uncommon for a portability library to include something like:
- :(:file
- : #+sbcl "port-sbcl"
- : #+clisp "port-clisp"
- : #-(or sbcl clisp) (error "not supported"))
-port-file and port-modules allow you to specify things more like so:
- :(:port-file "port-~A")
-or, less positionally,
- :(:port-file "port-~/implementation/")
-
-Whether such magical divinations are a good thing is left to you to decide.
-
-port-file and port-module both also support specification of an :alternate-file,
-which if specified will be used in place of throwing a not-implemented error.
-E.g., for use if only one or two implementations need special behavior.
-
-You can also specify :not-found-condition, the condition type which will be
-thrown if no applicable file is found. (e.g., you might prefer 'not-supported
-instead, or 'not-necessary if a missing component is okay).
-
-** Condition: not-implemented
-
-Useful for indicating a particular thing is not implemented.
-
-This is the default condition thrown when an implementation-specific ASDF
-component is not found.
-
-** Condition: not-supported
-
-A particular thing is not implemented and won't be. E.g., because the lisp
-implementation lacks the necessary features.
-
-** Condition: not-necessary
-
-If this thing is not implemented, it didn't need to be.
-
-When specified as the :not-found-condition in a defsystem form, will cause
-operations on the component to be considered successful even if the component
-could not be found.
-
-** Function: featurep feature-expression
-
-Given a feature expression, returns true if that expression is true.
-
-see [[http://www.lispworks.com/documentation/HyperSpec/Body/24_aba.htm][CLHS 24.1.2.1]] for details.
-
-** Macro: define-feature-test test-name-or-names lambda-list [documentation] &body
-
-Defines a feature test which shall return true if the given feature expressions apply.
-
-see [[http://repo.kepibu.org/portaCL/feature-tests.lisp][feature-tests.lisp]] for usage examples.
-
-** Macro: feature-cond ([feature-conditional] [clause]+)*
-
-A macro version of #+foo (thing) #+bar (thing2) #-(or foo bar) (no-thing), with
-all the caveats and shortcomings that implies.
-
-** Macro: feature-ecase ([[feature-conditional] [clause]+]+)
-
-feature-case, except always includes a final (error 'not-implemented).
-
-* Future Ideas
-
-** ASDF component enhancements
-*** platform / operating system
-
-It might be useful to also offer up the operating system for interpolation into
-port-files. (e.g., via ~/platform/ or ~/operating-system/).
-
-*** shared-implementation support
-
-It might also be useful to offer a way to specify that certain implementations
-should be treated just like another implementation. E.g.,
- :(:port-file "port-~a" :treat-as (:ecl :sbcl))
-could be used by usocket, instead of futzing with :alternate-file.
-
-** Other porting styles?
-
-Per-file implementation is not the only possible or used porting approach.
-Perhaps some others should also be supported?
-
- * SLIME's defimplementation
- * Xach's CLOS-based approach
- * Any others?
-
-* Bugs
-
- * ASDF systems sometimes try to recursively load themselves a couple
- hundred times. (Though I've seen that even without loading portaCL, so
- may not be entirely my bug...)
- * Constructs similar to the ones below will result in an incorrect
- package-error:
- :(list #+(or) #+package:notexported a b c)
- :(list #+(or) #+notapackage:foo a b c)
- NOTE: this bug is shared by the standard readers of at least SBCL,
- Clisp, and Lispworks; but not by Allegro.
-
-* see also
-
-[[http://www.cliki.net/trivial-features][trivial-features]]
- smooths out the unnecessary differences between implementation *features*
-[[http://common-lisp.net/project/alexandria/][alexandria]]
- implements a #'featurep which exactly matches that used by the standard's
- #+/#- readmacros.
-[[http://common-lisp.net/project/cl-syntax-sugar/][cl-syntax-sugar]]
- Offers a feature-case reader which is almost certainly more useful than
- portaCL's feature-cond macro.