commit 8f6b31924c1cf8022c2f3cc2fb83d643a633b4e8
parent e690d99f574cafac755704e02de3c41d0224561f
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 3 Jun 2012 02:57:54 +0800
clarifications and additions to style guide
original commit: c5f821b6415a4ad0f073b66b9bbf6455d801ff01
Diffstat:
1 file changed, 20 insertions(+), 3 deletions(-)
diff --git 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
