document mz/mr command-line arguments

svn: r8047

original commit: 058d8dc77eca3023f96280c0f19029f2ffe02d02

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)

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 ...))])]{

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