suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adjust scribbling style guide for new location

Browse Source 
(and a few other minor tweaks)
This commit is contained in:
Robby Findler 2017-01-06 11:58:39 -06:00
parent 7d70c4cc6e
commit c9100a98c5
1 changed files with 10 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
pkgs/racket-doc/scribblings/style/scribble.scrbl
View File

@ -1,19 +1,12 @@
#lang scribble/doc #lang scribble/doc
@(require scribble/manual scribble/eval "utils.rkt" @(require scribble/eval
(for-label scribble/manual scribble/eval)) "shared.rkt"
(for-label (except-in scribble/manual link)
scribble/eval))
@title[#:tag "reference-style"]{Style Guide} @title[#:tag "reference-style"]{Scribbling Documentation}
Consistent style---for terms, typesetting, and prose---makes This section describes good style for Racket documentation writing.
documentation clearer. As much as possible, follow the rules listed in
this section. Many of the rules are arbitrary in the sense that a
different choice of rule could work fine, but the only way to make our
documentation consistent is to pick one of the choices.
There are too many rules to absorb easily on a first reading. Re-read
this section after writing documentation for a library or two, and
revisit the section periodically to refresh your memory and check for
new rules.
@section{Prose and Terminology} @section{Prose and Terminology}
@ -147,14 +140,13 @@ syntactic constraint, such as requiring a sub-form to be an identifier.
Use @racket[defform/subs] for syntactic constraints. Use @racket[defform/subs] for syntactic constraints.
When showing example evaluations, use the REPL-snapshot style: When showing example evaluations, use the REPL-snapshot style:
@verbatim[#:indent 2]|{ @verbatim[#:indent 2]|{
@interaction[ @examples[
(+ 1 2) (+ 1 2)
] ]
}| }|
See also the @racket[scribble/eval] library and @secref["examples-style"]. See also the @racketmodname[scribble/example] library and @secref["examples-style"].
Use four dots, @litchar{....}, in place of omitted code, since Use four dots, @litchar{....}, in place of omitted code, since
@litchar{...} means repetition. @litchar{...} means repetition.
@ -210,7 +202,7 @@ are terms defined with @racket[deftech].
Symbols are not indexed automatically. Use @racket[indexed-racket] Symbols are not indexed automatically. Use @racket[indexed-racket]
instead of @racket[racket] for the instance of a symbol that roughly instead of @racket[racket] for the instance of a symbol that roughly
defines the use. For an example, try searching for ``truncate'' to defines the use. For an example, try searching for ``truncate'' to
find @racket['truncate] as used with @racket[open-output-file]. Do no find @racket['truncate] as used with @racket[open-output-file]. Do not
use something like @racket[(index "'truncate")] to index a symbol, use something like @racket[(index "'truncate")] to index a symbol,
because it will not typeset correctly (i.e., in a fixed-width font because it will not typeset correctly (i.e., in a fixed-width font
with the color of a literal). with the color of a literal).