[cdr-discuss] A proposed convention for *FEATURES*

[Richard M Kreuter]

Nick Levine writes:
> Some comments on this proposal:
> 
> 1. Ought this proposal to be a CDR?

That's an interesting question.  In some sense, it's not necessary: a
document's author can certainly call for whatever features they like
(note that my proposal doesn't require each CDR document to call for any
features, because not every document describes something that programs
can use; for example, CDR 0 does not).  Nevertheless, it seems to me
that it might be good to encourage authors of documents that do specify
programers' interfaces to call for features, and I think that
(informally) reserving a subset of keywords for denoting conformance
with CDR documents, and giving document authors some boilerplate text to
use might facilitate this goal.

> At present
> 
>     #+(not cdr-42) 
> 
> ...doesn't necessarily tell us anything - it could just mean that your
> proposal hasn't been adopted.
>
> But suppose this proposal is CDR number 5 (as of 2007-08-24 this is
> the next in the sequence) and so requires the feature keyword
> :cdr-5. Then
> 
>     #+(and cdr-5
>            (not cdr-42))
> 
> ...implies that your proposal is in effect and therefore that the
> absense of :cdr-42 on *features* means that this implementation isn't
> conforming to CDR-42.

Probably my writeup wasn't clear enough about the following point: my
proposal doesn't say that :CDR-42 in *FEATURES* means that CDR 42 is
implemented.  Instead, it encourages the author of CDR 42 to say that.
Consequently, adoption of /CDR 42/ is what makes :CDR-42 in *FEATURES*
meaningful.  There are no formal or technical criteria for the adoption
of my proposal; it's just a set conventions among CDR document authors,
Lisp and library implementors, and users.  I've tried to change the
wording of the writeup to express this more clearly.

> 2. Names beginning with "CDR-" 
> 
> You suggest:
> 
>     programmers are discouraged from adding keyword symbols to
>     *FEATURES* whose names begin with "CDR-" except as part of
>     implementations of interfaces described in CDR documents.
> 
> Given that you only specify use of keywords beginning with CDR-<nn>,
> I'm curious to know why you restricted keyword use to anything
> beginning with CDR-. Grasping at straws, I wonder whether the
> implementors of a lisp which employed cdr-consing would want to
> announce this to their users by means of the :CDR-CONS feature (the
> presence of which would conflict with your suggestion).

That was a write-o.  I meant to say that people should avoid names
beginning with "CDR-<NN>".  I've changed the wording accordingly.

> 3. Read-time conditionals only?
> 
> You haven't proposed a means of determining after read-time (for
> example: during load of a pre-compiled system, or at runtime) which
> CDRs are in effect. I think this weakens your proposal.
>
> On the other hand, the solution (defun featurep) is fairly clear and
> has previously been documented "elsewhere":
> 
>   http://clrfi.alu.org/clrfi/clrfi-1-featurep
> 
> Should this be revisited and proposed as a CDR?

How and when to use the value *FEATURES* is mostly orthogonal to
conventions about what the elements of *FEATURES* mean, isn't it?  My
only goal was to come up with conventions for what should be in the list
when an implementation or a library conforms to a CDR document's
specification(s).  If people want to examine the list at run-time,
nothing in my proposal stops them; I've added this note to the proposal.

> 4. Minor typo
> 
> I don't know about your reader,, but mine really enjoys complaining
> about "too many commas". (See under "Esthetics")

Fixed.

Below is the diff to effect the changes as above.

--
Richard

Index: cdr-feature-cdr.txt
===================================================================
--- cdr-feature-cdr.txt	(revision 235)
+++ cdr-feature-cdr.txt	(working copy)
@@ -37,42 +37,47 @@
 
 * Proposal
 
-  We propose a convention for naming symbols meant to be included in
+  We propose a convention for naming symbols to be included in
   *FEATURES* for the purpose of advertising purported conformance with
   a CDR document's specifications, and encourage CDR document authors,
   Common Lisp implementors, and library authors to follow such
   conventions when providing purported implementations of such
   specifications.
 
