From 69ee9cce11d18178e2e10ee85cbab23ac9c790fa Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 18 Dec 2007 13:52:50 +0000 Subject: [PATCH] document mz/mr command-line arguments svn: r8047 original commit: 058d8dc77eca3023f96280c0f19029f2ffe02d02 --- collects/scribble/manual.ss | 6 +++++- collects/scribblings/scribble/manual.scrbl | 20 +++++++++++++++++-- collects/scribblings/scribble/style.scrbl | 23 ++++++++++++++++++---- 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index fa4c47ea..bae3eae3 100644 --- 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 index 1ad0a1e4..7271e98c 100644 --- 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 index 1910ee9d..ca76033b 100644 --- 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