From 8f6b31924c1cf8022c2f3cc2fb83d643a633b4e8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 3 Jun 2012 02:57:54 +0800 Subject: [PATCH] clarifications and additions to style guide original commit: c5f821b6415a4ad0f073b66b9bbf6455d801ff01 --- collects/scribblings/scribble/style.scrbl | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl index e8e51bec..fc4e60b3 100644 --- a/collects/scribblings/scribble/style.scrbl +++ b/collects/scribblings/scribble/style.scrbl @@ -19,9 +19,10 @@ new rules. In the descriptive body of @racket[defform], @racket[defproc], etc., do not start with ``This ...'' Instead, start with a sentence whose -implicit subject is the form or value being described. Capitalize the -first word. Thus, the description will often start with ``Returns'' or -``Produces.'' Refer to arguments and sub-forms by name. +implicit subject is the form or value being described (but only start +the first sentence that way). Capitalize the first word. Thus, the +description will often start with ``Returns'' or ``Produces.'' Refer +to arguments and sub-forms by name. Do not use the word ``argument'' to describe a sub-form in a syntactic form; use the term ``sub-form'' instead, reserving ``argument'' for @@ -119,6 +120,21 @@ variable, meta-variable, etc.---use @racket[racketidfont] (e.g., as in not merely @racket[racketfont] or @racket[verbatim], to refer to a specific sequence of characters. +When a syntactic form synthesizes an identifier from a given +identifier, use a combination of @racket[racketidfont] and +@racket[racket] to describe the identifiers. For example, if +@racket[_id] is combined with @racketidfont{is-} and @racketidfont{?} +to form @racketidfont{is-}@racket[_id]@racketidfont{?}, then implement +that identifier as +@code[#:lang "at-exp racket"]|{@racketidfont{is-}@racket[id]@racketidfont{?}}|. + +When using @racket[defform] to describe a syntactic form, don't +confuse the @racket[#:contracts] clause with a grammar +specification. Use @racket[#:contracts] only for expressions within the +syntactic form, and the contract is a run-time constraint---not a +syntactic constraint, such as requiring a sub-form to be an identifier. +Use @racket[defform/subs] for syntactic constraints. + When showing example evaluations, use the REPL-snapshot style: @verbatim[#:indent 2]|{ @@ -132,6 +148,7 @@ See also the @racket[scribble/eval] library and @secref["examples-style"]. Use four dots, @litchar{....}, in place of omitted code, since @litchar{...} means repetition. + @section{Typesetting Prose} Refrain from referring to documentation ``above'' or ``below,'' and