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-values (:path->root-relative

4
collects/scribble/basic.ss
View File

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

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

@ -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 "<!DOCTYPE html PUBLIC ~s ~s>\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)

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

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

5
collects/scribble/run.ss
View File

@ -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 <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"
(current-style-file file)]
[("--redirect") url "redirect external links to tag search via <url>"
@ -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)

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
\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''}

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

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

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

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

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

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["xref.scrbl"]
@include-section["preprocessor.scrbl"]
@include-section["config.scrbl"]
@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[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],