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{
} 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))))