diff --git a/collects/scribble/base-render.ss b/collects/scribble/base-render.ss index 0279f549..df0ca9e4 100644 --- a/collects/scribble/base-render.ss +++ b/collects/scribble/base-render.ss @@ -47,6 +47,30 @@ ;; ---------------------------------------- + (define/public (extract-part-style-files d tag stop-at-part?) + (let loop ([p d]) + (let ([s (part-style p)]) + (apply + append + (if (list? s) + (filter + values + (map (lambda (s) + (and (list? s) + (= 2 (length s)) + (eq? (car s) tag) + (path-string? (cadr s)) + (cadr s))) + s)) + null) + (map (lambda (p) + (if (stop-at-part? p) + null + (loop p))) + (part-parts p)))))) + + ;; ---------------------------------------- + (define root (make-mobile-root root-path)) (define-values (:path->root-relative diff --git a/collects/scribble/basic.ss b/collects/scribble/basic.ss index d90ae6f1..80aed345 100644 --- a/collects/scribble/basic.ss +++ b/collects/scribble/basic.ss @@ -213,8 +213,8 @@ h)) (make-element 'hspace (list (make-string n #\space))))) -(define (elem . str) - (make-element #f (decode-content str))) +(define (elem #:style [style #f] . str) + (make-element style (decode-content str))) (define (aux-elem . s) (make-aux-element #f (decode-content s))) diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss index e472fa42..542f095e 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.ss @@ -4,6 +4,7 @@ scheme/class scheme/path scheme/file + scheme/port scheme/list scheme/string mzlib/runtime-path @@ -43,6 +44,7 @@ "\n")))) (define-runtime-path scribble-css "scribble.css") +(define-runtime-path scribble-prefix-html "scribble-prefix.html") (define-runtime-path scribble-js "scribble-common.js") ;; utilities for render-one-part (define-values (scribble-css-contents scribble-js-contents) @@ -232,13 +234,15 @@ install-file get-dest-directory format-number - quiet-table-of-contents) + quiet-table-of-contents + extract-part-style-files) (init-field [css-path #f] ;; up-path is either a link "up", or #t which uses ;; goes to start page (using cookies to get to the ;; user start page) [up-path #f] + [prefix-file #f] [style-file #f] [style-extra-files null] [script-path #f] @@ -570,19 +574,19 @@ (define/public (render-one-part d ri fn number) (parameterize ([current-output-file fn]) - (let* ([style-file (or style-file scribble-css)] + (let* ([prefix-file (or prefix-file scribble-prefix-html)] + [style-file (or style-file scribble-css)] [script-file (or script-file scribble-js)] [title (cond [(part-title-content d) => (lambda (c) `(title ,@(format-number number '(nbsp)) ,(content->string c this d ri)))] [else `(title)])]) - (unless css-path (install-file style-file)) - (for-each (lambda (f) (install-file f)) style-extra-files) + (unless css-path (install-file style-file)) (unless script-path (install-file script-file)) - (printf "\n" - "-//W3C//DTD HTML 4.0 Transitional//EN" - "http://www.w3.org/TR/html4/loose.dtd") + (call-with-input-file* prefix-file + (lambda (in) + (copy-port in (current-output-port)))) (xml:write-xml/content (xml:xexpr->xml `(html () @@ -592,8 +596,13 @@ ,title ,(scribble-css-contents style-file css-path) ,@(map (lambda (style-file) - (scribble-css-contents style-file css-path)) - style-extra-files) + (install-file style-file) + (scribble-css-contents style-file #f)) + (append style-extra-files + (extract-part-style-files + d + 'css + (lambda (p) (part-whole-page? p ri))))) ,(scribble-js-contents script-file script-path)) (body () ,@(render-toc-view d ri) diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss index 30b7a720..d43fcc81 100644 --- a/collects/scribble/latex-render.ss +++ b/collects/scribble/latex-render.ss @@ -17,6 +17,7 @@ (define-struct (toc-paragraph paragraph) ()) +(define-runtime-path scribble-prefix-tex "scribble-prefix.tex") (define-runtime-path scribble-tex "scribble.tex") (define (gif-to-png p) @@ -26,7 +27,8 @@ (define (render-mixin %) (class % - (init-field [style-file #f] + (init-field [prefix-file #f] + [style-file #f] [style-extra-files null]) (define/override (get-suffix) #".tex") @@ -35,16 +37,23 @@ render-block render-content install-file - format-number) + format-number + extract-part-style-files) (define/override (render-one d ri fn) - (let ([style-file (or style-file scribble-tex)]) + (let ([style-file (or style-file scribble-tex)] + [prefix-file (or prefix-file scribble-prefix-tex)]) (for-each (lambda (style-file) (with-input-from-file style-file (lambda () (copy-port (current-input-port) (current-output-port))))) - (cons style-file style-extra-files)) + (list* prefix-file style-file + (append style-extra-files + (extract-part-style-files + d + 'tex + (lambda (p) #f))))) (printf "\\begin{document}\n\\preDoc\n") (when (part-title-content d) (let ([m (ormap (lambda (v) diff --git a/collects/scribble/run.ss b/collects/scribble/run.ss index 58bd4961..12650f8c 100644 --- a/collects/scribble/run.ss +++ b/collects/scribble/run.ss @@ -32,6 +32,8 @@ (make-parameter null)) (define current-xref-input-modules (make-parameter null)) + (define current-prefix-file + (make-parameter #f)) (define current-style-file (make-parameter #f)) (define current-style-extra-files @@ -67,6 +69,8 @@ (current-dest-directory dir)] [("--dest-name") name "write output as " (current-dest-name name)] + [("--prefix") file "use given .html/.tex prefix (for doctype/documentclass)" + (current-prefix-file file)] [("--style") file "use given base .css/.tex file" (current-style-file file)] [("--redirect") url "redirect external links to tag search via " @@ -110,6 +114,7 @@ (let ([renderer (new ((current-render-mixin) render%) [dest-dir dir] + [prefix-file (current-prefix-file)] [style-file (current-style-file)] [style-extra-files (reverse (current-style-extra-files))])]) (when (current-redirect) diff --git a/collects/scribble/scribble-prefix.html b/collects/scribble/scribble-prefix.html new file mode 100644 index 00000000..4ef584cc --- /dev/null +++ b/collects/scribble/scribble-prefix.html @@ -0,0 +1 @@ + diff --git a/collects/scribble/scribble-prefix.tex b/collects/scribble/scribble-prefix.tex new file mode 100644 index 00000000..9cfd0982 --- /dev/null +++ b/collects/scribble/scribble-prefix.tex @@ -0,0 +1,11 @@ +% This is the default prefix for Scribble-generated Latex +\documentclass{article} + +\parskip=10pt +\parindent=0pt + +% Adjust margins to match HTML width for +% fixed-width font +\advance \oddsidemargin by -0.15in +\advance \evensidemargin by -0.15in +\advance \textwidth by 0.3in diff --git a/collects/scribble/scribble.tex b/collects/scribble/scribble.tex index 3c0552fa..47e3f691 100644 --- a/collects/scribble/scribble.tex +++ b/collects/scribble/scribble.tex @@ -1,16 +1,5 @@ -% This is the default prefix for Scribble-generated Latex - -\documentclass{article} +% This is the default style configuration for Scribble-generated Latex -\parskip=10pt -\parindent=0pt - -% Adjust margins to match HTML width for -% fixed-width font -\advance \oddsidemargin by -0.15in -\advance \evensidemargin by -0.15in -\advance \textwidth by 0.3in - \usepackage{graphicx} \usepackage{hyperref} \renewcommand{\rmdefault}{ptm} @@ -88,7 +77,6 @@ \newenvironment{bibentry}[1]{\parbox[t]{0.8\linewidth}{#1}} \newenvironment{bigtabular}{\begin{longtable}}{\end{longtable}\vspace{-3ex}} -\newcommand{\bigtabline}{\vspace{-2ex}} \newcommand{\SecRef}[2]{\S#1 ``#2''} diff --git a/collects/scribble/text-render.ss b/collects/scribble/text-render.ss index 31835d1f..906d426d 100644 --- a/collects/scribble/text-render.ss +++ b/collects/scribble/text-render.ss @@ -6,7 +6,8 @@ (define (render-mixin %) (class % - (init [style-file #f] + (init [prefix-file #f] + [style-file #f] [style-extra-files ()]) (define/override (get-substitutions) diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index 6a680275..7d9bf573 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -151,8 +151,12 @@ using @scheme[path->main-collects-relative].} @section{Text Styles} -@def-elem-proc[elem]{ Wraps the @tech{decode}d @scheme[pre-content] as -an element with style @scheme[#f].} +@defproc[(elem [pre-content any/c] ... + [#:style style any/c #f]) + element?]{ + +Wraps the @tech{decode}d @scheme[pre-content] as an element with style +@scheme[style].} @def-elem-proc[aux-elem]{Like @scheme[elem], but creates an @scheme[aux-element].} diff --git a/collects/scribblings/scribble/config.scrbl b/collects/scribblings/scribble/config.scrbl new file mode 100644 index 00000000..0d031057 --- /dev/null +++ b/collects/scribblings/scribble/config.scrbl @@ -0,0 +1,135 @@ +#lang scribble/doc +@(require scribble/manual + scribble/struct + scribble/decode + "utils.ss" + (for-label scheme/base)) + +@(define (nested . str) + (make-blockquote #f (flow-paragraphs (decode-flow str)))) +@(define (fake-title . str) (apply bold str)) + +@title[#:tag "config"]{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 +extend or configure Scribble fall into two groups: + +@itemize[ + + @item{You may need to drop into the back-end ``language'' of CSS or + Tex to create a specific output effect. For this kind of + extension, you will mostly likely attach a @scheme[`(css + ,_file)] or @scheme[`(tex ,_file)] style to a @scheme[section] + and then use a string defined in the @scheme[_file] as an + @scheme[element] or @tech{block} style. This kind of extension + is described in @secref["extra-style"].} + + @item{You may need to produce a document whose page layout is + different from the PLT Scheme documentation style. For that + kind of configuration, you will most likely run the + @exec{scribble} command-line tool and supply flags like + @DFlag{prefix} or @DPFlag{style}. This kind of configuration + is described in @secref["config-style"].} + +] + +@; ------------------------------------------------------------ + +@section[#:tag "extra-style" + #:style `((css "inbox.css") (tex "inbox.tex"))]{Adding a Style} + +When a string is uses as a style in an @scheme[element], +@scheme[styled-paragraph], or @scheme[blockquote], it corresponds to a +CSS class for HTML output or a Tex macro (or Latex environment, in the +case of @scheme[blockquote]) for Latex output. + +Scribble includes a number of predefined styles that are used by the +exports of @scheme[scribble/manual], but they are not generally +intended for direct use. For now, use them or redefine them at your +own risk. + +To add a mapping from your own style name to a CSS configuration, add +a @scheme[`(css ,_file)] style (in a list of styles) to an enclosing +@scheme[part]. To map a style name to a Tex macro (or Latex +environment), add a @scheme[`(tex ,_file)] style to an enclosing part. + +To avoid collisions with future additions to Scribble, start your +style name with an uppercase letter that is not @litchar{S}. An +uppercase letter helps to avoid collisions with macros defined by +Latex packages, and future styles needed by @scheme[scribble/manual] +will start with @litchar{s}. + +For example, a Scribble document + +@verbatim[#:indent 2]|{ + #lang scribble/doc + @(require manual) + + @title[#:style `((css "inbox.css") (tex "inbox.tex"))]{Quantum Pet} + + Do not open: @elem[#:style "InBox"]{Cat} +}| + +combined with an @filepath{inbox.css} that contains + +@verbatim[#:indent 2]|{ + .inbox { + padding: 0.2em; + border: 1px solid #000000; + } +}| + +and an @filepath{inbox.tex} that contains + +@verbatim[#:indent 2]|{ + \newcommand{\InBox}[1]{\fbox{#1}} +}| + +generates + +@nested{ + @fake-title{Quantum Pet} + + Do not open: @elem[#:style "InBox"]{Cat} +} + +@; ------------------------------------------------------------ + +@section[#:tag "config-style"]{Configuring Output} + +Scribble's output is configured in two layers: + +@itemize[ + + @item{A prefix determines the @tt{DOCTYPE} line for HTML output or + the @tt{documentclass} configuration (and perhaps some addition + package uses or other configuration) for Latex output. The + default prefix is @filepath{scribble-prefix.html} or + @filepath{scribble-prefix.tex} in the @filepath{scribble} + collection.} + + @item{Style definitions for all of the ``built-in'' styles used by + @scheme[scribble/manual] (as described in + @secref["extra-style"]). The default style definitions are + @filepath{scribble.css} or @filepath{scribble.tex} in the + @filepath{scribble} collection.} + +] + +When using the @exec{scribble} command-line utility: + +@itemize[ + + @item{Replace the prefix using the @as-index{@DFlag{prefix}} flag.} + + @item{Replace the style definitions using the + @as-index{@DFlag{style}} flag.} + + @item{Add style definitions (that can override earlier ones) + using the @as-index{@DPFlag{style}} flag.} + +] + +For now, reading the default files is the best way to understand how +they interact. diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl index 63b6ff34..39c7ad4b 100644 --- a/collects/scribblings/scribble/how-to.scrbl +++ b/collects/scribblings/scribble/how-to.scrbl @@ -9,7 +9,11 @@ Although the @exec{scribble} command-line utility generates output from a Scribble document (run @exec{scribble -h} for more information), documentation of PLT Scheme libraries is normally built by @exec{setup-plt}. This chapter emphasizes the @exec{setup-plt} -approach, which more automatically supports links across documents. +approach, which more automatically supports links across +documents. + +@margin-note{See @secref["config"] for information on using the + @exec{scribble} command-line utility.} @;---------------------------------------- @section[#:tag "getting-started"]{Getting Started} diff --git a/collects/scribblings/scribble/inbox.css b/collects/scribblings/scribble/inbox.css new file mode 100644 index 00000000..4cc3a903 --- /dev/null +++ b/collects/scribblings/scribble/inbox.css @@ -0,0 +1,4 @@ +.inbox { + padding: 0.2em; + border: 1px solid #000000; +} diff --git a/collects/scribblings/scribble/inbox.tex b/collects/scribblings/scribble/inbox.tex new file mode 100644 index 00000000..399a3ee2 --- /dev/null +++ b/collects/scribblings/scribble/inbox.tex @@ -0,0 +1,2 @@ + +\newcommand{\InBox}[1]{\fbox{#1}} diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl index 37be0ce4..628e4911 100644 --- a/collects/scribblings/scribble/scribble.scrbl +++ b/collects/scribblings/scribble/scribble.scrbl @@ -39,5 +39,6 @@ starting with the @filepath{scribble.scrbl} file. @include-section["bnf.scrbl"] @include-section["xref.scrbl"] @include-section["preprocessor.scrbl"] +@include-section["config.scrbl"] @index-section[] diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl index f5d65564..31bf12b3 100644 --- a/collects/scribblings/scribble/struct.scrbl +++ b/collects/scribblings/scribble/struct.scrbl @@ -257,9 +257,9 @@ to the section. The @scheme[title-content] field holds the part's title, if any. -The @scheme[style] field is normally either a symbol or a list of -symbols. The currently recognized style symbols (alone or in a list) -are as follows: +The @scheme[style] field is normally either a symbol or a list. The +currently recognized style symbols (alone or in a list) or other +values (must be in a list) are as follows: @itemize{ @@ -288,6 +288,12 @@ are as follows: multi-page documents) takes on the location and color of the main table of contents, instead.} + @item{@scheme[`(css ,_path)] --- generated HTML refers to (a copy + of) @scheme[_path] as CSS.} + + @item{@scheme[`(tex ,_path)] --- generated Latex includes + (a copy of) @scheme[_path] in the document header.} + } The @scheme[to-collect] field contains @techlink{content} that is @@ -350,7 +356,7 @@ The @scheme[style] can be @itemize[ @item{A string that corresponds to a CSS class for HTML output or a - macro for Latex output.} + macro for Latex output (see @secref["extra-style"]).} @item{An instance of @scheme[with-attributes], which combines a base style with a set of additional HTML attributes.} @@ -386,7 +392,7 @@ The @scheme[style] can be any of the following: @itemize[ @item{A string that corresponds to a CSS class for - HTML output.} + HTML output (see @secref["extra-style"]).} @item{@scheme['boxed] to render as a definition.} @@ -431,7 +437,8 @@ A @techlink{itemization} has a list of flows. A @techlink{blockquote} has a style and a list of @tech{blocks}. The @scheme[style] field is normally a string that corresponds to a CSS -class for HTML output. +class for HTML output or Latex environment for Latex output (see +@secref["extra-style"]). } @@ -452,7 +459,7 @@ The @scheme[style] field is normally either @itemize{ @item{a string, which corresponds to a CSS class for HTML output and - a macro name for Latex output;} + a macro name for Latex output (see @secref["extra-style"]);} @item{one of the symbols that all renderers recognize: @scheme['tt], @scheme['italic], @scheme['bold], @scheme['sf],