commit a16a3fbfbafce60e8cdc6d0259a6fdf674b042ac
parent 66cc1e65a24632559cfca1cafafa50210ddd50cb
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 5 Sep 2007 14:18:44 +0000
save define-class-doc approach before trying to get rid of a lyer of bindings
svn: r7281
original commit: 7e085ae75f187917ac4a121da626b23ca2fa8d2f
Diffstat:
4 files changed, 109 insertions(+), 16 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -366,6 +366,60 @@ 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}
@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the
diff --git 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%]
