diff --git a/pkgs/racket-doc/scribblings/style/scribble.scrbl b/pkgs/racket-doc/scribblings/style/scribble.scrbl index 90417f8f1f..29c554389d 100644 --- a/pkgs/racket-doc/scribblings/style/scribble.scrbl +++ b/pkgs/racket-doc/scribblings/style/scribble.scrbl @@ -40,7 +40,7 @@ Use the word ``list'' only when you mean a run-time value consisting of the empty list and cons cells; use the word ``sequence'' in other cases, if you must use any word. For example, do not write that @racket[begin] has a ``list of sub-forms;'' instead, it has a -``sequence of subforms.'' Similarly, do not refer to a ``list of +``sequence of sub-forms.'' Similarly, do not refer to a ``list of arguments'' in a function call; just write ``arguments'' if possible, or write ``sequence of argument expressions.'' (Unfortunately, ``@tech[#:doc '(lib @@ -56,6 +56,8 @@ except that ...,'' instead of abstracting the source and instantiating it multiple times; often, a prose abstraction is clearer to the reader than a hidden abstraction in the document implementation. +Hyphenate the words ``sub-form'' and ``sub-expression.'' + @section{Typesetting Code} Use @racketidfont{id} or a name that ends @racketidfont{-id} in @@ -149,6 +151,10 @@ Do not start a sentence with a Racket variable name, since it is normally lowercase. For example, use ``The @racket[_thing] argument is...'' instead of ``@racket[_thing] is...'' +Use @racket[etc] for ``@|etc|'' when it does not end a sentence, and +include a comma after ``@|etc|'' unless it ends a sentence of is +followed by other punctuation (such as a parenthesis). + @section{Section Titles} Capitalize all words except articles (``the,'' ``a,'' etc.),