DEFVAR-DOCUMENTATION (Version 1)

[Kent M Pitman <KMP@STONY-BROOK.SCRC.Symbolics.COM>]

Issue:        DEFVAR-DOCUMENTATION
References:   DEFVAR, DEFPARAMETER, DEFCONSTANT (pp68-9)
Category:     CLARIFICATION
Edit history: 30-Jun-87, Version 1 by Pitman
Status:	      For Internal Discussion

Problem Description:

  CLtL is not explicit about whether the documentation part of
  DEFVAR, DEFPARAMETER, and DEFCONSTANT special forms is evaluated.

Proposal (DEFVAR-DOCUMENTATION:UNEVALUATED):

  Clarify that the documentation part of DEFVAR, DEFPARAMETER, and
  DEFCONSTANT special forms is not evaluated. That is, it must be
  a literal string, not a form which evaluates to a string.

Rationale:

  To ensure portability, implementations must agree on whether or not
  this position is evaluated. Specifying that the position is unevaluated
  is the conservative thing to suggest.

Current Practice:

  Some implementations evaluate this position. Others do not.

Adoption Cost:

  The change is presumably trivial in all implementations.

Benefits:

  Code portability would be improved.

Conversion Cost:

  Code which uses other than a literal string is not portable, so no portable
  programs will be broken. Some non-portable programs which rely on a particular
  vendor's interpretation would have to be rewritten. Automatic tools to detect
  most offending cases could trivially be constructed.

Aesthetics:

  No significant impact.

Discussion:

  Pitman thinks this is a good idea.