From 798a3983de4bb01d488ed611d44d3e8fd330c5e2 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Fri, 26 Oct 2012 14:24:10 -0400 Subject: [PATCH 1/7] scribble: add examples for most def* forms original commit: b56574e4d56d4abc991dee201a93d92dfd613817 --- collects/scribblings/scribble/manual.scrbl | 148 +++++++++++++++++++-- 1 file changed, 136 insertions(+), 12 deletions(-) diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 3c55a1d2..84065b0e 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -757,7 +757,28 @@ If @racket[#:id [src-id dest-id-expr]] is supplied, then @racket[dest-id-expr] produces the identifier to be documented in place of @racket[src-id]. This split between @racket[src-id] and @racket[dest-id-expr] roles is useful for functional abstraction of -@racket[defproc].} +@racket[defproc]. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defproc[(make-sandwich [ingredients (listof ingredient?)]) + sandwich?]{ + Returns a sandwich given the right ingredients. +} + +@defproc[#:kind "sandwich-maker" + (make-reuben [ingredient sauerkraut?] ... + [#:veggie? veggie? any/c #f]) + sandwich?]{ + Produces a reuben given some number of @racket[ingredient]s. + + If @racket[veggie?] is @racket[#f], produces a standard + reuben with corned beef. Otherwise, produces a vegetable + reuben. +} +}| +} @defform[(defproc* maybe-kind maybe-id ([prototype @@ -765,16 +786,29 @@ place of @racket[src-id]. This split between @racket[src-id] and pre-flow ...)]{ Like @racket[defproc], but for multiple cases with the same -@racket[id]. +@racket[id]. When an @racket[id] has multiple calling cases, they must be defined with a single @racket[defproc*], so that a single definition point exists for the @racket[id]. However, multiple distinct @racket[id]s can also be defined by a single @racket[defproc*], for the case that -it's best to document a related group of procedures at once.} +it's best to document a related group of procedures at once. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defproc[((make-pb&j) + (make-pb&j [jelly jelly?])) + sandwich?]{ + Returns a peanut butter and jelly sandwich. If @racket[jelly] + is provided, then it is used instead of the standard (grape) + jelly. +} +}| +} -@defform/subs[(defform maybe-kind maybe-id maybe-literals form-datum +@defform/subs[(defform maybe-kind maybe-id maybe-literals form-datum maybe-contracts pre-flow ...) ([maybe-kind code:blank @@ -831,14 +865,48 @@ auxiliary grammar specified using @racket[defform/subs]. The typesetting of @racket[form-datum], @racket[subform-datum], and @racket[contract-expr-datum] preserves the source layout, like -@racket[racketblock].} +@racket[racketblock]. -@defform[(defform* maybe-kind maybe-id maybe-literals [form-datum ...+] +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defform[(sandwich-promise sandwich-expr) + #:contracts ([sandwich-expr sandwich?])]{ + Returns a promise to construct a sandwich. When forced, the promise + will produce the result of @racket[sandwich-expr]. +} + +@defform[#:literals (sandwich mixins) + (sandwich-promise* [sandwich sandwich-expr] + [mixins ingredient-expr ...]) + #:contracts ([sandwich-expr sandwich?] + [ingreient-expr ingredient?])]{ + Returns a promise to construct a sandwich. When forced, the promise + will produce the result of @racket[sandwich-expr]. Each result of + the @racket[ingredient-expr]s will be mixed into the resulting + sandwich. +} +}| +} + +@defform[(defform* maybe-kind maybe-id maybe-literals [form-datum ...+] maybe-contracts pre-flow ...)]{ Like @racket[defform], but for multiple forms using the same -@racket[_id].} +@racket[_id]. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defform*[((call-with-current-sandwich expr) + (call-with-current-sandwich expr sandwich-handler-expr))]{ + Runs @racket[expr] and passes it the value of the current + sandwich. If @racket[sandwich-handler-expr] is provided, its result + is invoked when the current sandwich is eaten. +} +}| +} @defform[(defform/subs maybe-kind maybe-id maybe-literals form-datum ([nonterm-id clause-datum ...+] ...) @@ -849,7 +917,22 @@ Like @racket[defform], but including an auxiliary grammar of non-terminals shown with the @racket[_id] form. Each @racket[nonterm-id] is specified as being any of the corresponding @racket[clause-datum]s, where the formatting of each -@racket[clause-datum] is preserved.} +@racket[clause-datum] is preserved. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defform/subs[(sandwich-factory maybe-name factory-component ...) + [(maybe-name (code:line) + name) + (factory-component (code:line #:protein protein-expr) + [vegetable vegetable-expr])]]{ + Constructs a sandwich factory. If @racket[maybe-name] is provided, + the factory will be named. Each of the @racket[factory-component] + clauses adds an additional ingredient to the sandwich pipeline. +} +}| +} @defform[(defform*/subs maybe-kind maybe-id maybe-literals [form-datum ...+] @@ -935,7 +1018,17 @@ Like @racket[specspecsubform], but with a grammar like Like @racket[defproc], but for a parameter. The @racket[contract-expr-datum] serves as both the result contract on the parameter and the contract on values supplied for the parameter. The -@racket[arg-id] refers to the parameter argument in the latter case.} +@racket[arg-id] refers to the parameter argument in the latter case. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defparam[current-sandwich sandwich sandwich?]{ + A parameter that defines the current sandwich for operations that + involve eating a sandwich. +} +}| +} @defform[(defboolparam id arg-id pre-flow ...)]{ @@ -950,7 +1043,16 @@ Like @racket[defproc], but for a non-procedure binding. If @racket[#:kind kind-string-expr] is supplied as @racket[maybe-kind], it is used in the same way as for -@racket[defproc], but the default kind is @racket["value"].} +@racket[defproc], but the default kind is @racket["value"]. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defthing[moldy-sandwich sandwich?] + Don't eat this. Provided for backwards compatibility. +} +}| +} @deftogether[( @@ -974,7 +1076,18 @@ If @racket[#:kind kind-string-expr] is supplied as Similar to @racket[defform] or @racket[defproc], but for a structure definition. The @racket[defstruct*] form corresponds to @racket[struct], -while @racket[defstruct] corresponds to @racket[define-struct].} +while @racket[defstruct] corresponds to @racket[define-struct]. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defstruct[sandwich ([protein ingredient?] [sauce ingredient?])]{ + A strucure type for sandwiches. Sandwiches are a pan-human foodstuff + composed of a partially-enclosing bread material and various + ingredients. +} +}| +} @defform[(deftogether [def-expr ...] pre-flow ...)]{ @@ -984,7 +1097,18 @@ single definition box. Each @racket[def-expr] should produce a definition point via @racket[defproc], @racket[defform], etc. Each @racket[def-expr] should have an empty @racket[pre-flow]; the @tech{decode}d @racket[pre-flow] sequence for the @racket[deftogether] -form documents the collected bindings.} +form documents the collected bindings. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@deftogether[(@defthing[test-sandwich-1 sandwich?] + @defthing[test-sandwich-2 sandwich?])]{ + Two high-quality sandwiches. These are provided for convenience + in writing test cases +} +}| +} @defform/subs[(racketgrammar maybe-literals id clause-datum ...+) From 77a57c85350063a4df05002c4ea7f9ccb1cd3591 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 27 Oct 2012 09:04:28 -0600 Subject: [PATCH 2/7] scribble Latex/PDF: use the `tocstyle' package Fixes the spacing of section numbers for a section like N.M where both N and M have two digits. original commit: c7d3de435f8c817bd7ccbe9c89678af21ec2d253 --- collects/scribble/scribble.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/collects/scribble/scribble.tex b/collects/scribble/scribble.tex index 773b745a..179f099d 100644 --- a/collects/scribble/scribble.tex +++ b/collects/scribble/scribble.tex @@ -11,6 +11,8 @@ \usepackage[htt]{hyphenat} \usepackage[usenames,dvipsnames]{color} \hypersetup{bookmarks=true,bookmarksopen=true,bookmarksnumbered=true} +\usepackage{tocstyle} +\usetocstyle{standard} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Configuration that is especially meant to be overridden: From 7189e553a0fb175e462f06ed66349d498262d4ef Mon Sep 17 00:00:00 2001 From: Robby Findler Date: Sat, 27 Oct 2012 18:36:55 -0500 Subject: [PATCH 3/7] fix apparent type error in the definition of in-plt? original commit: 54301ad5ede34fc5000e1a0effa342036b9c0ba9 --- collects/scribble/html-render.rkt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collects/scribble/html-render.rkt b/collects/scribble/html-render.rkt index cf33a004..e8f8ad4d 100644 --- a/collects/scribble/html-render.rkt +++ b/collects/scribble/html-render.rkt @@ -1597,7 +1597,7 @@ (list name))))))) (define in-plt? - (let ([roots (map explode (list (find-doc-dir) (find-collects-dir)))]) + (let ([roots (map explode (filter values (list (find-doc-dir) (find-collects-dir))))]) (lambda (path) (ormap (lambda (root) (let loop ([path path] [root root]) From e9ed7ce065fcb72b02db1879837dd60297f307c1 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 1 Nov 2012 09:29:26 -0600 Subject: [PATCH 4/7] Scribble Latex/PDF: use tocstyle only if it's available original commit: 739aa114044d17019936cd202045eabcd2e5e13c --- collects/scribble/scribble.tex | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/collects/scribble/scribble.tex b/collects/scribble/scribble.tex index 179f099d..29a3bd43 100644 --- a/collects/scribble/scribble.tex +++ b/collects/scribble/scribble.tex @@ -11,8 +11,7 @@ \usepackage[htt]{hyphenat} \usepackage[usenames,dvipsnames]{color} \hypersetup{bookmarks=true,bookmarksopen=true,bookmarksnumbered=true} -\usepackage{tocstyle} -\usetocstyle{standard} +\IfFileExists{tocstyle.sty}{\usepackage{tocstyle}\usetocstyle{standard}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Configuration that is especially meant to be overridden: From b951c48fca62ef7dbe36f8691f5a6c418afe033a Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 2 Nov 2012 06:51:20 -0600 Subject: [PATCH 5/7] Scribble PDF/Latex: Hangul support original commit: 008f476210498537dc4e6812b154aadb9cf4e864 --- collects/scribble/latex-render.rkt | 56 ++++++++++++++++-------------- collects/scribble/scribble.tex | 3 +- 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/collects/scribble/latex-render.rkt b/collects/scribble/latex-render.rkt index 8d542a02..082a7e54 100644 --- a/collects/scribble/latex-render.rkt +++ b/collects/scribble/latex-render.rkt @@ -966,33 +966,37 @@ [(#\u207a) "$^+$"] [(#\u207b) "$^-$"] [else - ;; Detect characters that can be formed with combining characters - ;; and translate them to Latex combinations: - (define s (string-normalize-nfd (string c))) - (define len (string-length s)) (cond - [(len . > . 1) - (define combiner (case (string-ref s (sub1 len)) - [(#\u300) "\\`{~a}"] - [(#\u301) "\\'{~a}"] - [(#\u302) "\\^{~a}"] - [(#\u303) "\\~~{~a}"] - [(#\u304) "\\={~a}"] - [(#\u306) "\\u{~a}"] - [(#\u307) "\\.{~a}"] - [(#\u308) "\\\"{~a}"] - [(#\u30a) "\\r{~a}"] - [(#\u30b) "\\H{~a}"] - [(#\u30c) "\\v{~a}"] - [(#\u327) "\\c{~a}"] - [(#\u328) "\\k{~a}"] - [else #f])) - (define base (string-normalize-nfc (substring s 0 (sub1 len)))) - (if (and combiner - (= 1 (string-length base))) - (format combiner (char-loop (string-ref base 0))) - c)] - [else c])]) + [(char<=? #\uAC00 c #\uD7AF) ; Korean Hangul + (format "\\begin{CJK}{UTF8}{mj}~a\\end{CJK}" c)] + [else + ;; Detect characters that can be formed with combining characters + ;; and translate them to Latex combinations: + (define s (string-normalize-nfd (string c))) + (define len (string-length s)) + (cond + [(len . > . 1) + (define combiner (case (string-ref s (sub1 len)) + [(#\u300) "\\`{~a}"] + [(#\u301) "\\'{~a}"] + [(#\u302) "\\^{~a}"] + [(#\u303) "\\~~{~a}"] + [(#\u304) "\\={~a}"] + [(#\u306) "\\u{~a}"] + [(#\u307) "\\.{~a}"] + [(#\u308) "\\\"{~a}"] + [(#\u30a) "\\r{~a}"] + [(#\u30b) "\\H{~a}"] + [(#\u30c) "\\v{~a}"] + [(#\u327) "\\c{~a}"] + [(#\u328) "\\k{~a}"] + [else #f])) + (define base (string-normalize-nfc (substring s 0 (sub1 len)))) + (if (and combiner + (= 1 (string-length base))) + (format combiner (char-loop (string-ref base 0))) + c)] + [else c])])]) c)]))) (loop (add1 i))))))) diff --git a/collects/scribble/scribble.tex b/collects/scribble/scribble.tex index 29a3bd43..e897e143 100644 --- a/collects/scribble/scribble.tex +++ b/collects/scribble/scribble.tex @@ -11,7 +11,8 @@ \usepackage[htt]{hyphenat} \usepackage[usenames,dvipsnames]{color} \hypersetup{bookmarks=true,bookmarksopen=true,bookmarksnumbered=true} -\IfFileExists{tocstyle.sty}{\usepackage{tocstyle}\usetocstyle{standard}} +\IfFileExists{tocstyle.sty}{\usepackage{tocstyle}\usetocstyle{standard}}{} +\IfFileExists{CJK.sty}{\usepackage{CJK}}{} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Configuration that is especially meant to be overridden: From 8002d98e5d93683287dd03f09b024e689fb75eb8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 2 Nov 2012 07:39:33 -0600 Subject: [PATCH 6/7] scribble: more control over version formatting Add "Version" in front of a version name via `.version:before' or `.versionNoNav:before' and `\SVersionBefore', so that they can be configured through overriding CSS or Latex macro declarations. Also, improve the documentation for how the `#:version' argument of `title' is propagated to a `part' style property. Closes PR 13227 original commit: a830f77403a1f51de7359c7946b01ef10d401cee --- collects/scribble/html-render.rkt | 2 +- collects/scribble/scribble.css | 4 ++++ collects/scribble/scribble.tex | 5 +++-- collects/scribblings/scribble/core.scrbl | 7 ++++++- collects/scribblings/scribble/decode.scrbl | 10 ++++++---- 5 files changed, 20 insertions(+), 8 deletions(-) diff --git a/collects/scribble/html-render.rkt b/collects/scribble/html-render.rkt index e8f8ad4d..016fb29d 100644 --- a/collects/scribble/html-render.rkt +++ b/collects/scribble/html-render.rkt @@ -890,7 +890,7 @@ (list (make-element (if (include-navigation?) "version" "versionNoNav") - (list "Version: " v))) + v)) d ri)))))) diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css index 7f502cba..d521d28f 100644 --- a/collects/scribble/scribble.css +++ b/collects/scribble/scribble.css @@ -154,6 +154,10 @@ table td { font-size: xx-small; /* avoid overlap with author */ } +.version:before, .versionNoNav:before { + content: "Version "; +} + /* ---------------------------------------- */ /* Margin notes */ diff --git a/collects/scribble/scribble.tex b/collects/scribble/scribble.tex index e897e143..b7ec1d86 100644 --- a/collects/scribble/scribble.tex +++ b/collects/scribble/scribble.tex @@ -141,12 +141,13 @@ \newenvironment{refcolumnleft}{\begin{refcolumn}}{\end{refcolumn}} % Macros used by `title' and `author': -\newcommand{\titleAndVersionAndAuthors}[3]{\title{#1\\{\normalsize Version #2}}\author{#3}\maketitle} -\newcommand{\titleAndVersionAndEmptyAuthors}[3]{\title{#1\\{\normalsize Version #2}}#3\maketitle} +\newcommand{\titleAndVersionAndAuthors}[3]{\title{#1\\{\normalsize \SVersionBefore{}#2}}\author{#3}\maketitle} +\newcommand{\titleAndVersionAndEmptyAuthors}[3]{\title{#1\\{\normalsize \SVersionBefore{}#2}}#3\maketitle} \newcommand{\titleAndEmptyVersionAndAuthors}[3]{\title{#1}\author{#3}\maketitle} \newcommand{\titleAndEmptyVersionAndEmptyAuthors}[3]{\title{#1}\maketitle} \newcommand{\SAuthor}[1]{#1} \newcommand{\SAuthorSep}[1]{\qquad} +\newcommand{\SVersionBefore}[1]{Version } % Useful for some styles, such as sigalternate: \newcommand{\SNumberOfAuthors}[1]{} diff --git a/collects/scribblings/scribble/core.scrbl b/collects/scribblings/scribble/core.scrbl index 71cda871..7ded2d58 100644 --- a/collects/scribblings/scribble/core.scrbl +++ b/collects/scribblings/scribble/core.scrbl @@ -400,7 +400,12 @@ The recognized @tech{style properties} are as follows: not @racket[""] may be used when rendering a document; at a minimum, a non-@racket[""] version is rendered when it is attached to a part representing the whole document. The default - version for a document is @racket[(version)].} + version for a document is @racket[(version)]. In rendered form, + the version is normally prefixed with the word ``Version,'' but + this formatting can be controlled by overriding + @tt{.version:before} and/or @tt{.versionNoNav:before} in CSS + for HTML rendering or by redefining the @tt{\SVersionBefore} + macro for Latex rendering (see @secref["config"]).} @item{@racket[document-date] structure --- A date for the part, normally used on a document's main part for for Latex diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl index 25e9cfaf..2b51d32f 100644 --- a/collects/scribblings/scribble/decode.scrbl +++ b/collects/scribblings/scribble/decode.scrbl @@ -168,18 +168,20 @@ otherwise.} @defstruct[title-decl ([tag-prefix (or/c #f string?)] [tags (listof string?)] [version (or/c string? #f)] - [style any/c] + [style style?] [content content?])]{ -See @racket[decode] and @racket[decode-part]. The @racket[_tag-prefix] -and @racket[_style] fields are propagated to the resulting +See @racket[decode] and @racket[decode-part]. The @racket[tag-prefix] +and @racketidfont{style} fields are propagated to the resulting +@racket[part]. If the @racketidfont{version} field is not @racket[#f], +it is propagated as a @racket[document-version] style property on the @racket[part].} @defstruct[part-start ([depth integer?] [tag-prefix (or/c #f string?)] [tags (listof string?)] - [style any/c] + [style style?] [title content?])]{ Like @racket[title-decl], but for a sub-part. See @racket[decode] and From 8ebc1bdfbd950acbbeb76a3515f4b3687b6c0c23 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 4 Nov 2012 06:38:30 -0700 Subject: [PATCH 7/7] make figure target rendering configurable from Kevin Tew original commit: c6fc92915d3de5b585eb01ddddf8c60f60664008 --- collects/scriblib/figure.rkt | 5 +++-- collects/scriblib/figure.tex | 2 ++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/collects/scriblib/figure.rkt b/collects/scriblib/figure.rkt index 014034c9..d9bbad80 100644 --- a/collects/scriblib/figure.rkt +++ b/collects/scriblib/figure.rkt @@ -29,6 +29,7 @@ (define herefigure-style (make-style "Herefigure" figure-style-extras)) (define figureinside-style (make-style "FigureInside" figure-style-extras)) (define legend-style (make-style "Legend" figure-style-extras)) +(define figure-target-style (make-style "FigureTarget" figure-style-extras)) (define centertext-style (make-style "Centertext" figure-style-extras)) (define figure-style (make-style "Figure" figure-style-extras)) @@ -52,7 +53,7 @@ figure-style (list (make-nested-flow content-style (list (make-nested-flow figureinside-style (decode-flow content)))) - (make-paragraph centertext-style (list (make-element legend-style (list (Figure-target tag) ": " caption))))))) + (make-paragraph centertext-style (list (make-element legend-style (list (make-element figure-target-style (list (Figure-target tag) ": ")) caption))))))) (define (*figure style tag caption content) (make-nested-flow @@ -65,7 +66,7 @@ (list (make-paragraph plain - (list (make-element legend-style (list (Figure-target tag) ": " caption)))))))))) + (list (make-element legend-style (list (make-element figure-target-style (list (Figure-target tag) ": ")) caption)))))))))) (define (figure* tag caption . content) (*figure centerfiguremulti-style tag caption content)) diff --git a/collects/scriblib/figure.tex b/collects/scriblib/figure.tex index b7a586a2..9f58e972 100644 --- a/collects/scriblib/figure.tex +++ b/collects/scriblib/figure.tex @@ -12,6 +12,8 @@ \vspace{4pt} \legend{#1}} +\newcommand{\FigureTarget}[1]{#1} + \newlength{\FigOrigskip} \FigOrigskip=\parskip