-  CDR documents that describe programmers' interfaces should enumerate
-  a set of symbols in the KEYWORD package whose names begin with a
-  prefix: the string "CDR-" followed by the decimal representation of
-  the number of the CDR document with no leading zeroes.  If the CDR
-  document defines only one level of conformance with the document's
-  specifications (e.g., the document specifies no subsets), then the
-  enumeration of keyword symbols should contain the symbol whose name
-  is the prefix.  If the CDR document defines levels of conformance of
-  its total specification (such as subsets, or even mutually
-  incompatible interfaces), then for each defined level of
-  conformance, the enumeration of keyword symbols should should
-  contain a symbol whose name begins with the prefix, followed by a
-  hyphen, followed by some descriptive name for the subset.
+  An author of a CDR document that describes programmers' interfaces
+  is encouraged to enumerate a set of symbols whose presence in the
+  *FEATURES* list in an environment indicates that the implementors of
+  the environment (which might include third-party libraries) purport
+  to have arranged for the environment to conform to the CDR
+  document's specifications.  The enumerated symbols should be present
+  in the KEYWORD package and have names that begin with a prefix
+  consisting of the string "CDR-" followed by the decimal
+  representation of the number of the CDR document, with no leading
+  zeroes.  If the CDR document defines only one level of conformance
+  with the document's specifications (e.g., the document specifies no
+  subsets), then the set of enumerated symbols should contain the
+  symbol whose name is the prefix.  If the CDR document defines levels
+  of conformance of its total specification (such as subsets, or even
+  mutually incompatible interfaces), then for each defined level of
+  conformance, the set of enumerated of symbols should contain a
+  symbol whose name begins with the prefix, followed by a hyphen,
+  followed by some descriptive name for the subset.
 
   Implementors of an interface described in a CDR document that
-  enumerates a set of keyword symbols as above should ensure that the
-  appropriate symbols occur in the *FEATURES* list when the Lisp
-  environment has been configured to behave in conformance with the
-  specification.  Configuring the Lisp environment might involve
-  loading files, invoking functions, etc.; or the environment may
-  conform to the specification when the host Lisp is initialized, in
-  which case the implementation should include the appropriate symbols
-  in *FEATURES* as early as initialization time.  If, after
-  configuring the Lisp environment to conform to the CDR document's
-  specification, it should be possible to reconfigure the Lisp
-  environment to fail to conform to the specification, whether the
-  corresponding symbol remains in the *FEATURES* list after so
-  reconfiguring is not defined by this proposal, but may be defined by
-  a CDR document or an implementation of a CDR document's interface.
+  enumerates a set of keyword symbols as described above are
+  encouraged to ensure that the appropriate symbols occur in the
+  *FEATURES* list when the Lisp environment has been configured to
+  behave in conformance with the specification.  Configuring the Lisp
+  environment might involve loading files, invoking functions, etc.;
+  or the environment may conform to the specification when Lisp is
+  initialized, in which case the implementation should include the
+  appropriate symbols in *FEATURES* as early as initialization time.
+  If, after configuring the Lisp environment to conform to the CDR
+  document's specification, it should be possible to reconfigure the
+  Lisp environment to fail to conform to the specification, whether
+  the corresponding symbol remains in the *FEATURES* list after so
+  reconfiguring is not defined here, but may be defined by a CDR
+  document or an implementation of a CDR document's interface.
 
   Implementations of Lisps that provide non-standard lettercase
   customs in their symbol names are permitted to vary the lettercase
@@ -80,11 +85,16 @@
   furnish the appropriate effects on those implementations.
 
   Finally, programmers are discouraged from adding keyword symbols to
-  *FEATURES* whose names begin with "CDR-" except as part of
-  implementations of interfaces described in CDR documents.
+  *FEATURES* whose names begin with "CDR-" followed by digit
+  characters except as part of implementations of interfaces described
+  in CDR documents.
 
 * Examples
 
+  Note that these examples do not exhaust the ways that the *FEATURES*
+  list may be used.  In particular, programs may investigate
+  *FEATURES* at times other than read-time, e.g., at run-time.
+
 ** Example 1
 
   Suppose CDR document number 42 defines no subsets of its
@@ -212,7 +222,7 @@
 
   It's slightly ugly to call for symbols such :CDR-<nn>-FOO-BAR-BAZ to
   be members of *FEATURES*, but alternatives are bad or worse.
-  Specifically,, it's inconvenient to use read-time conditionals to
+  Specifically, it's inconvenient to use read-time conditionals to
   check for anything other than the presence of keyword symbols in
   *FEATURES*, it seemed like overkill to call for a package (say,
   "CDR") solely for the names of CDR document interfaces.
@@ -240,3 +250,13 @@
   It is not intended that identifiers of the form CDR-<NN> supplant
   descriptive, mnemonic names for interfaces, libraries, packages,
   systems, etc.
+
+  Note that this document describes conventions that document authors,
+  Lisp implementors and library implementors are encouraged to follow
+  for the benefit of users, and not an interface that any program can
+  meaningfully depend on.  (Purporting to conform to this document's
+  specification would amount to claiming that the environment is prone
+  to purport to conform to other documents' specifications; that
+  metaclaim can't possibly be useful to programs.)  Consequently this
+  document's specification does not enumerate any features that denote
+  purported conformance with itself.