[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Format revisited

Summarizing the ballots is slow going. I hope to be done tomorrow and to
mail out some revisions.

Below is a minor revision of the style sheet which incorporates a couple
of suggestions.

Note that the hardcopy of the issues to x3j13 (and the internal copies I
deal with) have font and paragraph control, but I have no simple way of
mailing them out in that form. However, I'd suggest you not worry about
formatting or grinding of paragraphs.

Format for proposals to "clean up" Common Lisp.
Revision 9 -  4-Jun-87
 >>Replace the text in italics (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 upcase 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, or other references..<<
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, and author and date of
subsequent revisions.<<
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 CLtL or some new specification document.
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.<<
Rationale:  >> A brief argument for the proposal. (If more than one
proposal is listed, discuss each issue separately here and in subsequent
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
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. <<