Format for proposals to the cleanup committee (Version 12)

[Masinter.pa@Xerox.COM]

Include related issues in References section. Changed "proposal" section
to make explicit that these are changes for a new specification document
rather than changes to CLtL.
!
  Format for proposals to the cleanup committee (Version 12)
                    October 23, 1987


Replace the text below in >> double inverted angle-brackets <<. Be
brief; leave testimonials and personal opinions to the discussion at the
end. Be complete; do not expect someone else to fix or redesign parts.
Spell out names (e.g., Masinter rather than LMM) and upper-case all Lisp
symbols (DEFUN rather than Defun). I like it better if you write in the
third person rather than first.

Issue:         >>A short descriptive label, which starts with a name
which occurs in the index of CLtL, and be a suitable symbol in the
Common Lisp style, e.g., CDR-TERMINATION.<<

References:    >>The pages of CLtL which describe the feature being
discussed, and other references, including other related issues.<<

Category:      >>One or more of: CLARIFICATION -- proposal to resolve an
ambiguity or case of under-specified situation in CLtL, where this
ambiguity interferes with portability of code. CHANGE -- proposal for an
incompatible change to the language.  ADDITION -- proposal for a
compatible extension to the language. <<

Edit history:  >>Author and date of submission (version 1), and author
and date of subsequent versions.<<

Problem description:

>>Describe the problem being addressed -- why is the current situation
unclear or unsatisfactory? Avoid describing the proposal here or arguing
for its adoption. <<

Proposal (>>issue-label:proposal-label<<): >> Describe as precisely as
possible what you are proposing.  Ideally, this should take the form of
text that could be dropped into the new specification document.
Proposals should be for changes to Common Lisp, rather than changes to
CLtL.  If necessary, propose a set of labelled alternatives here, rather
than a single proposal. Each proposal must be a complete design; do not
leave out details.  Avoid arguing for the proposal here, just describe
it.<<

Test Case:

>>When possible, give a sample of Common Lisp code that illustrates the
issue. The code should stand alone, and preferably be suitable for
incorporation in a diagnostic suite. <<

Rationale:

>> A brief argument for the proposal. (If more than one proposal is
listed, discuss each issue separately here and in subsequent
sections.)<<

Current practice:

>>Do some/many/no Common Lisp implementations already work this way?
Survey independent Common Lisp implementations - preferably three or
more.<<

Adoption Cost:

>>What is the cost to implementors of adopting the proposal?  How much
implementation effort is required?  Is public-domain code available? For
pervasive changes, can the conversion be automated?<<

Cost of non-adoption:

>>How serious is it if nothing is done? <<

Benefits:

>>What is better if the proposal is adopted? How serious is the problem
if just left as it is? <<

Conversion Cost:

>>For incompatible changes, what is the cost to users of converting
existing user code?  To what extent can the process be automated? How?<<

Esthetics:

>>How does this proposal affect the simplicity of the language, ease of
learning, etc.<<

Discussion:

>> Additional arguments, discussions, endorsements, testimonials, etc.
should go here. A blow-by-blow account of debates is not necessary. <<