From 929b10f1bf3ca50f6a93e45c0447b78b5b5dc190 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 8 Jan 2014 20:16:19 -0600
Subject: [PATCH] scribble: document all `scribble/manual` CSS style classes

Includes a few Scrible bug and documentation repairs.

original commit: bf3fa13bb8bce224aac3c07a05d8740791d32058
---
 .../scribblings/scribble/config.scrbl         | 116 +++++++-
 .../scribblings/scribble/demo-class.scrbl     |  23 ++
 .../scribblings/scribble/demo-manual-m1.scrbl |  10 +
 .../scribblings/scribble/demo-manual-m2.scrbl |  12 +
 .../scribblings/scribble/demo-manual-s1.scrbl |  10 +
 .../scribblings/scribble/demo-manual-s2.scrbl |  12 +
 .../scribblings/scribble/demo-manual.scrbl    | 203 +++++++++++++
 .../scribblings/scribble/info.rkt             |   8 +-
 .../scribblings/scribble/manual.scrbl         |  38 ++-
 .../scribble-lib/scribble/html-render.rkt     |  25 +-
 .../scribble/private/manual-class.rkt         | 267 ++++++++++--------
 .../scribble/private/manual-style.rkt         |   4 +-
 .../scribble-lib/scribble/racket.css          |   3 -
 .../scribble-lib/scribble/racket.rkt          |   6 +-
 14 files changed, 590 insertions(+), 147 deletions(-)
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-class.scrbl
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m1.scrbl
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m2.scrbl
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s1.scrbl
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s2.scrbl
 create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual.scrbl

diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl
index 6a9599d6..59142272 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl
@@ -7,6 +7,16 @@
 
 @(define (fake-title . str) (apply bold str))
 
