From 133883ef2e68ba802e98448cf14c475632ec9541 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 24 Jul 2008 11:32:16 +0000 Subject: [PATCH] scribble and doc improvements svn: r10896 original commit: a97b4bff8a6eb38353f64606c4a42f2150b39e2a --- collects/scribble/html-render.ss | 40 ++++++++++++------ collects/scribble/manual.ss | 33 +++++++++------ collects/scribblings/scribble/manual.scrbl | 32 ++++++++++++--- collects/scribblings/scribble/struct.scrbl | 47 ++++++++++++++++++++-- 4 files changed, 119 insertions(+), 33 deletions(-) diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index 7a84aa8c..b2308ee6 100644 --- 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 index ca96fe74..fea3bf78 100644 --- 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 index 1231493a..9fe94818 100644 --- 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 index 6a83cb43..ef77a8cd 100644 --- 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{
} block is generated +instead of a @tt{

} 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?))]