commit 7de01e897e8e7eff87f59aafb5a888cdc04814fe
parent 12f7e3c037540798a3e4f568b3eefe45725ebd2f
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 2 Jan 2008 03:33:00 +0000
finish first draft of HtDP language docs
svn: r8179
original commit: d4482c90ca2fa711ac2d02f1d825a1540de338ca
Diffstat:
2 files changed, 24 insertions(+), 6 deletions(-)
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
@@ -222,6 +222,7 @@
(provide schemeblock SCHEMEBLOCK schemeblock/form
schemeblock0 SCHEMEBLOCK0 schemeblock0/form
+ schemeblockelem
schemeinput
schememod
scheme SCHEME scheme/form schemeresult schemeid schememodname
@@ -442,7 +443,9 @@
(provide declare-exporting
deftogether
- defproc defproc* defstruct defthing defthing* defparam defparam* defboolparam
+ defproc defproc* defstruct
+ defthing defthing* defthing/proc
+ defparam defparam* defboolparam
defform defform* defform/subs defform*/subs defform/none
defidform
specform specform/subs
@@ -762,6 +765,10 @@
(syntax-rules ()
[(_ id) (*var 'id)]))
+ (define (defthing/proc id contract descs)
+ (*defthing (list id) (list (syntax-e id)) #f (list contract)
+ (lambda () descs)))
+
(define (into-blockquote s)
(cond
[(splice? s)
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
@@ -19,6 +19,14 @@ 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.''
+Avoid cut-and-paste for descriptive text. If two functions are
+similar, consider documenting them together with
+@scheme[deftogether]. To abstract a description, consider using
+explicit prose abstraction, such as ``@scheme[x] is like @scheme[@y],
+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.
+
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
@@ -69,10 +77,13 @@ specific sequence of characters.
Refrain from referring to documentation ``above'' or ``below,'' and
instead have a hyperlink point to the right place.
-Use American style for quotation marks and punctuation at the end of
-quotation marks (i.e., a sentence-terminating period goes inside the
-quotation marks). Of course, this rule does not apply for quotation
-marks that are part of code.
+In prose, use @litchar{``} and @litchar{''} quotation marks instead of
+@litchar{"}. Use @litchar{---} for an em-dash, and do not include
+spaces on either side, though it will typeset as an en-dash and spaces
+in HTML output. Use American style for quotation marks and punctuation
+at the end of quotation marks (i.e., a sentence-terminating period
+goes inside the quotation marks). Of course, this rule does not apply
+for quotation marks that are part of code.
Do not use a citation reference (as created by @scheme[cite]) as a
-noun. Use it as an annotation.
+noun; use it as an annotation.
