scribble and doc improvements

svn: r10896

original commit: a97b4bff8a6eb38353f64606c4a42f2150b39e2a

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)]
+      (let* ([contents (super render-paragraph p part ri)]
-            [style (and (styled-paragraph? p) (styled-paragraph-style p))])
+             [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)
+                        (with-attributes-style raw-style)
-                      raw-style)])
+                        raw-style)])
-        (define (attribs)
+        (define (attribs) (style->attribs raw-style))
-          (if (with-attributes? raw-style)
-            (map (lambda (p) (list (car p) (cdr p)))
-                 (with-attributes-assoc raw-style))
-            null))
         (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)

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)
+                      (let ([finality
-                        [(pubment)
+                             (lambda ()
-                         #'((t "Refine this method with "
+                               (case (syntax-e #'mode)
-                               (scheme augment) "."))]
+                                 [(override-final public-final extend-final)
-                        [(override extend augment)
+                                  #'(" This method is final, so it cannot be overiddden.")]
-                         #'((t (case (syntax-e #'mode)
+                                 [(augment-final)
-                                 [(override) "Overrides "]
+                                  #'(" This method is final, so it cannot be augmented.")]
-                                 [(extend) "Extends "]
+                                 [else null]))])
-                                 [(augment) "Augments "])
+                        (case (syntax-e #'mode)
-                               (*xmethod/super (quote-syntax/loc cname) 'name1)
+                          [(pubment)
-                               "."))]
+                           #'((t "Refine this method with "
-                        [else null])])
+                                 (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 ()

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 ...)
+@defform/subs[#:literals (override override-final public-final 
-                    result-contract-expr-datum
+                          augment augment-final pubment extend extend-final)
-                    pre-flow ...)]{
+              (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)]{

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