+@(define (css s) (tt s))
+@(define spacer @hspace[1])
+@(define baseline (style #f '(baseline)))
+@(define-syntax-rule (css-table [name desc] ...)
+   (tabular 
+    #:style (style #f (list (table-columns (list baseline baseline baseline baseline))))
+    (list (list spacer name spacer @smaller[desc]) ...)))
+
+@; ------------------------------------------------------------
+
 @title[#:tag "config" #:style 'toc]{Extending and Configuring Scribble Output}
 
 Sometimes, Scribble's primitives and built-in styles are insufficient
@@ -269,11 +279,6 @@ functions:
 
 ]
 
-@(define (css s) (tt s))
-@(define spacer @hspace[1])
-@(define-syntax-rule (css-table [name desc] ...)
-   (tabular (list (list spacer name spacer @smaller[desc]) ...)))
-
 The style classes:
 
 @(css-table
@@ -394,6 +399,107 @@ The style classes:
   [@css{badlink} @elem{Broken cross-reference.}]
   [@css{plainlink} @elem{Hyperlink without an underline.}])
 
+In addition, the @css{SIEHidden} style class is built in to all
+Scribble HTML output to hide an element on Internet Explorer 6.
+
+@; ------------------------------------------------------------
+
+@section[#:tag "manual-css"]{Manual CSS Style Classes}
+
+The following renderings of @elem[#:style (style #f (list
+(link-resource "demo-manual.scrbl")))]{@filepath{demo-manual.scrbl}}
+demonstrate all of the CSS style classes used by
+@racketmodname[scribble/manual] forms and functions in addition to the
+@seclink["builtin-css"]{base style classes}.
+
+@itemlist[
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-manual-s1.scrbl")] shows
+       the original style in a single-page rendering without a search
+       box.}
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-manual-m1.scrbl")] shows
+       the original style in a multi-page rendering without a search
+       box.}
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-manual-s2.scrbl")] shows
+       the current manual style's adjustments in a single-page
+       rendering with a search box.}
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-manual-m2.scrbl")] shows
+       the current manual style's adjustments in a multi-page
+       rendering with a search box.}
+
+]
+
+The style classes:
+
+@(css-table
+  [@css{RktSym} @elem{Identifiers with no @racket[for-label] binding.}]
+  [@css{RktValLink} @elem{Identifier with @racket[for-label] binding to a variable definition.}]
+  [@css{RktValDef} @elem{Definition site of a variable, normally combined with @css{RktValLink}.}]
+  [@css{RktStxLink} @elem{Identifier with @racket[for-label] binding to a syntactic-form definition.}]
+  [@css{RktStxDef} @elem{Definition site of a syntactic form, normally combined with @css{RktStxLink}.}]
+  [@css{RktSymDef} @elem{Definition site of an identifier without binding (normally a mistake), combined with @css{RktSym}.}]
+  [@css{RktVar} @elem{Local variable or meta-variable.}]
+  [@css{RktRes} @elem{REPL result.}]
+  [@css{RktOut} @elem{Output written to the current output port.}]
+  [@css{RktErr} @elem{Output written to the current error port.}]
+  [@css{RktCmt} @elem{A comment in Racket code.}]
+  [@css{RktVal} @elem{A literal value in Racket code.}]
+  [@css{RktPn} @elem{Parentheses, keywords, and similar delimiters in Racket code.}]
+  [@css{RktRdr} @elem{Reader shorthands in Racket code, except for commas.}]
+  [@css{RktMeta} @elem{An unquoting comma in Racket code.}]
+  [@css{highlighted} @elem{Hilighlted code (via @racket[code:highlight] in @racket[racketblock], for example).}]
+  [@css{RktIn} @elem{Foreground for literal characters written with @racket[litchar].}]
+  [@css{RktInBG} @elem{Background for literal characters written with @racket[litchar].}]
+  [@css{RktModLink} @elem{A module name linked to the module's definition.}]
+  [@css{RktMod} @elem{A module name (normally @css{RktModLink}, instead).}]
+  [@css{RktKw} @elem{A ``keyword;'' not normally used.}]
+  [@css{RktOpt} @elem{Brackets for optional arguments (in function definitions).}]
+
+  [@spacer @spacer]
+
+  [@css{RktBlk} @elem{Wrapper for multi-linke Racket code blocks.}]
+
+  [@spacer @spacer]
+
+  [@css{defmodule} @elem{Module definition block.}]
+  [@css{RpackageSpec} @elem{Package specification within a module-definition block.}]
+
+  [@spacer @spacer]
+
+  [@css{RBoxed} @elem{Definition block; always combined with @css{boxed}.}]
+  [@css{together} @elem{Table within a @racket[together] grouping.}]
+  [@css{RBackgroundLabel} @elem{Wrapper for ``procedure,'' ``syntax,'' etc., backing in a definition box.}]
+  [@css{RBackgroundLabelInner} @elem{Wrapper within @css{RBackgroundLabel}.}]
+  [@css{RForeground} @elem{Wrapper for element to appear over a @css{RBackgroundLabel}.}]
+  [@css{prototype} @elem{Wrapper for a multi-line procedure-definition prototype.}]
+  [@css{argcontract} @elem{Wrapper for a multi-line argument contract and default value.}]
+  [@css{specgrammar} @elem{Wrapper for a grammar with a syntactic-form definition box.}]
+  [@css{inherited} @elem{Wrapper for a margin ``inherited methods'' table.}]
+  [@css{inheritedlbl} @elem{Wrapper for ``Inherited methods:'' and ``from'' labels.}]
+
+  [@spacer @spacer]
+
+  [@css{leftindent} @elem{Left-indented block, such as form @racket[specsubform].}]
+  [@css{insetpara} @elem{Inset block.}]
+
+  [@spacer @spacer]
+
+  [@css{Rfilebox} @elem{Wrapper for a file box (via @racket[filebox]),}]
+  [@css{Rfiletitle} @elem{Outer wrapper for a file box title.}]
+  [@css{Rfilename} @elem{Inner wrapper for a file box title.}]
+  [@css{Rfilecontent} @elem{Wrapper for file box content.}]
+
+  [@spacer @spacer]
+
+  [@css{SHistory} @elem{Wrapper for @racket[history] paragraphs.}]
+
+  [@spacer @spacer]
+
+  [@css{RBibliography} @elem{Wrapper for a @racket[bibliography] section.}])
+
 @; ------------------------------------------------------------
 
 @section[#:tag "builtin-latex"]{Base Latex Macros}
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-class.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-class.scrbl
new file mode 100644
index 00000000..3b81e0eb
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-class.scrbl
@@ -0,0 +1,23 @@
+#lang scribble/base
+@(require scribble/manual
+          (for-label racket/base
+                     racket/class
+                     racket/contract/base
+                     racket/draw))
+
+@(define css tt)
+
+@defclass/title[#:link-target? #f bitmap-dc% object% (dc<%>)]{
+
+In multi-page mode, this class definition gets its own page, and
+there's an ``inherited methods'' table in the margin.  The table has
+style class @css{inherited}, and the words ``inherited methods:'' and
+``from'' have style class @css{inheritedlbl}.
+
+@defmethod[#:link-target? #f (set-bitmap [bm any/c]) any]{
+
+A method example; nothing new here, but note how the defined
+identifier is not at the start of the box.}
+
+}
+
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m1.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m1.scrbl
new file mode 100644
index 00000000..05e1bf1f
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m1.scrbl
@@ -0,0 +1,10 @@
+#lang racket/base
+(require "demo-manual.scrbl"
+         scribble/core)
+
+(define renamed-doc
+  (struct-copy part doc
+               [title-content
+                (cons "M1 " (part-title-content doc))]))
+
+(provide (rename-out [renamed-doc doc]))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m2.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m2.scrbl
new file mode 100644
index 00000000..e10ae1ce
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-m2.scrbl
@@ -0,0 +1,12 @@
+#lang racket/base
+(require "demo-manual.scrbl"
+         scribble/core
+         scribble/manual)
+
+(define renamed-doc
+  (struct-copy part doc
+               [style manual-doc-style]
+               [title-content
+                (cons "M2 " (part-title-content doc))]))
+
+(provide (rename-out [renamed-doc doc]))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s1.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s1.scrbl
new file mode 100644
index 00000000..a2e2d22f
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s1.scrbl
@@ -0,0 +1,10 @@
+#lang racket/base
+(require "demo-manual.scrbl"
+         scribble/core)
+
+(define renamed-doc
+  (struct-copy part doc
+               [title-content
+                (cons "S1 " (part-title-content doc))]))
+
+(provide (rename-out [renamed-doc doc]))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s2.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s2.scrbl
new file mode 100644
index 00000000..aa3e84a0
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual-s2.scrbl
@@ -0,0 +1,12 @@
+#lang racket/base
+(require "demo-manual.scrbl"
+         scribble/core
+         scribble/manual)
+
+(define renamed-doc
+  (struct-copy part doc
+               [style manual-doc-style]
+               [title-content
+                (cons "S2 " (part-title-content doc))]))
+
+(provide (rename-out [renamed-doc doc]))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual.scrbl
new file mode 100644
index 00000000..ca89f3d5
--- /dev/null
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-manual.scrbl
@@ -0,0 +1,203 @@
+#lang scribble/base
+@(require scribble/manual
+          scribble/eval
+          (for-syntax racket/base)
+          (for-label racket/base
+                     racket/contract/base
+                     scribble/manual))
+
+@(define css tt)
+
+@(define-syntax (opt-example stx)
+  ;; A #\? 'paren-shape value triggers RktOpt:
+   #`@racket[#,(syntax-property #'(in-example) 'paren-shape '#\?)])
+
+@title{Manual All-Styles Document}
+
+@table-of-contents[]
+
+@section{Code Styles}
+
+@itemlist[
+
+ @item{@css{RktSym} (identifier without @racket[for-label] binding): 
+       @racket[unbound] or @racketidfont{example}}
+
+ @item{@css{RktValLink} (link to variable form): @racket[cons]}
+
+ @item{@css{RktValDef} (definition of variable, normally combined with @css{RktValLink}):
+       @racket[list] in 
+
+       @defproc[#:link-target? #f (list) any/c]
+       @defthing[#:link-target? #f list any/c]}
+
+ @item{@css{RktStxLink} (link to syntactic form): @racket[lambda]}
+
+ @item{@css{RktStxDef} (definition of syntactic form, normally combined with @css{RktStxLink}):
+       @racket[lambda] in
+
+       @defform[#:link-target? #f (lambda ...)]}
+
+ @item{@css{RktSymDef} (definition without binding, normally a mistake, combined with @css{RktSym}):
+       @racket[unbound-identifier] in
+
+       @defform[#:link-target? #f (unbound-identifier)]}
+
+ @item{@css{RktVar} (local variable or meta-variable): @racket[_variable] or @racketvarfont{example}}
+
+ @item{@css{RktRes} (REPL result): @racketresult['(1 2 3)] or @racketresultfont{example}}
+
+ @item{@css{RktOut} (as written to the current output port): @racketoutput{example}}
+
+ @item{@css{RktErr} (errors): @racketerror{example} or the error message in
+
+       @interaction[(+ 1 'a)]}
+
+ @item{@css{RktCmt} (comments): @racketcommentfont{example} or
+
+       @racketblock[(code:comment "comment")]}
+
+ @item{@css{RktVal} (values): @racket['(1 2 3)] or @racketvalfont{example}}
+
+ @item{@css{highlighted} (highlight via background): @racket[(not-this (code:hilite example) nor-this)]}
+
+ @item{@css{RktIn} on a @css{RktInBG}: @litchar{example}}
+
+ @item{@css{RktPn} (parentheses, etc.): @racket[([{}])] or @racketparenfont{example}}
+
+ @item{@css{RktRdr} (reader shorthands): non-parentheses in @racket[(#`() ,@())]}
+
+ @item{@css{RktMeta} (the @racket[unquote] comma):
+       @racket[,1] or @racketmetafont{example} or ``#reader'' below.
+
+       @defmodule[@schemeidfont{module} #:module-paths (racket/base) #:reader #:no-declare #:link-target? #f]}
+
+ @item{@css{RktMod} (module name; normally @css{RktModLink} instead): @racketmodfont{example}}
+
+ @item{@css{RktModLink} (a linked module reference): @racketmodname[racket/base]}
+
+ @item{@css{RktOpt} (option-argument brackets): brackets in @opt-example[]}
+
+ @item{@css{RktKw} (not normally used): @racketkeywordfont{example}}
+
+]
+
+The @css{RktBlk} style class is used for a table of multiple lines (more
+than 1) of Racket code:
+
+@racketblock[
+ (define x (+ 1 2))
+ (+ x 3)
+]
+
+@section{Definition Blocks}
+
+@defmodule[racket/base #:link-target? #f]
+
+The module-declaration box above is in a @css{defmodule} table. The
+package-specification part is in an @css{RpackageSpec} wrapper.
+
+The definitions below are marked so that they are not link targets. If
+they were link targets, the table-of-contents panel on the left would
+have entries for them.
+
+@defproc[#:link-target? #f (cons [really-long-name-for-the-first-argument
+                                  any/c]
+                                 [really-long-name-for-the-second-argument
+                                  (or/c any/c
+                                        any/c)])
+         pair?]{
+
+This definition box starts with a @css{SVInsetFlow} wrapper, which is a
+@racketmodname[scribble/base] style class for the
+@racket['vertical-inset] style name on a block; it should give the
+block suitable vertical space before and after.
+
+The next layer is a @css{boxed} plus @css{RBoxed} table. The @css{boxed}
+style class is from @racketmodname[scribble/base] and the
+@racket['boxed] style name on a table. The @css{RBoxed} style class is
+from the @racket[scribble/manual] layer. Both @css{boxed} and @css{RBoxed}
+are used for all definition boxes by @racket[scribble/manual] forms.
+
+The initial content of the table includes a @css{SubFlow} (a
+@racket[scribble/base] style class for non-indented flow) to combine
+blocks for the background label with the first line of the table. The
+background label ``procedure'' has an @css{RBackgroundLabel} outer
+wrapper, which makes the label float right. (The wrapper also has the
+@css{SIEHidden} style class, which built-in for all Scribble HTML output
+and makes the label hidden on Internet Explorer 6 and earlier.)  The
+background label has an @css{RBackgroundLabelInner} inner wrapper, which
+makes the label suitably faint. The content part of the first line is
+wrapped in @css{RForeground}, which ensures that it is in front of the
+background label.
+
+In a procedure definition box:
+
+@itemlist[
+
+ @item{When the initial ``prototype'' call in the definition box spans
+       multiple lines, the table that contains the call has the
+       @css{prototype} style class in addition to @css{RForeground}.}
+
+ @item{When the contract or default value for an argument spans
+       multiple lines, then the contract, the ``='' for a value (if
+       any), and value (if any) are wrapped in an table with the
+       @css{argcontract} style class.}
+
+]
+
+Finally, the definition box and all of the associated explanation text
+are wrapped in @css{SIntrapara} blocks and grouped into a single
+@tt{<p>}.}
+
+@defform[#:link-target? #f 
+         (lambda ...)
+         #:grammar ([example good
+                             bad])]
+
+When a syntactic-from specification has a grammar, the grammar is in a
+table with the @css{specgrammar} style class.
+
+Since no explanation flow is attached to the above @racket[defform] use,
+there's no @css{SIntrapara} block around the table (just a @tt{<p>}).
+
+@deftogether[(
+@defproc[#:link-target? #f (cons [a any/c] [d any/c]) pair?]
+@defform[#:link-target? #f (lambda ...)]
+)]{
+
+Putting definitions together with @racket[deftogether] converts the
+@css{RBoxed} and @css{boxed} tables that would be generated for the
+individual definitions into tables with the @css{together} style
+class. The tables are then combined as rows in a new table with the
+@css{RBoxed} and @css{boxed}  style classes.}
+
+A @racket[defsubform], @racket[specsubform], etc., such as
+
+@specsubform[(lambda ...)]
+
+is indented though a wrapper with a @css{leftindent} style class.
+
+@include-section["demo-class.scrbl"]
+
+@section{Miscellaneous}
+
+In @racket[filebox] rendering,
+
+@(filebox "example.rkt" "This is a file box")
+
+a @css{Rfilebox} wrapper surrounds the file name in a @css{Rfiletitle}
+outer wrapper and an @css{Rfilename} inner wrapper, plus the file
+content in an @css{Rfilecontent} wrapper.
+
+@inset-flow{The @racket[inset-flow] form generates a
+@racket[nested-flow] with style class @css{insetpara}.}
+
+@history[#:changed "1.0" @elem{History paragraphs have the @css{SHistory} style class.}]
+
+@section{Bibliography}
+
+The bibliography table for the citation @cite["Example"] as the
+@css{RBibliography} style class.
+
+@bibliography[(bib-entry #:key "Example" #:title "Example bibliography entry")]
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
index 8e067076..e8aa9ab8 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
@@ -1,7 +1,13 @@
 #lang info
 
 (define scribblings '(("scribble.scrbl" (multi-page) (racket-core -24))
+
                       ("demo-s1.scrbl" (keep-style no-search) (omit-start))
                       ("demo-m1.scrbl" (multi-page keep-style no-search) (omit-start))
                       ("demo-s2.scrbl" (keep-style) (omit-start))
-                      ("demo-m2.scrbl" (multi-page keep-style) (omit-start))))
+                      ("demo-m2.scrbl" (multi-page keep-style) (omit-start))
+
+                      ("demo-manual-s1.scrbl" (keep-style no-search) (omit-start))
+                      ("demo-manual-m1.scrbl" (multi-page keep-style no-search) (omit-start))
+                      ("demo-manual-s2.scrbl" (keep-style) (omit-start))
+                      ("demo-manual-m2.scrbl" (multi-page keep-style) (omit-start))))
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
index 15b12ffe..553f5c4c 100644
--- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
+++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
@@ -1120,6 +1120,19 @@ Like @racket[defidform], but @racket[id] (or the result of
 inline element. Use this form sparingly, because the typeset form does
 not stand out to the reader as a specification of @racket[id].}
 
+@deftogether[(
+@defform[(defsubform options form-datum
+            maybe-grammar maybe-contracts
+            pre-flow ...)]
+@defform[(defsubform* options [form-datum ...+]
+           maybe-grammar maybe-contracts
+           pre-flow ...)]
+)]{
+
+Like @racket[defform] and @racket[defform*], but with
+indenting on the left for both the specification and the
+@racket[pre-flow]s.}
+
 
 @defform[(specform maybe-literals datum maybe-grammar maybe-contracts
            pre-flow ...)]{
@@ -1411,8 +1424,10 @@ Specifies the target maximum width in characters for the output of
 @; ------------------------------------------------------------------------
 @section[#:tag "doc-classes"]{Documenting Classes and Interfaces}
 
-@defform/subs[(defclass id super (intf-id ...) pre-flow ...)
-              ([super super-id
+@defform/subs[(defclass maybe-link id super (intf-id ...) pre-flow ...)
+              ([maybe-link code:blank
+                           (code:line #:link-target? link-target?-expr)]
+               [super super-id
                       (mixin-id super)])]{
 
 Creates documentation for a class @racket[id] that is a subclass of
@@ -1428,7 +1443,7 @@ definitions (see @racket[defmethod]). In rendered form, the
 constructor and method specification are indented to visually group
 them under the class definition.}
 
-@defform[(defclass/title id super (intf-id ...) pre-flow ...)]{
+@defform[(defclass/title maybe-link id super (intf-id ...) pre-flow ...)]{
 
 Like @racket[defclass], also includes a @racket[title] declaration
 with the style @racket['hidden]. In addition, the constructor and
@@ -1489,10 +1504,12 @@ accepted and propagated to the superclass.}
 
 @defform/subs[#:literals (override override-final public-final 
                           augment augment-final pubment extend extend-final)
-              (defmethod maybe-mode (id arg-spec ...)
+              (defmethod maybe-mode maybe-link (id arg-spec ...)
                          result-contract-expr-datum
                          pre-flow ...)
-              ([maybe-mode code:blank
+              ([maybe-link code:blank
+                           (code:line #:link-target? link-target?-expr)]
+               [maybe-mode code:blank
                            (code:line #:mode override)
                            (code:line #:mode override-final)
                            (code:line #:mode public-final)
@@ -1512,7 +1529,7 @@ interface.) The @racket[extend] mode is like @racket[override], but
 the description of the method should describe only extensions to the
 superclass implementation.}
 
-@defform[(defmethod* maybe-mode
+@defform[(defmethod* maybe-mode maybe-link
                      ([(id arg-spec ...)
                        result-contract-expr-datum] ...)
                      pre-flow ...)]{
@@ -1891,6 +1908,13 @@ that is hyperlinked to an explanation.}
 @defproc[(commandline [pre-content pre-content?] ...) paragraph?]{Produces
 an inset command-line example (e.g., in typewriter font).}
 
+@defproc[(inset-flow [pre-flow pre-flow?] ...) nested-flow?]{
+
+Creates a @racket[nested-flow] with indenting on the left and right.
+
+Using @racket[nested] with the @racket['inset] style is a prefered
+alternative.}
+
 @defproc[(centerline [pre-flow pre-flow?] ...) nested-flow?]{
 
 An alias for @racket[centered] for backward compatibility.}
@@ -1920,7 +1944,7 @@ An alias for @racket[centered] for backward compatibility.}
 Typesets the @racket[pre-flow]s as the content of
 @racket[filename]. For example, the content may be inset on the page
 with @racket[filename] above it. If @racket[filename] is a string, it
-is passed to @racket{filepath} to obtain an @racket[element].}
+is passed to @racket[filepath] to obtain an @racket[element].}
 
 @defproc[(deprecated [#:what what content? "library"]
                      [replacement content?]
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/html-render.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/html-render.rkt
index 991a13ca..b779cb40 100644
--- a/pkgs/scribble-pkgs/scribble-lib/scribble/html-render.rkt
+++ b/pkgs/scribble-pkgs/scribble-lib/scribble/html-render.rkt
@@ -141,19 +141,29 @@
                 (if (< v 16) (string-append "0" s) s)))
             c))))
 
-(define (merge-styles s l)
-  ;; merge multiple 'style attributes into one
+(define (merge-styles s cls l)
+  ;; merge multiple 'style and 'class attributes into one
   (cond
-   [(null? l) (if s
-                  (list (list 'style s))
-                  null)]
+   [(null? l) (append
+               (if s
+                   (list (list 'style s))
+                   null)
+               (if cls
+                   (list (list 'class cls))
+                   null))]
    [(eq? 'style (caar l))
     (merge-styles (if s (string-append s "; " (cadar l)) (cadar l))
+                  cls
                   (cdr l))]
-   [else (cons (car l) (merge-styles s (cdr l)))]))
+   [(eq? 'class (caar l))
+    (merge-styles s
+                  (if cls (string-append cls " " (cadar l)) (cadar l))
+                  (cdr l))]
+   [else (cons (car l) (merge-styles s cls (cdr l)))]))
 
 (define (style->attribs style [extras null])
   (let ([a (merge-styles
+            #f
             #f
             (apply
              append
@@ -197,7 +207,8 @@
            (for/list ([i (in-list al)]
                       #:unless (eq? 'class (car i)))
              i))))]
-   [else (append cl al)]))
+   [else
+    (append cl al)]))
 
 (define (style->tag style)
   (for/or ([s (in-list (style-properties style))])
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-class.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-class.rkt
index d26f986c..a9358f2c 100644
--- a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-class.rkt
+++ b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-class.rkt
@@ -116,37 +116,39 @@
      (map (lambda (i) (list (to-flow i)))
           (cons (make-element "inheritedlbl" '("Inherited methods:")) inh)))))
 
-(define (make-decl-collect decl)
-  (make-part-collect-decl
-   ((id-to-target-maker (decl-name decl) #f)
-    (list "ignored")
-    (lambda (tag)
-      (make-collect-element
-       #f null
-       (lambda (ci)
-         (collect-put!
-          ci
-          `(cls/intf ,(cadr tag))
-          (make-cls/intf
-           (make-element
-            symbol-color
-            (list (make-link-element
-                   value-link-color
-                   (list (datum-intern-literal
-                          (symbol->string (syntax-e (decl-name decl)))))
-                   tag)))
-           (map id-info (decl-app-mixins decl))
-           (and (decl-super decl)
-                (not (free-label-identifier=? (quote-syntax object%)
-                                              (decl-super decl)))
-                (id-info (decl-super decl)))
-           (map id-info (decl-intfs decl))
-           (append-map (lambda (m)
-                         (let loop ([l (meth-names m)])
-                           (cond [(null? l) null]
-                                 [(memq (car l) (cdr l)) (loop (cdr l))]
-                                 [else (cons (car l) (loop (cdr l)))])))
-                       (filter meth? (decl-body decl)))))))))))
+(define (make-decl-collect decl link?)
+  (if link?
+      (make-part-collect-decl
+       ((id-to-target-maker (decl-name decl) #f)
+        (list "ignored")
+        (lambda (tag)
+          (make-collect-element
+           #f null
+           (lambda (ci)
+             (collect-put!
+              ci
+              `(cls/intf ,(cadr tag))
+              (make-cls/intf
+               (make-element
+                symbol-color
+                (list (make-link-element
+                       value-link-color
+                       (list (datum-intern-literal
+                              (symbol->string (syntax-e (decl-name decl)))))
+                       tag)))
+               (map id-info (decl-app-mixins decl))
+               (and (decl-super decl)
+                    (not (free-label-identifier=? (quote-syntax object%)
+                                                  (decl-super decl)))
+                    (id-info (decl-super decl)))
+               (map id-info (decl-intfs decl))
+               (append-map (lambda (m)
+                             (let loop ([l (meth-names m)])
+                               (cond [(null? l) null]
+                                     [(memq (car l) (cdr l)) (loop (cdr l))]
+                                     [else (cons (car l) (loop (cdr l)))])))
+                           (filter meth? (decl-body decl))))))))))
+      null))
 
 (define (build-body decl body)
   `(,@(map (lambda (i)
@@ -156,17 +158,17 @@
            body)
     ,(make-delayed-block (lambda (r d ri) (make-inherited-table r d ri decl)))))
 
-(define (*include-class/title decl)
+(define (*include-class/title decl link?)
   (make-splice
    (list* (title #:style 'hidden (to-element (decl-name decl)))
-          (make-decl-collect decl)
+          (make-decl-collect decl link?)
           (build-body decl (append ((decl-mk-head decl) #t)
                                    (decl-body decl))))))
 
-(define (*include-class decl)
+(define (*include-class decl link?)
   (make-splice
    (cons
-    (make-decl-collect decl)
+    (make-decl-collect decl link?)
     (append
      ((decl-mk-head decl) #f)
      (let-values ([(pre post)
@@ -184,7 +186,7 @@
           (flow-paragraphs
            (decode-flow (build-body decl post)))))))))))
 
-(define (*class-doc kind stx-id super intfs ranges whole-page? make-index-desc)
+(define (*class-doc kind stx-id super intfs ranges whole-page? make-index-desc link?)
   (make-table
    boxed-style
    (append
@@ -194,30 +196,32 @@
        (make-flow
         (list
          (make-omitable-paragraph
-          (list (let ([target-maker (id-to-target-maker stx-id #t)]
-                      [content (annote-exporting-library
-                                (to-element #:defn? #t stx-id))]
-                      [ref-content (to-element stx-id)])
-                  (if target-maker
-                      (target-maker
-                       content
-                       (lambda (tag)
-                         ((if whole-page?
-                              make-page-target-element
-                              (lambda (s c t)
-                                (make-toc-target2-element s c t ref-content)))
-                          #f
-                          (list
-                           (make-index-element
-                            #f content tag
-                            (list (datum-intern-literal
-                                   (symbol->string (syntax-e stx-id))))
-                            (list ref-content)
-                            (with-exporting-libraries
-                             (lambda (libs)
-                               (make-index-desc (syntax-e stx-id) libs)))))
-                          tag)))
-                      content))
+          (list (if link?
+                    (let ([target-maker (id-to-target-maker stx-id #t)]
+                          [content (annote-exporting-library
+                                    (to-element #:defn? #t stx-id))]
+                          [ref-content (to-element stx-id)])
+                      (if target-maker
+                          (target-maker
+                           content
+                           (lambda (tag)
+                             ((if whole-page?
+                                  make-page-target-element
+                                  (lambda (s c t)
+                                    (make-toc-target2-element s c t ref-content)))
+                              #f
+                              (list
+                               (make-index-element
+                                #f content tag
+                                (list (datum-intern-literal
+                                       (symbol->string (syntax-e stx-id))))
+                                (list ref-content)
+                                (with-exporting-libraries
+                                 (lambda (libs)
+                                   (make-index-desc (syntax-e stx-id) libs)))))
+                              tag)))
+                          content))
+                    (to-element stx-id))
                 spacer ":" spacer
                 (case kind
                   [(class) (racket class?)]
@@ -272,48 +276,62 @@
           [(splice? (car l)) (append (splice-run (car l)) (loop (cdr l)))]
           [else (cons (car l) (loop (cdr l)))])))
 
-(define-syntax-rule (*defclass *include-class name super (intf ...) body ...)
-  (*include-class
-   (syntax-parameterize ([current-class (quote-syntax name)])
-     (make-decl (quote-syntax/loc name)
-                (extract-super super)
-                (extract-app-mixins super)
-                (list (quote-syntax/loc intf) ...)
-                null
-                (lambda (whole-page?)
-                  (list (*class-doc 'class
-                                    (quote-syntax/loc name)
-                                    (quote-syntax/loc super)
-                                    (list (quote-syntax intf) ...)
-                                    null
-                                    whole-page?
-                                    make-class-index-desc)))
-                (flatten-splices (list body ...))))))
+(define-syntax-rule (*defclass *include-class link-target? name super (intf ...) body ...)
+  (let ([link? link-target?])
+    (*include-class
+     (syntax-parameterize ([current-class (quote-syntax name)])
+       (make-decl (quote-syntax/loc name)
+                  (extract-super super)
+                  (extract-app-mixins super)
+                  (list (quote-syntax/loc intf) ...)
+                  null
+                  (lambda (whole-page?)
+                    (list (*class-doc 'class
+                                      (quote-syntax/loc name)
+                                      (quote-syntax/loc super)
+                                      (list (quote-syntax intf) ...)
+                                      null
+                                      whole-page?
+                                      make-class-index-desc
+                                      link?)))
+                  (flatten-splices (list body ...))))
+     link?)))
 
-(define-syntax-rule (defclass name super (intf ...) body ...)
-  (*defclass *include-class name super (intf ...) body ...))
+(define-syntax defclass
+  (syntax-rules ()
+    [(_ #:link-target? link-target? name super (intf ...) body ...)
+     (*defclass *include-class link-target? name super (intf ...) body ...)]
+    [(_ name super (intf ...) body ...)
+     (defclass #:link-target? #t name super (intf ...) body ...)]))
 
-(define-syntax-rule (defclass/title name super (intf ...) body ...)
-  (*defclass *include-class/title name super (intf ...) body ...))
+(define-syntax defclass/title
+  (syntax-rules ()
+    [(_ #:link-target? link-target? name super (intf ...) body ...)
+     (*defclass *include-class/title link-target? name super (intf ...) body ...)]
+    [(_ name super (intf ...) body ...)
+     (defclass/title #:link-target? #t name super (intf ...) body ...)]))
 
 (define-syntax-rule (*definterface *include-class name (intf ...) body ...)
-  (*include-class
-   (syntax-parameterize ([current-class (quote-syntax name)])
-     (make-decl (quote-syntax/loc name)
-                #f
-                null
-                (list (quote-syntax/loc intf) ...)
-                null
-                (lambda (whole-page?)
-                  (list
-                   (*class-doc 'interface
-                               (quote-syntax/loc name)
-                               #f
-                               (list (quote-syntax intf) ...)
-                               null
-                               whole-page?
-                               make-interface-index-desc)))
-                (list body ...)))))
+  (let ([link? #t])
+    (*include-class
+     (syntax-parameterize ([current-class (quote-syntax name)])
+       (make-decl (quote-syntax/loc name)
+                  #f
+                  null
+                  (list (quote-syntax/loc intf) ...)
+                  null
+                  (lambda (whole-page?)
+                    (list
+                     (*class-doc 'interface
+                                 (quote-syntax/loc name)
+                                 #f
+                                 (list (quote-syntax intf) ...)
+                                 null
+                                 whole-page?
+                                 make-interface-index-desc
+                                 link?)))
+                  (list body ...)))
+     link?)))
 
 (define-syntax-rule (definterface name (intf ...) body ...)
   (*definterface *include-class name (intf ...) body ...))
@@ -323,23 +341,26 @@
 
 (define-syntax-rule (*defmixin *include-class name (domain ...) (range ...)
                                body ...)
-  (*include-class
-   (syntax-parameterize ([current-class (quote-syntax name)])
-     (make-decl (quote-syntax/loc name)
-                #f
-                null
-                (list (quote-syntax/loc domain) ...)
-                (list (quote-syntax/loc range) ...)
-                (lambda (whole-page?)
-                  (list
-                   (*class-doc 'mixin
-                               (quote-syntax/loc name)
-                               #f
-                               (list (quote-syntax domain) ...)
-                               (list (quote-syntax range) ...)
-                               whole-page?
-                               make-mixin-index-desc)))
-                (list body ...)))))
+  (let ([link? #t])
+    (*include-class
+     (syntax-parameterize ([current-class (quote-syntax name)])
+       (make-decl (quote-syntax/loc name)
+                  #f
+                  null
+                  (list (quote-syntax/loc domain) ...)
+                  (list (quote-syntax/loc range) ...)
+                  (lambda (whole-page?)
+                    (list
+                     (*class-doc 'mixin
+                                 (quote-syntax/loc name)
+                                 #f
+                                 (list (quote-syntax domain) ...)
+                                 (list (quote-syntax range) ...)
+                                 whole-page?
+                                 make-mixin-index-desc
+                                 link?)))
+                  (list body ...)))
+     link?)))
 
 (define-syntax-rule (defmixin name (domain ...) (range ...) body ...)
   (*defmixin *include-class name (domain ...) (range ...) body ...))
@@ -399,7 +420,7 @@
 
 (define-syntax (defmethod* stx)
   (syntax-case stx ()
-    [(_ #:mode mode ([(name arg ...) result-type] ...) desc ...)
+    [(_ #:mode mode #:link-target? link-target? ([(name arg ...) result-type] ...) desc ...)
      (with-syntax ([cname (syntax-parameter-value #'current-class)]
                    [name1 (car (syntax->list #'(name ...)))])
        (with-syntax ([(extra ...)
@@ -427,7 +448,7 @@
          #'(make-meth '(name ...)
                       'mode
                       (lambda ()
-                        (defproc* #:mode send #:within cname
+                        (defproc* #:link-target? link-target? #:mode send #:within cname
                           ([(name arg ...) result-type] ...)
                           (make-splice
                            (append-map (lambda (f)
@@ -435,15 +456,23 @@
                                                [(spec? f) ((spec-def f))]
                                                [else (list f)]))
                                        (list extra ... desc ...))))))))]
+    [(_ #:mode mode ([(name arg ...) result-type] ...) desc ...)
+     #'(defmethod* #:mode mode #:link-target? #t ([(name arg ...) result-type] ...) desc ...)]
+    [(_ #:link-target? link-target? ([(name arg ...) result-type] ...) desc ...)
+     #'(defmethod* #:mode public #:link-target? link-target? ([(name arg ...) result-type] ...) desc ...)]
     [(_ ([(name arg ...) result-type] ...) desc ...)
      #'(defmethod* #:mode public ([(name arg ...) result-type] ...) desc ...)]))
 
 (define-syntax defmethod
   (syntax-rules ()
+    [(_ #:mode mode #:link-target? link-target? (name arg ...) result-type desc ...)
+     (defmethod* #:mode mode #:link-target? link-target? ([(name arg ...) result-type]) desc ...)]
     [(_ #:mode mode (name arg ...) result-type desc ...)
-     (defmethod* #:mode mode ([(name arg ...) result-type]) desc ...)]
+     (defmethod #:mode mode #:link-target? #t (name arg ...) result-type desc ...)]
+    [(_ #:link-target? link-target? (name arg ...) result-type desc ...)
+     (defmethod #:mode public #:link-target? link-target? (name arg ...) result-type desc ...)]
     [(_ (name arg ...) result-type desc ...)
-     (defmethod #:mode public (name arg ...) result-type desc ...)]))
+     (defmethod #:mode public #:link-target? #t (name arg ...) result-type desc ...)]))
 
 (define-syntax-rule (methimpl body ...)
   (make-impl (lambda () (list (italic "Default implementation:") " " body ...))))
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt
index 63b48f40..edd46533 100644
--- a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt
+++ b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-style.rkt
@@ -5,7 +5,7 @@
          (only-in "../basic.rkt" aux-elem itemize)
          "../scheme.rkt"
          (only-in "../core.rkt" make-style plain
-                  make-nested-flow box-mode box-mode*
+                  make-nested-flow nested-flow? box-mode box-mode*
                   [element? core:element?])
          "manual-utils.rkt"
          "on-demand.rkt"
@@ -56,7 +56,7 @@
  [PLaneT element?]
  [hash-lang (-> element?)]
  [etc element?]
- [inset-flow (() () #:rest (listof pre-content?) . ->* . any/c)] ; XXX no docs and bad return contract
+ [inset-flow (() () #:rest (listof pre-content?) . ->* . nested-flow?)]
  [litchar (() () #:rest (listof string?) . ->* . element?)]
  [t (() () #:rest (listof pre-content?) . ->* . paragraph?)]
  [commandline (() () #:rest (listof pre-content?) . ->* . paragraph?)]
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css
index 47989add..b44fef59 100644
--- a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css
+++ b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css
@@ -144,9 +144,6 @@
 .prototype td {
   vertical-align: text-top;
 }
-.longprototype td {
-  vertical-align: bottom;
-}
 
 .RktBlk {
   white-space: inherit;
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.rkt
index f19a00c0..55116480 100644
--- a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.rkt
+++ b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.rkt
@@ -389,7 +389,7 @@
             (let ([new-line? (and l (l . > . line))])
               (when new-line?
                 (for ([i (in-range (- l line))])
-                  (out "\n" no-color))
+                  (out "\n" #f))
                 (set! line l)
                 (set! col-map next-col-map)
                 (set! next-col-map (make-hash))
@@ -629,7 +629,7 @@
                          symbol-color)
                     (unless (and (struct-proxy? (syntax-e c))
                                  (null? (struct-proxy-content (syntax-e c))))
-                      (out " " no-color))))
+                      (out " " #f))))
                 (when (vector? (syntax-e c))
                   (unless (and expr? (zero? quote-depth))
                     (let ([vec (syntax-e c)])
@@ -738,7 +738,7 @@
                   (begin
                     (out "(" paren-color)
                     (out "box" symbol-color)
-                    (out " " no-color)
+                    (out " " #f)
                     (set! src-col (+ src-col 5)))
                   (begin
                     (out "#&" value-color)