From a97b4bff8a6eb38353f64606c4a42f2150b39e2a 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 --- collects/scribble/html-render.ss | 40 ++++++++++++------ collects/scribble/manual.ss | 33 +++++++++------ collects/scribblings/framework/frame.scrbl | 2 +- collects/scribblings/gui/frame-class.scrbl | 6 +-- collects/scribblings/reference/class.scrbl | 12 +++--- collects/scribblings/scribble/manual.scrbl | 32 ++++++++++++--- collects/scribblings/scribble/struct.scrbl | 47 ++++++++++++++++++++-- doc/release-notes/mred/HISTORY.txt | 8 ++++ 8 files changed, 137 insertions(+), 43 deletions(-) diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index 7a84aa8cc0..b2308ee64d 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 ca96fe7461..fea3bf78c6 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/framework/frame.scrbl b/collects/scribblings/framework/frame.scrbl index f585ca2957..0c8017fdaa 100644 --- a/collects/scribblings/framework/frame.scrbl +++ b/collects/scribblings/framework/frame.scrbl @@ -1030,7 +1030,7 @@ } @defmixin[frame:searchable-text-mixin (frame:text<%> frame:searchable<%>) (frame:searchable-text<%>)]{ - @defmethod*[#:mode override (((get-text-to-search) (instanceof text%)))]{ + @defmethod*[#:mode override-final (((get-text-to-search) (instanceof text%)))]{ Returns the result of @method[frame:editor<%> get-editor]. diff --git a/collects/scribblings/gui/frame-class.scrbl b/collects/scribblings/gui/frame-class.scrbl index 64e085e2fd..421afeb3fb 100644 --- a/collects/scribblings/gui/frame-class.scrbl +++ b/collects/scribblings/gui/frame-class.scrbl @@ -250,9 +250,9 @@ If the event does not correspond to a complete shortcut combination, Returns the result of @schemeblock[ -(or (send this (:: frame% on-menu-char) event) - (send this (:: top-level-window<%> on-system-menu-char) event) - (send this (:: top-level-window<%> on-traverse-char) event)) +(or (send this #, @method[frame% on-menu-char] event) + (send this #, @method[top-level-window<%> on-system-menu-char] event) + (send this #, @method[top-level-window<%> on-traverse-char] event)) ] } diff --git a/collects/scribblings/reference/class.scrbl b/collects/scribblings/reference/class.scrbl index c56c392058..a5bcefae97 100644 --- a/collects/scribblings/reference/class.scrbl +++ b/collects/scribblings/reference/class.scrbl @@ -444,17 +444,17 @@ The values bound to initialization variables are } If an initialization argument is not provided for an initialization -variable that has an associated @scheme[default-value-expr], then the -@scheme[default-value-expr] expression is evaluated to obtain a value -for the variable. A @scheme[default-value-expr] is only evaluated when +variable that has an associated @scheme[_default-value-expr], then the +@scheme[_default-value-expr] expression is evaluated to obtain a value +for the variable. A @scheme[_default-value-expr] is only evaluated when an argument is not provided for its variable. The environment of -@scheme[default-value-expr] includes all of the initialization +@scheme[_default-value-expr] includes all of the initialization variables, all of the fields, and all of the methods of the class. If -multiple @scheme[default-value-expr]s are evaluated, they are +multiple @scheme[_default-value-expr]s are evaluated, they are evaluated from left to right. Object creation and field initialization are described in detail in @secref["objcreation"]. -If an initialization variable has no @scheme[default-value-expr], then +If an initialization variable has no @scheme[_default-value-expr], then the object creation or superclass initialization call must supply an argument for the variable, otherwise the @exnraise[exn:fail:object]. diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 1231493a2a..9fe9481834 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 6a83cb4316..ef77a8cd66 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?))] diff --git a/doc/release-notes/mred/HISTORY.txt b/doc/release-notes/mred/HISTORY.txt index 7f724b4bfa..2da0e7b993 100644 --- a/doc/release-notes/mred/HISTORY.txt +++ b/doc/release-notes/mred/HISTORY.txt @@ -1,3 +1,11 @@ +Version 4.1 + +Added auto-resize init argument and method to message% +Added scroll-editor-to method to editor<%> +Added on-reflow method to text% + +---------------------------------------------------------------------- + Version 4.0, June 2008 Mac OS X and Windows: adjusted window refresh to draw only