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

expand Scribble-layers overview

Browse Source 
svn: r8241

original commit: 4ba06b7ae0
This commit is contained in:
Matthew Flatt 2008-01-07 03:50:43 +00:00 committed by Robby Findler
parent 7c87184951
commit ea534e55c0
1 changed files with 17 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,10 +1,13 @@
#lang scribble/doc
@(require scribble/manual
scribble/eval
"utils.ss"
(for-label scribble/manual))
@title[#:tag "reference-style"]{Style Guide}
@section{Prose and Terminology}
In the descriptive body of @scheme[defform], @scheme[defproc], etc.,
do not start with ``This ...'' Instead, start with a sentence whose
implicit subject is the form or value being described. Thus, the
@ -17,7 +20,8 @@ values or expressions in a function call. Refer to libraries and
languages as such, rather than as ``modules'' (even though the form to
typeset a library or language name is called @scheme[schememodname]).
Do not call an identifier (i.e., a syntactic element) a ``variable''
or a ``symbol.''
or a ``symbol.'' Do not use the word ``expression'' for a form that is
a definition or might be a definition; use the word ``form,'' instead.
Avoid cut-and-paste for descriptive text. If two functions are
similar, consider documenting them together with
@ -27,6 +31,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.
@section{Typesetting Code}
Use @schemeidfont{id} or a name that ends @schemeidfont{-id} in
@scheme[defform] to mean an identifier, not @schemeidfont{identifier},
@schemeidfont{variable}, @schemeidfont{name}, or
@ -74,6 +80,16 @@ variable, meta-variable, etc.---use @scheme[schemeidfont] (e.g., as in
not merely @scheme[schemefont] or @scheme[verbatim], to refer to a
specific sequence of characters.
When showing example evaluations, use the REPL-snapshot style:
@interaction[
(+ 1 2)
]
See also the @scheme[scribble/eval] library.
@section{Typesetting Prose}
Refrain from referring to documentation ``above'' or ``below,'' and
instead have a hyperlink point to the right place.