commit dae3560a767a8d5efdb5c388d8c223d227f81763
parent cf3e0ef3eb7f80bb19d3ee8e3a0d56b08439ed27
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 8 Jan 2014 07:34:15 -0700
scribble: document all `scribble/base` CSS style classes
A demo document (linked from the Scribble manual) demonstrates how
to trigger each style class and what it looks like with the default
and manual styles.
original commit: 5e0182029fea2d79e22d515305654a79a881e6d3
Diffstat:
8 files changed, 532 insertions(+), 4 deletions(-)
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl
@@ -7,7 +7,7 @@
@(define (fake-title . str) (apply bold str))
-@title[#:tag "config"]{Extending and Configuring Scribble Output}
+@title[#:tag "config" #:style 'toc]{Extending and Configuring Scribble Output}
Sometimes, Scribble's primitives and built-in styles are insufficient
to produce the output that you need. The cases in which you need to
@@ -33,6 +33,8 @@ extend or configure Scribble fall into two groups:
]
+@local-table-of-contents[]
+
@; ------------------------------------------------------------
@section[#:tag "extra-style"
@@ -240,7 +242,161 @@ it does not already have such a property added through the
@; ------------------------------------------------------------
-@section[#:tag "builtin-latex"]{Predefined Latex Macros}
+@section[#:tag "builtin-css"]{Base CSS Style Classes}
+
+The following renderings of @elem[#:style (style #f (list
+(link-resource "demo.scrbl")))]{@filepath{demo.scrbl}} demonstrate all
+of the CSS style classes used by @racketmodname[scribble/base] forms and
+functions:
+
+@itemlist[
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-s1.scrbl")] shows
+ the default style in a single-page rendering without a search
+ box.}
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-m1.scrbl")] shows
+ the default style in a multi-page rendering without a search
+ box.}
+
+ @item{@other-doc['(lib "scribblings/scribble/demo-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-m2.scrbl")] shows
+ the current manual style's adjustments in a multi-page
+ rendering with a search box.}
+
+]
+
+@(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
+ [@css{maincolumn} @elem{Outer wrapper for all content in the main column.}]
+ [@css{main} @elem{Inner wrapper for all content in the main column, including navigation bars.}]
+
+ [@spacer @spacer]
+
+ [@css{refpara} @elem{Outer wrapper for right-hand @racket[margin-note] notes.}]
+ [@css{refparaleft} @elem{Outer wrapper for left-hand @racket[margin-note] notes.}]
+ [@css{refelem} @elem{Outer wrapper for right @racket[margin-note*] notes.}]
+ [@css{refelemleft} @elem{Outer wrapper for left-hand @racket[margin-note*] notes.}]
+ [@css{refcolumn} @elem{Middle wrapper for right-hand @racket[margin-note] and @racket[margin-note*] notes.}]
+ [@css{refcolumnleft} @elem{Middle wrapper for left-hand @racket[margin-note] and @racket[margin-note*] notes.}]
+ [@css{refcontent} @elem{Inner wrapper for @racket[margin-note] and @racket[margin-note*] notes.}]
+
+ [@spacer @spacer]
+
+ [@css{tocset} @elem{Groups table-of-contents panels: main and ``on this page.''}]
+
+ [@spacer @spacer]
+
+ [@css{tocview} @elem{Wraps the main (multi-page mode) or only (single-page mode) table-of-contents panel.}]
+ [@css{tocviewlist} @elem{A hierarchical layer of content in a main table-of-contents panel.}]
+ [@css{tocviewlisttopspace} @elem{With @css{tocviewlist} for the first layer.}]
+ [@css{tocviewtoggle} @elem{The always-visible name of a layer.}]
+ [@css{tocviewtitle} @elem{With @css{tocviewtoggle} for the first layer.}]
+ [@css{tocviewsublist} @elem{An item in a layer that has multiple items and more items before and after.}]
+ [@css{tocviewsublistonly} @elem{An item in a single-item layer.}]
+ [@css{tocviewsublisttop} @elem{The first item in a multi-item layer.}]
+ [@css{tocviewsublistbottom} @elem{The last item in a multi-item layer.}]
+ [@css{tocviewlink} @elem{Inner wrapper for an item in a layer when linked to a different page.}]
+ [@css{tocviewselflink} @elem{Inner wrapper for every item in a layer when linked to the same page.}]
+
+ [@spacer @spacer]
+
+ [@css{tocsub} @elem{Wraps the ``on this page'' (multi-page mode only) table-of-contents panel.}]
+ [@css{tocsubtitle} @elem{Wraps the words ``on this page''.}]
+ [@css{tocsublist} @elem{Inner table for the ``on this page'' panel.}]
+ [@css{tocsublinknumber} @elem{Number for an entry in an ``on this page'' panel.}]
+ [@css{tocsubseclink} @elem{Title for a @emph{section} entry in an ``on this page'' panel.}]
+ [@css{tocsubnonseclink} @elem{Title for a @emph{non-section} entry in an ``on this page'' panel
+ that has some section links.}]
+ [@css{tocsublink} @elem{Title for a @emph{non-section} entry in an ``on this page'' panel
+ that has no section links.}]
+
+ [@css{toctoplink} @elem{Top-level entry in an inline (not the panel) table of contents.}]
+ [@css{toclink} @elem{Nested entry in an inline (not the panel) table of contents.}]
+
+ [@spacer @spacer]
+
+ [@css{versionbox} @elem{Outer wrapper for version}]
+ [@css{version} @elem{Inner wrapper for version in the case of search box and/or navigation.}]
+ [@css{versionNoNav} @elem{Inner wrapper for version in the acse of no search box and navigation.}]
+
+ [@spacer @spacer]
+
+ [@css{SAuthorListBox} @elem{Outer wrapper for the author list.}]
+ [@css{SAuthorList} @elem{Inner wrapper for the author list.}]
+ [@css{author} @elem{Wrapper for an individual author.}]
+
+ [@spacer @spacer]
+
+ [@css{navsettop} @elem{Wraps the top navigation bar (in multi-page mode or when a search bar is present).}]
+ [@css{navsetbottom} @elem{Wraps the bottom navigation bar (in multi-page mode or when a search bar is present).}]
+ [@css{navleft} @elem{Wraps left-side elements within a navigation bar.}]
+ [@css{navright} @elem{Wraps right-side elements within a navigation bar.}]
+ [@css{nonavigation} @elem{Disabled lins within a navigation bar.}]
+ [@css{searchform} @elem{Outer wrapper for a search box within the top navigation bar.}]
+ [@css{searchbox} @elem{Inner wrapper for a search box within the top navigation bar.}]
+
+ [@spacer @spacer]
+
+ [@css{SSubSubSubSection} @elem{Deeply nested subsection (below @tt{<h5>}).}]
+
+ [@spacer @spacer]
+
+ [@css{SIntrapara} @elem{Used with @tt{<div>} instead of @tt{<p>} for a paragraph
+ within a @racket[compound-paragraph].}]
+
+ [@spacer @spacer]
+
+ [@css{SubFlow} @elem{For a @racket[nested-flow] with no style name: no inset.}]
+ [@css{SCodeFlow} @elem{For a @racket[nested-flow] with the @racket['code-inset] style name:
+ inset suitable for code.}]
+ [@css{SVInsetFlow} @elem{For a @racket[nested-flow] with the @racket['vertical-inset] style name:
+ add space before and after suitable for code.}]
+ [@css{SCentered} @elem{For a @racket[nested-flow] created by @racket[centered]: horizontally
+ centered.}]
+
+ [@spacer @spacer]
+
+ [@css{boxed} @elem{For a @racket[table] with the @racket['boxed] style name: as a definition box.}]
+
+ [@spacer @spacer]
+
+ [@css{compact} @elem{For an @racket[itemlist] with the @racket['compact] style name.}]
+
+ [@spacer @spacer]
+
+ [@css{techoutside} @elem{Outer wrapper for a technical-term reference.}]
+ [@css{techinside} @elem{Inner wrapper for a technical-term reference.}]
+
+ [@spacer @spacer]
+
+ [@css{indexlink} @elem{For an entry in the index.}]
+
+ [@spacer @spacer]
+
+ [@css{stt} @elem{Fixed-width text.}]
+ [@css{sroman} @elem{Serif text.}]
+ [@css{ssanserif} @elem{Sans serif text.}]
+ [@css{slant} @elem{Oblique (as opposed to italic) text.}]
+ [@css{Smaller} @elem{Smaller text (as created by @racket[smaller]).}]
+ [@css{Larger} @elem{Smaller text (as created by @racket[larger]).}]
+ [@css{hspace} @elem{For whitespace produced by @racket[hspace].}]
+ [@css{nobreak} @elem{Disable link breaks.}]
+ [@css{badlink} @elem{Broken cross-reference.}]
+ [@css{plainlink} @elem{Hyperlink without an underline.}])
+
+@; ------------------------------------------------------------
+
+@section[#:tag "builtin-latex"]{Base Latex Macros}
The @filepath{scribble.tex} Latex configuration includes several
macros and environments that you can redefine to adjust the output
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl
@@ -570,7 +570,10 @@ recognized:
@itemize[
- @item{@racket['boxed] --- Renders as a definition.}
+ @item{@racket['boxed] --- Renders as a definition.
+ This style name is not intended for use on a table that is
+ nested within a @racket['boxed] table; nested uses may look
+ right for some renders of the style but not others.}
@item{@racket['centered] --- Centers HTML output horizontally.}
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-m1.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-m1.scrbl
@@ -0,0 +1,10 @@
+#lang racket/base
+(require "demo.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-m2.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-m2.scrbl
@@ -0,0 +1,12 @@
+#lang racket/base
+(require "demo.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-s1.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-s1.scrbl
@@ -0,0 +1,10 @@
+#lang racket/base
+(require "demo.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-s2.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-s2.scrbl
@@ -0,0 +1,12 @@
+#lang racket/base
+(require "demo.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.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo.scrbl
@@ -0,0 +1,321 @@
+#lang scribble/base
+@(require scribble/core
+ scribble/manual)
+
+@title[#:tag "top" #:version "1.0" #:style 'toc-hidden]{All-Styles Document, Title in ``H2''}
+
+@author["Jack" "Jill"]
+
+All of this content is within ``maincolumn'', then ``main''.
+
+@"\U2192" The version on the top left of this page is in
+``versionbox'' and then either span ``versionNoNav'' (no navigation
+bar, as for single-page rendering) or ``version'' (with navigation
+bar, as for multi-page rendering).
+
+@"\U2192" The author on the top left of this page is in
+``SAuthorListBox'', then ``SAuthorList'', and then a span ``author'',
+where @tt{<br/>} separates multiple authors.
+
+@"\U2190" The table-of-contents panels are both in a table ``tocset'':
+
+@margin-note{This note is in ``refpara'', then ``refcolumn'', then
+ ``refcontent''.}
+
+@itemlist[
+
+ @item{The top panel is in ``tocview''.
+
+ The top panel can have multiple layers of the hierarchy. For a
+ single-page rendering, only one layer is present. For an
+ example of multiple layers when rendering this document to
+ multiple pages, go to @secref["deepest"].
+
+ Each layer is in a ``tocviewlist'' that also has the class
+ ``tocviewlisttopspace'' in the case of the first layer. The
+ always-visible name of a layer is in a span ``tocviewtoggle'',
+ but that span is also in a ``tocviewtitle'' in the case of the
+ first layer. Each item under the title is in a
+ ``tocviewsublist'' or a variant: ``tocviewsublistonly'' if only
+ a single item is present, ``tocviewsublistfirst'' for the first
+ item of multi, ``tocviewsublistlast'' for the last item of
+ multiple. Then, each item is in a span ``tocviewlink''.
+
+ Each section link in the panel is a span ``tocviewlink'' or a
+ span ``tocviewselflink'' if the link corresponds to the current
+ page or on the path to the current page.}
+
+ @item{A bottom panel is visible here only for a single-page
+ rendering. See its description in @secref["h3"].}
+
+]
+
+
+@margin-note[#:left? #t]{This note is in ``refparaleft'', then
+ ``refcolumnleft'', then ``refcontent''.}
+
+Table of contents uses ``toptoclink'' for the top layer, and
+``toclink'' for nested levels:
+
+@table-of-contents[]
+
+@margin-note*{This note is in ``refelem'', then ``refcolumn'', then
+ ``refcontent''.}
+@margin-note*[#:left? #t]{This note is in ``refelemleft'', then
+ ``refcolumnleft'', then ``refcontent''.}
+
+@; ======================================================================
+@section[#:tag "h3"]{Section in ``H3''}
+
+@"\U2190" For either single-page or multi-page rendering, the
+table-of-contents column here has two panels. The top panel is
+described in the @seclink["h3"]{starting prose}. For the bottom panel:
+
+@itemlist[
+
+ @item{The bottom panel is in a ``tocsub''. For a multi-page
+ rendering, the on-this-page title is in ``tocsubtitle''. The
+ rest is always in a table ``tocsublist''. For each entry, the
+ number part is in a span ``tocsublinknumber'', and the title
+ part in a span, one of the following: ``tocsubseclink'' if the
+ link represents a (sub)section, ``tocnonseclink'' if the link is
+ not a (sub)section but there are (sub)sections in the list (and
+ there is an example target in this section), or ``tocsublink''
+ if no links represent a (sub)section (see
+ @secref["all-non-sec"]).}
+
+]
+
+When a part that corresponds to a page has a @racket['no-toc] style,
+the top panel of the table-of-contents column is missing and the
+bottom panel is in a ``tocview'' instead of ``tocsub''. See
+@secref["no-toc"].
+
+Here is the target for the
+@toc-target-element[#f @elem{``tocnonseclink''} `(demo (prefixable "non-sec"))]
+link.
+
+@subsection[#:style 'toc]{Subsection in ``H4''}
+
+@local-table-of-contents[]
+
+@subsubsection[#:tag "deepest"]{Subsubsection in ``H5''}
+
+@"\U2190" This page has no on-this-page panel in a multi-page
+rendering, because there are no numbered subsections, but it has three
+levels shown in the table-of-contents panel.
+
+@subsubsub*section{``SSubSubSubSection''}
+
+
+@subsection{Second Subsection in ``H4''}
+
+
+@; ======================================================================
+@section[#:tag "no-toc" #:style 'no-toc]{Suppressed ToC Panel}
+
+In multi-page rendering, this page has no gobal table-of-contents
+panel, because it is suppressed with @racket['no-toc].
+
+@subsection{Subsection}
+
+@subsection{Another Subsection}
+
+
+@; ======================================================================
+@section[#:tag "all-non-sec"]{Non-Section On-This-Page Links}
+
+This section has only non-section targets in the on-this-page
+panel of a multi-page rendering.
+Here is the target for the
+@toc-target-element[#f @elem{``tocsublink'' 1} `(demo (prefixable "non-sec 1"))]
+link.
+Here is the target for the
+@toc-target-element[#f @elem{``tocsublink'' 2} `(demo (prefixable "non-sec 2"))]
+link.
+
+Here is the target for the @as-index{``indexlink''} link in the
+@seclink["doc-index"]{index} (where ``indexlink'' is used for the
+index entry and not here).
+
+@; ======================================================================
+@section{Element Styles}
+
+Some spans:
+
+@itemlist[
+
+ @item{@tt{``stt''}}
+
+ @item{@elem[#:style 'roman]{``sroman''}}
+
+ @item{@elem[#:style "slant"]{``slant''}}
+
+ @item{@elem[#:style 'sf]{``ssanserif''}}
+
+ @item{@smaller{``Smaller''}}
+
+ @item{@larger{``Larger''}}
+
+ @item{``hspace'' is used for forced @hspace[3] space}
+
+ @item{``url'' is used for URLs: @url{http://racket-lang.org}}
+
+ @item{@elem[#:style 'no-break]{``nobreak'', which is used to prevent
+ line breaks anywhere in the element so that the element may run too
+ far right}}
+
+ @item{@italic{italic} directly sets @tt{font-style} to @tt{italic}}
+
+ @item{@bold{bold} directly sets @tt{font-weight} to @tt{bold}}
+
+ @item{@elem[#:style 'superscript]{superscript} directly sets
+ @tt{vertical-align} to @tt{super} and @tt{font-size} to @tt{80%}.}
+
+ @item{@elem[#:style 'subscript]{subscript} directly sets
+ @tt{vertical-align} to @tt{sub} and @tt{font-size} to @tt{80%}.}
+
+]
+
+Link spans:
+
+@itemlist[
+
+ @item{@elemref[#:underline? #f '(prefixable "plain-target")]{``plainlink''}
+ hyperlink to @elemtag['(prefixable "plain-target")]{here}}
+
+ @item{@deftech{technical term} definitions are simply italicized by default}
+
+ @item{@tech{technical term} references are in ``techoutside'', then ``techinside''}
+
+]
+
+@; ======================================================================
+@section{Block Styles}
+
+@nested{This paragraph is in a ``SubFlow'' @tt{<blockquote>}.}
+
+@nested[#:style 'inset]{This paragraph is in a plain @tt{<blockquote>}.}
+
+@nested[#:style 'code-inset]{This paragraph is in a ``SCodeFlow''
+@tt{<blockquote>}.}
+
+@nested[#:style 'vertical-inset]{This paragraph is in a
+``SVInsetFlow'' @tt{<blockquote>}. This style is useful when space is
+not normally included between blocks.}
+
+@centered{This paragraph is in a ``SCentered'' @tt{<blockquote>}.}
+
+@tabular[#:style 'boxed (list (list @t{A ``boxed'' table.}))]
+
+@; ======================================================================
+@section{Enumerations}
+
+This one is unordered, so it uses @tt{<ul>}:
+
+@itemlist[
+
+ @item{six}
+
+ @item{half-dozen}
+
+]
+
+This one is ordered, so it uses @tt{<ol>}:
+
+@itemlist[#:style 'ordered
+
+ @item{First}
+
+ @item{Second
+
+ @itemlist[#:style 'ordered
+
+ @item{Second, first half}
+
+ @item{Second, second half
+
+ @itemlist[#:style 'ordered
+
+ @item{First half of that}
+
+ @item{Second half of that
+
+ @itemlist[#:style 'ordered
+
+ @item{Thin-slice start}
+
+ @item{Thin-sliced end}
+
+ ]}
+ ]}
+
+ ]}
+
+ @item{Third}
+]
+
+This one is ``compact'':
+
+@itemlist[ #:style 'compact
+
+ @item{six}
+
+ @item{half-dozen}
+
+]
+
+@; ======================================================================
+@section{Paragraph Spacing}
+
+This sentence is a paragraph all by itself.
+
+@t{This sentence is a paragraph.}
+@t{This sentence is also a paragraph, but it is connected to the
+ previous paragraph as a compound paragraph by virtue of having no
+ paragraph-breaking space before it, and each paragraph is in a
+ ``SIntraPara'' @tt{<div>} instead of a @tt{<p>}.}
+
+This sentence is a paragraph, as is each of A1, B1, A2, B2, A3, B3a,
+and B2a in the following table, but B3a and B2a form a compound paragraph.
+@;
+@tabular[(list (list "A1"
+ "B1")
+ (list "A2"
+ "B2")
+ (list "A3"
+ @compound-paragraph[plain (list @t{B3a} @t{B3b})]))]
+@;
+This sentence is a paragraph, and with the preceding table and
+ paragraph forms a compound paragraph.
+
+@nested{
+ @t{This is a first paragraph in a @tt{<blockquote>}.}
+ @t{This is a second paragraph in a @tt{<blockquote>}.}
+}
+
+
+@; ======================================================================
+@section{Navigation Bars}
+
+For multi-page rendering, this page will have a navigation bar at the
+top and bottom. The bars are within ``maincolumn'' and ``main''.
+
+The tap bar is in ``navsettop'', and the bottom one is in
+``navsetbottom''. Within those divs, ``navsetleft'' wraps content to
+be left-aligned and ``navsetright'' wraps content to be right-aligned.
+
+Links that are disabled (such as a next-page link on the last page)
+are each in a span ``nonavigation''.
+
+When a search box is included, then it is in ``searchform'' and then
+``searchbox''.
+
+Finally, and not part of the nagivation bar, the bottom nagivation bar
+is followed by a @tt{div} with the name
+``contextindicator''. JavaScript code attached to the page copies the
+@tt{ctxtname} query argument, if any, to the @tt{div} and makes it
+visible.
+
+@; ======================================================================
+@index-section[]
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/info.rkt
@@ -1,3 +1,7 @@
#lang info
-(define scribblings '(("scribble.scrbl" (multi-page) (racket-core -24))))
+(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))))
