suzanne.soy/hyper-literate
1
0
Fork 0
Code Issues 4 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

scribble back-end configuration improvements

Browse Source 
svn: r13792

original commit: 04c2a2c3a4ab78103f6c682964ce53f675887c83
This commit is contained in:
Matthew Flatt 2009-02-22 18:37:35 +00:00
parent 0e45d725ea
commit 2a91307fce
16 changed files with 244 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
collects/scribble/base-render.ss
View File

@ -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 root (make-mobile-root root-path))
(define-values (:path->root-relative (define-values (:path->root-relative

4
collects/scribble/basic.ss
View File

@ -213,8 +213,8 @@
h)) h))
(make-element 'hspace (list (make-string n #\space))))) (make-element 'hspace (list (make-string n #\space)))))
(define (elem . str) (define (elem #:style [style #f] . str)
(make-element #f (decode-content str))) (make-element style (decode-content str)))
(define (aux-elem . s) (define (aux-elem . s)
(make-aux-element #f (decode-content s))) (make-aux-element #f (decode-content s)))

27
collects/scribble/html-render.ss
View File

@ -4,6 +4,7 @@
scheme/class scheme/class
scheme/path scheme/path
scheme/file scheme/file
scheme/port
scheme/list scheme/list
scheme/string scheme/string
mzlib/runtime-path mzlib/runtime-path
@ -43,6 +44,7 @@
"\n")))) "\n"))))
(define-runtime-path scribble-css "scribble.css") (define-runtime-path scribble-css "scribble.css")
(define-runtime-path scribble-prefix-html "scribble-prefix.html")
(define-runtime-path scribble-js "scribble-common.js") (define-runtime-path scribble-js "scribble-common.js")
;; utilities for render-one-part ;; utilities for render-one-part
(define-values (scribble-css-contents scribble-js-contents) (define-values (scribble-css-contents scribble-js-contents)
@ -232,13 +234,15 @@
install-file install-file
get-dest-directory get-dest-directory
format-number format-number
quiet-table-of-contents) quiet-table-of-contents
extract-part-style-files)
(init-field [css-path #f] (init-field [css-path #f]
;; up-path is either a link "up", or #t which uses ;; up-path is either a link "up", or #t which uses
;; goes to start page (using cookies to get to the ;; goes to start page (using cookies to get to the
;; user start page) ;; user start page)
[up-path #f] [up-path #f]
[prefix-file #f]
[style-file #f] [style-file #f]
[style-extra-files null] [style-extra-files null]
[script-path #f] [script-path #f]
@ -570,19 +574,19 @@
(define/public (render-one-part d ri fn number) (define/public (render-one-part d ri fn number)
(parameterize ([current-output-file fn]) (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)] [script-file (or script-file scribble-js)]
[title (cond [(part-title-content d) [title (cond [(part-title-content d)
=> (lambda (c) => (lambda (c)
`(title ,@(format-number number '(nbsp)) `(title ,@(format-number number '(nbsp))
,(content->string c this d ri)))] ,(content->string c this d ri)))]
[else `(title)])]) [else `(title)])])
(unless css-path (install-file style-file)) (unless css-path (install-file style-file))
(for-each (lambda (f) (install-file f)) style-extra-files)
(unless script-path (install-file script-file)) (unless script-path (install-file script-file))
(printf "<!DOCTYPE html PUBLIC ~s ~s>\n" (call-with-input-file* prefix-file
"-//W3C//DTD HTML 4.0 Transitional//EN" (lambda (in)
"http://www.w3.org/TR/html4/loose.dtd") (copy-port in (current-output-port))))
(xml:write-xml/content (xml:write-xml/content
(xml:xexpr->xml (xml:xexpr->xml
`(html () `(html ()
@ -592,8 +596,13 @@
,title ,title
,(scribble-css-contents style-file css-path) ,(scribble-css-contents style-file css-path)
,@(map (lambda (style-file) ,@(map (lambda (style-file)
(scribble-css-contents style-file css-path)) (install-file style-file)
style-extra-files) (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)) ,(scribble-js-contents script-file script-path))
(body () (body ()
,@(render-toc-view d ri) ,@(render-toc-view d ri)

17
collects/scribble/latex-render.ss
View File

@ -17,6 +17,7 @@
(define-struct (toc-paragraph paragraph) ()) (define-struct (toc-paragraph paragraph) ())
(define-runtime-path scribble-prefix-tex "scribble-prefix.tex")
(define-runtime-path scribble-tex "scribble.tex") (define-runtime-path scribble-tex "scribble.tex")
(define (gif-to-png p) (define (gif-to-png p)
@ -26,7 +27,8 @@
(define (render-mixin %) (define (render-mixin %)
(class % (class %
(init-field [style-file #f] (init-field [prefix-file #f]
[style-file #f]
[style-extra-files null]) [style-extra-files null])
(define/override (get-suffix) #".tex") (define/override (get-suffix) #".tex")
@ -35,16 +37,23 @@
render-block render-block
render-content render-content
install-file install-file
format-number) format-number
extract-part-style-files)
(define/override (render-one d ri fn) (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 (for-each
(lambda (style-file) (lambda (style-file)
(with-input-from-file style-file (with-input-from-file style-file
(lambda () (lambda ()
(copy-port (current-input-port) (current-output-port))))) (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") (printf "\\begin{document}\n\\preDoc\n")
(when (part-title-content d) (when (part-title-content d)
(let ([m (ormap (lambda (v) (let ([m (ormap (lambda (v)

5
collects/scribble/run.ss
View File

@ -32,6 +32,8 @@
(make-parameter null)) (make-parameter null))
(define current-xref-input-modules (define current-xref-input-modules
(make-parameter null)) (make-parameter null))
(define current-prefix-file
(make-parameter #f))
(define current-style-file (define current-style-file
(make-parameter #f)) (make-parameter #f))
(define current-style-extra-files (define current-style-extra-files
@ -67,6 +69,8 @@
(current-dest-directory dir)] (current-dest-directory dir)]
[("--dest-name") name "write output as <name>" [("--dest-name") name "write output as <name>"
(current-dest-name name)] (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" [("--style") file "use given base .css/.tex file"
(current-style-file file)] (current-style-file file)]
[("--redirect") url "redirect external links to tag search via <url>" [("--redirect") url "redirect external links to tag search via <url>"
@ -110,6 +114,7 @@
(let ([renderer (new ((current-render-mixin) render%) (let ([renderer (new ((current-render-mixin) render%)
[dest-dir dir] [dest-dir dir]
[prefix-file (current-prefix-file)]
[style-file (current-style-file)] [style-file (current-style-file)]
[style-extra-files (reverse (current-style-extra-files))])]) [style-extra-files (reverse (current-style-extra-files))])])
(when (current-redirect) (when (current-redirect)

1
collects/scribble/scribble-prefix.html Normal file
View File

@ -0,0 +1 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

11
collects/scribble/scribble-prefix.tex Normal file
View File

@ -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

14
collects/scribble/scribble.tex
View File

@ -1,16 +1,5 @@
% This is the default prefix for Scribble-generated Latex % This is the default style configuration 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
\usepackage{graphicx} \usepackage{graphicx}
\usepackage{hyperref} \usepackage{hyperref}
\renewcommand{\rmdefault}{ptm} \renewcommand{\rmdefault}{ptm}
@ -88,7 +77,6 @@
\newenvironment{bibentry}[1]{\parbox[t]{0.8\linewidth}{#1}} \newenvironment{bibentry}[1]{\parbox[t]{0.8\linewidth}{#1}}
\newenvironment{bigtabular}{\begin{longtable}}{\end{longtable}\vspace{-3ex}} \newenvironment{bigtabular}{\begin{longtable}}{\end{longtable}\vspace{-3ex}}
\newcommand{\bigtabline}{\vspace{-2ex}}
\newcommand{\SecRef}[2]{\S#1 ``#2''} \newcommand{\SecRef}[2]{\S#1 ``#2''}

3
collects/scribble/text-render.ss
View File

@ -6,7 +6,8 @@
(define (render-mixin %) (define (render-mixin %)
(class % (class %
(init [style-file #f] (init [prefix-file #f]
[style-file #f]
[style-extra-files ()]) [style-extra-files ()])
(define/override (get-substitutions) (define/override (get-substitutions)

8
collects/scribblings/scribble/basic.scrbl
View File

@ -151,8 +151,12 @@ using @scheme[path->main-collects-relative].}
@section{Text Styles} @section{Text Styles}
@def-elem-proc[elem]{ Wraps the @tech{decode}d @scheme[pre-content] as @defproc[(elem [pre-content any/c] ...
an element with style @scheme[#f].} [#: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 @def-elem-proc[aux-elem]{Like @scheme[elem], but creates an
@scheme[aux-element].} @scheme[aux-element].}

135
collects/scribblings/scribble/config.scrbl Normal file
View File

@ -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.

6
collects/scribblings/scribble/how-to.scrbl
View File

@ -9,7 +9,11 @@ Although the @exec{scribble} command-line utility generates output
from a Scribble document (run @exec{scribble -h} for more from a Scribble document (run @exec{scribble -h} for more
information), documentation of PLT Scheme libraries is normally built information), documentation of PLT Scheme libraries is normally built
by @exec{setup-plt}. This chapter emphasizes the @exec{setup-plt} 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} @section[#:tag "getting-started"]{Getting Started}

4
collects/scribblings/scribble/inbox.css Normal file
View File

@ -0,0 +1,4 @@
.inbox {
padding: 0.2em;
border: 1px solid #000000;
}

2
collects/scribblings/scribble/inbox.tex Normal file
View File

@ -0,0 +1,2 @@
\newcommand{\InBox}[1]{\fbox{#1}}

1
collects/scribblings/scribble/scribble.scrbl
View File

@ -39,5 +39,6 @@ starting with the @filepath{scribble.scrbl} file.
@include-section["bnf.scrbl"] @include-section["bnf.scrbl"]
@include-section["xref.scrbl"] @include-section["xref.scrbl"]
@include-section["preprocessor.scrbl"] @include-section["preprocessor.scrbl"]
@include-section["config.scrbl"]
@index-section[] @index-section[]

21
collects/scribblings/scribble/struct.scrbl
View File

@ -257,9 +257,9 @@ to the section.
The @scheme[title-content] field holds the part's title, if any. 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 The @scheme[style] field is normally either a symbol or a list. The
symbols. The currently recognized style symbols (alone or in a list) currently recognized style symbols (alone or in a list) or other
are as follows: values (must be in a list) are as follows:
@itemize{ @itemize{
@ -288,6 +288,12 @@ are as follows:
multi-page documents) takes on the location and color of the multi-page documents) takes on the location and color of the
main table of contents, instead.} 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 The @scheme[to-collect] field contains @techlink{content} that is
@ -350,7 +356,7 @@ The @scheme[style] can be
@itemize[ @itemize[
@item{A string that corresponds to a CSS class for HTML output or a @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 @item{An instance of @scheme[with-attributes], which combines a base
style with a set of additional HTML attributes.} style with a set of additional HTML attributes.}
@ -386,7 +392,7 @@ The @scheme[style] can be any of the following:
@itemize[ @itemize[
@item{A string that corresponds to a CSS class for @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.} @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 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 @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{ @itemize{
@item{a string, which corresponds to a CSS class for HTML output and @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], @item{one of the symbols that all renderers recognize: @scheme['tt],
@scheme['italic], @scheme['bold], @scheme['sf], @scheme['italic], @scheme['bold], @scheme['sf],