From a16a3fbfbafce60e8cdc6d0259a6fdf674b042ac Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 5 Sep 2007 14:18:44 +0000 Subject: [PATCH] save define-class-doc approach before trying to get rid of a lyer of bindings svn: r7281 original commit: 7e085ae75f187917ac4a121da626b23ca2fa8d2f --- collects/scribble/latex-render.ss | 2 +- collects/scribble/manual.ss | 62 ++++++++++++++++---- collects/scribblings/scribble/manual.scrbl | 56 +++++++++++++++++- collects/scribblings/scribble/renderer.scrbl | 5 +- 4 files changed, 109 insertions(+), 16 deletions(-) diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss index 57dcc9bc..db64784a 100644 --- a/collects/scribble/latex-render.ss +++ b/collects/scribble/latex-render.ss @@ -159,7 +159,7 @@ [(italic) (wrap e "textit" #f)] [(bold) (wrap e "textbf" #f)] [(tt) (wrap e "mytexttt" #t)] - [(nobreak) (super render-element e part ri)] + [(no-break) (super render-element e part ri)] [(sf) (wrap e "textsf" #f)] [(subscript) (wrap e "textsub" #f)] [(superscript) (wrap e "textsuper" #f)] diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss index 29e17708..35140712 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.ss @@ -1322,7 +1322,9 @@ ;; ---------------------------------------- (provide defclass + define-class-doc definterface + define-interface-doc defconstructor defconstructor/make defconstructor*/make @@ -1332,6 +1334,7 @@ methspec methimpl this-obj + include-class-section include-class) (define-syntax-parameter current-class #f) @@ -1426,7 +1429,7 @@ ht)) ht))) - (define (*include-class decl) + (define (*include-class-section decl) (make-splice (cons (section #:style 'hidden (to-element (decl-name decl))) (map (lambda (i) @@ -1439,11 +1442,32 @@ ((decl-mk-head decl) #t) (decl-body decl)))))) + (define (*include-class decl) + (make-splice + (append + ((decl-mk-head decl) #f) + (list + (make-blockquote + "leftindent" + (flow-paragraphs + (decode-flow + (map (lambda (i) + (cond + [(constructor? i) ((constructor-def i))] + [(meth? i) + ((meth-def i) (meth-desc i))] + [else i])) + (decl-body decl))))))))) + + (define-syntax include-class-section + (syntax-rules () + [(_ id) (*include-class-section (class-doc-info id))])) + (define-syntax include-class (syntax-rules () [(_ id) (*include-class (class-doc-info id))])) - (define (*defclass stx-id super intfs whole-page?) + (define (*define-class-doc stx-id super intfs whole-page?) (let ([spacer (hspace 1)]) (make-table 'boxed @@ -1497,7 +1521,7 @@ (make-flow (list (make-paragraph (list (to-element i))))))) (cdr intfs))))))))))))) - (define-syntax defclass + (define-syntax define-class-doc (syntax-rules () [(_ name super (intf ...) body ...) (define-class-doc-info name @@ -1507,13 +1531,20 @@ (list (class-doc-info intf) ...) (lambda (whole-page?) (list - (*defclass (quote-syntax/loc name) - (quote-syntax super) - (list (quote-syntax intf) ...) - whole-page?))) + (*define-class-doc (quote-syntax/loc name) + (quote-syntax super) + (list (quote-syntax intf) ...) + whole-page?))) (list body ...))))])) - (define-syntax definterface + (define-syntax defclass + (syntax-rules () + [(_ name . rest) + (begin + (define-class-doc name . rest) + (include-class name))])) + + (define-syntax define-interface-doc (syntax-rules () [(_ name (intf ...) body ...) (define-class-doc-info name @@ -1523,12 +1554,19 @@ (list (class-doc-info intf) ...) (lambda (whole-page?) (list - (*defclass (quote-syntax/loc name) - #f - (list (quote-syntax intf) ...) - whole-page?))) + (*define-class-doc (quote-syntax/loc name) + #f + (list (quote-syntax intf) ...) + whole-page?))) (list body ...))))])) + (define-syntax definterface + (syntax-rules () + [(_ name . rest) + (begin + (define-interface-doc name . rest) + (include-class name))])) + (define-syntax (defconstructor*/* stx) (syntax-case stx () [(_ mode ((arg ...) ...) desc ...) diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index d08a066b..37e53114 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -353,7 +353,7 @@ definition.} @defform/subs[(schemegrammar maybe-literals id clause-datum ...+) ([maybe-literals code:blank (code:line #:literals (literal-id ...))])]{ - + Creates a table to define the grammar of @scheme[id]. Each identifier mentioned in a @scheme[clause-datum] is typeset as a non-terminal, except for the identifiers listed as @scheme[literal-id]s, which are @@ -365,6 +365,60 @@ typeset as with @scheme[scheme].} Like @scheme[schemegrammar], but for typesetting multiple productions at once, aligned around the @litchar{=} and @litchar{|}.} +@; ------------------------------------------------------------------------ +@section{Classes and Interfaces} + +@defform[(define-class-doc id super-id (intf-id ...) pre-flow ...)]{ + +Binds @schemeidfont{class-doc-info:}@scheme[id] to documentation for +the class @scheme[id]. If @scheme[super-id] is not @scheme[object%], +then @schemeidfont{class-doc-info:}@scheme[super-id] must be bound to +documentation for the superclass (so that links can be created to +inherited methods, etc.). Similarly, +@schemeidfont{class-doc-info:}@scheme[intf-id] must be bound to +documentation for interfaces implemented by the class. At the same +time, @scheme[id], @scheme[super-id], and the @scheme[int-id]s must +have for-label bindings that are used for hyperlinks in the usual way. + +The decoding of the @scheme[pre-flow] sequence should start with +general documentation about the class, followed by constructor +definition (see @scheme[defconstructor]), and then field and method +definitions (see @scheme[defmethod]). + +A @scheme[define-class-doc] form is a Scheme-level definition. It does +not produce documentation directly. Instead, @scheme[(include-class +id)] or @scheme[(include-class-section id)] should be used later to +produce the documentation.} + +@defform[(include-class id)]{ + +Generates inline documentation based on the information bound to +@schemeidfont{class-doc-info:}@scheme[id]. Constructor and method +specification are indented to visually group them under the class +definition.} + +@defform[(include-class-section id)]{ + +Generates documentation based on the information bound to +@schemeidfont{class-doc-info:}@scheme[id] as a new section. The +@scheme[id] is used as the section title, but the title is not +rendered in HTML output, as the definition box serves as a title. With +the expectation that the section will have its own page, constructor +and method specifications are not indented (unlike the result of +@scheme[include-class]).} + +@defform[(defclass id super-id (intf-id ...) pre-flow ...)]{ + +Combines @scheme[define-class-doc] and @scheme[include-class].} + +@defform[(defconstructor)]{ + +TBD.} + +@defform[(defmethod)]{ + +TBD.} + @; ------------------------------------------------------------------------ @section{Various String Forms} diff --git a/collects/scribblings/scribble/renderer.scrbl b/collects/scribblings/scribble/renderer.scrbl index c06088a9..2f49996c 100644 --- a/collects/scribblings/scribble/renderer.scrbl +++ b/collects/scribblings/scribble/renderer.scrbl @@ -46,6 +46,7 @@ Creates a renderer whose output goes to @scheme[dest-dir]. [dests (listof path-string?)]) collect-info?]{ +Performs the @techlink{collect pass}. } @@ -54,6 +55,7 @@ Creates a renderer whose output goes to @scheme[dest-dir]. [ci collect-info?]) resolve-info?]{ +Performs the @techlink{resolve pass}. } @@ -62,6 +64,7 @@ Creates a renderer whose output goes to @scheme[dest-dir]. [ri resolve-info?]) void?]{ +Produces the final output. } @@ -81,5 +84,3 @@ Adds the deserialized form of @scheme[v] to @scheme[ci]. } } - -@include-class[render%]