commit 69ee9cce11d18178e2e10ee85cbab23ac9c790fa
parent 1b21a6d56ed466251dcc6f40a96b9f2b528731e7
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 18 Dec 2007 13:52:50 +0000
document mz/mr command-line arguments
svn: r8047
original commit: 058d8dc77eca3023f96280c0f19029f2ffe02d02
Diffstat:
3 files changed, 42 insertions(+), 7 deletions(-)
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
@@ -232,7 +232,7 @@
(provide image onscreen menuitem defterm
schemefont schemevalfont schemeresultfont schemeidfont schemevarfont
schemeparenfont schemekeywordfont schememetafont schememodfont
- filepath exec envvar Flag DFlag
+ filepath exec envvar Flag DFlag PFlag DPFlag
indexed-file indexed-envvar
link procedure
idefterm)
@@ -284,6 +284,10 @@
(make-element 'no-break (list (make-element 'tt (cons "-" (decode-content str))))))
(define (DFlag . str)
(make-element 'no-break (list (make-element 'tt (cons "--" (decode-content str))))))
+ (define (PFlag . str)
+ (make-element 'no-break (list (make-element 'tt (cons "+" (decode-content str))))))
+ (define (DPFlag . str)
+ (make-element 'no-break (list (make-element 'tt (cons "++" (decode-content str))))))
(define (envvar . str)
(make-element 'tt (decode-content str)))
(define (indexed-envvar . str)
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
@@ -245,7 +245,7 @@ hovers the mouse over one of the bindings defined within the section.}
(keyword arg-id contract-expr-datum)
(keyword arg-id contract-expr-datum default-expr)])]{
-Produces a sequence of flow elements (encaptured in a @scheme[splice])
+Produces a sequence of flow elements (encapsulated in a @scheme[splice])
to document a procedure named @scheme[id]. The @scheme[id] is indexed,
and it also registered so that @scheme[scheme]-typeset uses of the
identifier (with the same for-label binding) are hyperlinked to this
@@ -343,7 +343,13 @@ non-terminals shown with the @scheme[id] form. Each
@scheme[clause-datum] is preserved.}
-@defform[(defform/none datum pre-flow ...)]{
+@defform[(defform*/subs maybe-literals [(id . datum) ...]
+ pre-flow ...)]{
+
+Like @scheme[defform/subs], but for multiple forms for @scheme[id].}
+
+
+@defform[(defform/none maybe-literal datum pre-flow ...)]{
Like @scheme[defform], but without registering a definition.}
@@ -431,6 +437,16 @@ Similar to @scheme[defform] or @scheme[defproc], but for a structure
definition.}
+@defform[(deftogether [def-expr ...] pre-flow ...)]{
+
+Combines the definitions created by the @scheme[def-expr]s into a
+single definition box. Each @scheme[def-expr] should produce a
+definition point via @scheme[defproc], @scheme[defform], etc. Each
+@scheme[def-expr] should have an empty @scheme[pre-flow]; the
+@tech{decode}d @scheme[pre-flow] sequence for the @scheme[deftogether]
+form documents the collected bindings.}
+
+
@defform/subs[(schemegrammar maybe-literals id clause-datum ...+)
([maybe-literals code:blank
(code:line #:literals (literal-id ...))])]{
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
@@ -8,20 +8,35 @@
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
-description will often start with ``Produces.'' Refer to arguments by
-name.
+description will often start with ``Produces.'' Refer to arguments and
+sub-forms by name.
-Use @schemeidfont{id} or something that ends @schemeidfont{-id} in
+Do not use the word ``argument'' to describe a sub-form in a syntactic
+form; use the term ``sub-form'' instead, reserving ``argument'' for
+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.''
+
+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
@schemeidfont{symbol}. Similarly, use @schemeidfont{expr} or something
that ends @schemeidfont{-expr} for an expression position within a
syntactic form. Use @schemeidfont{body} for a form (definition or
-expression) in an internal-definition position. Never use
+expression) in an internal-definition position. Do not use
@schemeidfont{expr} for something that isn't exactly an expression,
@scheme[id] for something that isn't exactly an identifier, etc.;
instead, use @scheme[defform/subs] to define a new non-terminal.
+Beware of using @scheme[deftogether] to define multiple variants of a
+syntactic form or procedure, because each @scheme[defform] or
+@scheme[defproc] creates a definition point, but each form or
+procedure should have a single definition point. (Scribble issues a
+warning when a binding has multiple definition points.) Instead, use
+@scheme[defproc*] or @scheme[defform*].
+
Pay attention to the difference between identifiers and meta-variables
when using @scheme[scheme], especially outside of @scheme[defproc] or
@scheme[defform]. Prefix a meta-variable with @litchar{_}; for
