From dae3560a767a8d5efdb5c388d8c223d227f81763 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 8 Jan 2014 07:34:15 -0700 Subject: [PATCH] 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 --- .../scribblings/scribble/config.scrbl | 160 ++++++++- .../scribblings/scribble/core.scrbl | 5 +- .../scribblings/scribble/demo-m1.scrbl | 10 + .../scribblings/scribble/demo-m2.scrbl | 12 + .../scribblings/scribble/demo-s1.scrbl | 10 + .../scribblings/scribble/demo-s2.scrbl | 12 + .../scribblings/scribble/demo.scrbl | 321 ++++++++++++++++++ .../scribblings/scribble/info.rkt | 6 +- 8 files changed, 532 insertions(+), 4 deletions(-) create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-m1.scrbl create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-m2.scrbl create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-s1.scrbl create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo-s2.scrbl create mode 100644 pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/demo.scrbl diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/config.scrbl index 8655ee4e..6a9599d6 100644 --- 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{
}).}] + + [@spacer @spacer] + + [@css{SIntrapara} @elem{Used with @tt{
} instead of @tt{

} 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 index be1e837f..c7fc5d0e 100644 --- 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 new file mode 100644 index 00000000..55489af3 --- /dev/null +++ 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 new file mode 100644 index 00000000..90587193 --- /dev/null +++ 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 new file mode 100644 index 00000000..b49c8dc9 --- /dev/null +++ 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 new file mode 100644 index 00000000..0e1afce3 --- /dev/null +++ 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 new file mode 100644 index 00000000..a70c8a37 --- /dev/null +++ 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{
} 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{

}.} + +@nested[#:style 'inset]{This paragraph is in a plain @tt{
}.} + +@nested[#:style 'code-inset]{This paragraph is in a ``SCodeFlow'' +@tt{
}.} + +@nested[#:style 'vertical-inset]{This paragraph is in a +``SVInsetFlow'' @tt{
}. This style is useful when space is +not normally included between blocks.} + +@centered{This paragraph is in a ``SCentered'' @tt{
}.} + +@tabular[#:style 'boxed (list (list @t{A ``boxed'' table.}))] + +@; ====================================================================== +@section{Enumerations} + +This one is unordered, so it uses @tt{
    }: + +@itemlist[ + + @item{six} + + @item{half-dozen} + +] + +This one is ordered, so it uses @tt{
      }: + +@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{
      } instead of a @tt{

      }.} + +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{

      }.} + @t{This is a second paragraph in a @tt{
      }.} +} + + +@; ====================================================================== +@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 index bd066b7c..8e067076 100644 --- 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))))