commit 133883ef2e68ba802e98448cf14c475632ec9541
parent 35ca52a88d46d787397a1d2bab791ffbe3c65395
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 24 Jul 2008 11:32:16 +0000
scribble and doc improvements
svn: r10896
original commit: a97b4bff8a6eb38353f64606c4a42f2150b39e2a
Diffstat:
4 files changed, 119 insertions(+), 33 deletions(-)
diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss
@@ -106,6 +106,12 @@
(define-serializable-struct literal-anchor (string))
+(define (style->attribs raw-style)
+ (if (with-attributes? raw-style)
+ (map (lambda (p) (list (car p) (cdr p)))
+ (with-attributes-assoc raw-style))
+ null))
+
#; ; no need for these index-local searches
#reader scribble/reader (begin ; easier to format
@@ -758,11 +764,21 @@
;; HACK: for the search, we need to be able to render a `div'
;; with an `id' attribute, `p' will probably work fine instead
;; of `div' since it's a block element. Do this for now.
- (let ([contents (super render-paragraph p part ri)]
- [style (and (styled-paragraph? p) (styled-paragraph-style p))])
+ (let* ([contents (super render-paragraph p part ri)]
+ [raw-style (and (styled-paragraph? p)
+ (flatten-style (styled-paragraph-style p)))]
+ [style (if (with-attributes? raw-style)
+ (with-attributes-style raw-style)
+ raw-style)])
(if (and (pair? style) (eq? (car style) 'div))
`((div-hack ,(cdr style) ,@contents))
- `((p ,(if style `([class ,style]) `()) ,@contents)))))
+ `((,(if (string? style) 'div 'p)
+ ,(append
+ (if (string? style)
+ `([class ,style])
+ `())
+ (style->attribs raw-style))
+ ,@contents)))))
(define/override (render-element e part ri)
(cond
@@ -828,13 +844,9 @@
(define/private (render-plain-element e part ri)
(let* ([raw-style (flatten-style (and (element? e) (element-style e)))]
[style (if (with-attributes? raw-style)
- (with-attributes-style raw-style)
- raw-style)])
- (define (attribs)
- (if (with-attributes? raw-style)
- (map (lambda (p) (list (car p) (cdr p)))
- (with-attributes-assoc raw-style))
- null))
+ (with-attributes-style raw-style)
+ raw-style)])
+ (define (attribs) (style->attribs raw-style))
(define (render* [x 'span])
;; x can be a tag name, or a list of attributes, or a tag followed by
;; a list of attributes (internal use: no error checking!)
@@ -929,7 +941,10 @@
[else (render*)])))
(define/override (render-table t part ri need-inline?)
- (define t-style (table-style t))
+ (define raw-style (flatten-style (table-style t)))
+ (define t-style (if (with-attributes? raw-style)
+ (with-attributes-style raw-style)
+ raw-style))
(define t-style-get (if (and (pair? t-style) (list? t-style))
(lambda (k) (assoc k t-style))
(lambda (k) #f)))
@@ -981,7 +996,8 @@
[else null])
,@(let ([a (t-style-get 'style)])
(if (and a (string? (cadr a))) `([class ,(cadr a)]) null))
- ,@(if (string? t-style) `([class ,t-style]) null))
+ ,@(if (string? t-style) `([class ,t-style]) null)
+ ,@(style->attribs raw-style))
,@(map make-row
(table-flowss t)
(cdr (or (t-style-get 'row-styles)
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
@@ -2322,18 +2322,27 @@
(with-syntax ([cname (syntax-parameter-value #'current-class)]
[name1 (car (syntax->list #'(name ...)))])
(with-syntax ([(extra ...)
- (case (syntax-e #'mode)
- [(pubment)
- #'((t "Refine this method with "
- (scheme augment) "."))]
- [(override extend augment)
- #'((t (case (syntax-e #'mode)
- [(override) "Overrides "]
- [(extend) "Extends "]
- [(augment) "Augments "])
- (*xmethod/super (quote-syntax/loc cname) 'name1)
- "."))]
- [else null])])
+ (let ([finality
+ (lambda ()
+ (case (syntax-e #'mode)
+ [(override-final public-final extend-final)
+ #'(" This method is final, so it cannot be overiddden.")]
+ [(augment-final)
+ #'(" This method is final, so it cannot be augmented.")]
+ [else null]))])
+ (case (syntax-e #'mode)
+ [(pubment)
+ #'((t "Refine this method with "
+ (scheme augment) "."))]
+ [(override override-final extend augment)
+ #`((t (case (syntax-e #'mode)
+ [(override override-final) "Overrides "]
+ [(extend extend-final) "Extends "]
+ [(augment augment-final) "Augments "])
+ (*xmethod/super (quote-syntax/loc cname) 'name1)
+ "."
+ #,@(finality)))]
+ [else null]))])
#'(make-meth '(name ...)
'mode
(lambda ()
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
@@ -627,19 +627,39 @@ Like @scheme[defconstructor], but the constructor is
annotated to indicate that additional initialization arguments are
accepted and propagated to the superclass.}
-@defform[(defmethod (id arg-spec ...)
- result-contract-expr-datum
- pre-flow ...)]{
+@defform/subs[#:literals (override override-final public-final
+ augment augment-final pubment extend extend-final)
+ (defmethod maybe-mode (id arg-spec ...)
+ result-contract-expr-datum
+ pre-flow ...)
+ ([maybe-mode code:blank
+ (code:line #:mode override)
+ (code:line #:mode override-final)
+ (code:line #:mode public-final)
+ (code:line #:mode augment)
+ (code:line #:mode augment-final)
+ (code:line #:mode pubment)
+ (code:line #:mode extend)
+ (code:line #:mode extend-final)])]{
Like @scheme[defproc], but for a method within a @scheme[defclass] or
-@scheme[definterface] body.}
+@scheme[definterface] body.
-@defform[(defmethod* ([(id arg-spec ...)
+The @scheme[maybe-mode] specifies whether the method overrides a
+method from a superclass, and so on. (For these purposes, use
+@scheme[#:mode override] when refining a method of an implemented
+interface.) The @scheme[extend] mode is like @scheme[override], but
+the description of the method should describe only extensions to the
+superclass implementation.}
+
+@defform[(defmethod* maybe-mode
+ ([(id arg-spec ...)
result-contract-expr-datum] ...)
pre-flow ...)]{
Like @scheme[defproc*], but for a method within a @scheme[defclass] or
-@scheme[definterface] body.}
+@scheme[definterface] body. The @scheme[maybe-mode] specification is as in
+@scheme[defmethod].}
@defform[(method class/intf-id method-id)]{
diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl
@@ -331,7 +331,9 @@ A @techlink{paragraph} has a list of @tech{elements}.
@defstruct[(styled-paragraph paragraph) ([style any/c])]{
The @scheme[style] is normally a string that corresponds to a CSS
-class for HTML output.
+class for HTML output, in which case a @tt{<div>} block is generated
+instead of a @tt{<p>} block. A base style can also be a
+@scheme[with-attributes] instance to add arbitrary HTML attributes.
}
@@ -344,7 +346,43 @@ the table can span multiple columns by using @scheme['cont] instead of
a flow in the following columns (i.e., for all but the first in a set
of cells that contain a single flow).
-}
+The @scheme[style] can be any of the following:
+
+@itemize[
+
+ @item{A string that corresponds to a CSS class for
+ HTML output.}
+
+ @item{@scheme['boxed] to render as a definition.}
+
+ @item{@scheme['centered] to render centered horizontally.}
+
+ @item{@scheme['at-left] to render left-aligned (HTML only).}
+
+ @item{@scheme['at-right] to render right-aligned (HTML only).}
+
+ @item{An association list with the following optional mappings:
+
+ @itemize[
+
+ @item{@scheme['style] to a string for a CSS class for HTML output.}
+
+ @item{@scheme['row-styles] to a list of association lists,
+ one for each row in the table. Each of these nested
+ association lists maps @scheme['alignment] and
+ @scheme['valignment] to a list of symbols an
+ @scheme[#f]s, one for each column. The symbols in an
+ @scheme['alignment] list can be @scheme['left],
+ @scheme['right], or @scheme['center]. The symbols in a
+ @scheme['valignment] list can be @scheme['top],
+ @scheme['baseline], or @scheme['bottom].}
+
+ ]}
+
+ @item{an instance of @scheme[with-attributes], which combines a base
+ style with a set of additional HTML attributes.}
+
+]}
@defstruct[itemization ([flows (listof flow?)])]{
@@ -565,7 +603,10 @@ saving collected info), it is reduced to a @scheme[element] instance.
[assoc (listof (cons/c symbol? string?))])]{
Used for an @scheme[element]'s style to combine a base style with
-arbitrary HTML attributes.}
+arbitrary HTML attributes. When the @scheme[style] field is itself an
+instance of @scheme[with-attributes], its content is automatically
+flattened into the enclosing @scheme[with-attributes] when it is used
+(when, e.g., rendering an @tech{element} or a styled @tech{paragraph}).}
@defstruct[collected-info ([number (listof (or/c false/c integer?))]
