diff --git a/collects/help/help.ss b/collects/help/help.rkt similarity index 74% rename from collects/help/help.ss rename to collects/help/help.rkt index 340a7a7c..039a3438 100644 --- a/collects/help/help.ss +++ b/collects/help/help.rkt @@ -1,10 +1,12 @@ #lang scheme/base -(require "search.ss" scheme/cmdline scheme/list scheme/string) +(require "search.ss" scheme/cmdline scheme/list scheme/string + raco/command-name) ;; Minimal command-line arguments, the query string can contain all ;; kinds of magic. (command-line + #:program (short-program+command-name) #:handlers (lambda (_ . ts) (if (null? ts) diff --git a/collects/help/search.ss b/collects/help/search.rkt similarity index 100% rename from collects/help/search.ss rename to collects/help/search.rkt diff --git a/collects/scribble/base-render.ss b/collects/scribble/base-render.rkt similarity index 100% rename from collects/scribble/base-render.ss rename to collects/scribble/base-render.rkt diff --git a/collects/scribble/base.ss b/collects/scribble/base.rkt similarity index 99% rename from collects/scribble/base.ss rename to collects/scribble/base.rkt index a8545a84..d3d7fc44 100644 --- a/collects/scribble/base.ss +++ b/collects/scribble/base.rkt @@ -638,7 +638,7 @@ ;; the last round, and #f means no desc (define desc-order '(part mod libs delayed #f)) ;; this defines an imposed ordering for module names - (define lib-order '(#rx"^scheme(?:/|$)" #rx"^r.rs(?:/|$)" #rx"^lang(?:/|$)")) + (define lib-order '(#rx"^racket(?:/|$)" #rx"^r.rs(?:/|$)" #rx"^lang(?:/|$)")) (define (lib . maxlen) - ;; break the error message into multiple lines: - (let loop ([pos (sub1 maxlen)]) - (cond - [(zero? pos) (cons (substring s 0 maxlen) - (sloop (substring s maxlen)))] - [(char-whitespace? (string-ref s pos)) - (cons (substring s 0 pos) - (sloop (substring s (add1 pos))))] - [else (loop (sub1 pos))])) - (list s)))) + (filter + (lambda (s) (not (equal? s ""))) + (let sloop ([s (caar val-list+outputs)]) + (apply + append + (map (lambda (s) + (if ((string-length s) . > . maxlen) + ;; break the error message into multiple lines: + (let loop ([pos (sub1 maxlen)]) + (cond + [(zero? pos) (cons (substring s 0 maxlen) + (sloop (substring s maxlen)))] + [(char-whitespace? (string-ref s pos)) + (cons (substring s 0 pos) + (sloop (substring s (add1 pos))))] + [else (loop (sub1 pos))])) + (list s))) + (regexp-split #rx"\n" s)))))) ;; Normal result case: (let ([val-list (caar val-list+outputs)]) (if (equal? val-list (list (void))) @@ -118,7 +124,7 @@ (list (hspace 2) (elem #:style result-color - (to-element/no-color v)))))))) + (to-element/no-color v #:expr? (print-as-expression))))))))) val-list)))) (loop (cdr expr-paras) (cdr val-list+outputs) @@ -314,7 +320,7 @@ (define (show-val v) (elem #:style result-color - (to-element/no-color v))) + (to-element/no-color v #:expr? (print-as-expression)))) (define (do-interaction-eval-show ev e) (parameterize ([current-command-line-arguments #()]) @@ -325,31 +331,31 @@ [(_ #:eval ev e) (do-interaction-eval-show ev (quote-expr e))] [(_ e) (do-interaction-eval-show #f (quote-expr e))])) - (define-syntax schemeinput* + (define-syntax racketinput* (syntax-rules (eval:alts code:comment) - [(_ (code:comment . rest)) (schemeblock (code:comment . rest))] - [(_ (eval:alts a b)) (schemeinput* a)] - [(_ e) (schemeinput e)])) + [(_ (code:comment . rest)) (racketblock (code:comment . rest))] + [(_ (eval:alts a b)) (racketinput* a)] + [(_ e) (racketinput e)])) - (define-code schemeblock+line (to-paragraph/prefix (hspace 2) + (define-code racketblock+line (to-paragraph/prefix (hspace 2) (hspace 2) (list " "))) - (define-syntax (schemedefinput* stx) + (define-syntax (racketdefinput* stx) (syntax-case stx (define define-values define-struct) [(_ (define . rest)) (syntax-case stx () - [(_ e) #'(schemeblock+line e)])] + [(_ e) #'(racketblock+line e)])] [(_ (define-values . rest)) (syntax-case stx () - [(_ e) #'(schemeblock+line e)])] + [(_ e) #'(racketblock+line e)])] [(_ (define-struct . rest)) (syntax-case stx () - [(_ e) #'(schemeblock+line e)])] + [(_ e) #'(racketblock+line e)])] [(_ (code:line (define . rest) . rest2)) (syntax-case stx () - [(_ e) #'(schemeblock+line e)])] - [(_ e) #'(schemeinput* e)])) + [(_ e) #'(racketblock+line e)])] + [(_ e) #'(racketinput* e)])) (define (do-titled-interaction ev t shows evals) (interleave t @@ -358,41 +364,41 @@ (define-syntax titled-interaction (syntax-rules () - [(_ #:eval ev t schemeinput* e ...) - (do-titled-interaction ev t (list (schemeinput* e) ...) (list (quote-expr e) ...))] - [(_ t schemeinput* e ...) - (titled-interaction #:eval (make-base-eval) t schemeinput* e ...)])) + [(_ #:eval ev t racketinput* e ...) + (do-titled-interaction ev t (list (racketinput* e) ...) (list (quote-expr e) ...))] + [(_ t racketinput* e ...) + (titled-interaction #:eval (make-base-eval) t racketinput* e ...)])) (define-syntax interaction (syntax-rules () - [(_ #:eval ev e ...) (titled-interaction #:eval ev #f schemeinput* e ...)] - [(_ e ...) (titled-interaction #f schemeinput* e ...)])) + [(_ #:eval ev e ...) (titled-interaction #:eval ev #f racketinput* e ...)] + [(_ e ...) (titled-interaction #f racketinput* e ...)])) - (define-syntax schemeblock+eval + (define-syntax racketblock+eval (syntax-rules () [(_ #:eval ev e ...) (let ([eva ev]) (#%expression (begin (interaction-eval #:eval eva e) ... - (schemeblock e ...))))] + (racketblock e ...))))] [(_ e ...) - (schemeblock+eval #:eval (make-base-eval) e ...)])) + (racketblock+eval #:eval (make-base-eval) e ...)])) - (define-syntax schememod+eval + (define-syntax racketmod+eval (syntax-rules () [(_ #:eval ev name e ...) (let ([eva ev]) (#%expression (begin (interaction-eval #:eval eva e) ... - (schememod name e ...))))] + (racketmod name e ...))))] [(_ name e ...) - (schememod+eval #:eval (make-base-eval) name e ...)])) + (racketmod+eval #:eval (make-base-eval) name e ...)])) (define-syntax def+int (syntax-rules () [(_ #:eval ev def e ...) (let ([eva ev]) - (column (list (schemeblock+eval #:eval eva def) + (column (list (racketblock+eval #:eval eva def) blank-line (interaction #:eval eva e ...))))] [(_ def e ...) @@ -402,7 +408,7 @@ (syntax-rules () [(_ #:eval ev [def ...] e ...) (let ([eva ev]) - (column (list (schemeblock+eval #:eval eva def ...) + (column (list (racketblock+eval #:eval eva def ...) blank-line (interaction #:eval eva e ...))))] [(_ [def ...] e ...) @@ -421,27 +427,27 @@ (define-syntax examples (syntax-rules () [(_ #:eval ev e ...) - (titled-interaction #:eval ev (pick-example-title e ...) schemeinput* e ...)] + (titled-interaction #:eval ev (pick-example-title e ...) racketinput* e ...)] [(_ e ...) - (titled-interaction (pick-example-title e ...) schemeinput* e ...)])) + (titled-interaction (pick-example-title e ...) racketinput* e ...)])) (define-syntax examples* (syntax-rules () [(_ #:eval ev example-title e ...) - (titled-interaction #:eval ev example-title schemeinput* e ...)] + (titled-interaction #:eval ev example-title racketinput* e ...)] [(_ example-title e ...) - (titled-interaction example-title schemeinput* e ...)])) + (titled-interaction example-title racketinput* e ...)])) (define-syntax defexamples (syntax-rules () [(_ #:eval ev e ...) - (titled-interaction #:eval ev (pick-example-title e ...) schemedefinput* e ...)] + (titled-interaction #:eval ev (pick-example-title e ...) racketdefinput* e ...)] [(_ e ...) - (titled-interaction (pick-example-title e ...) schemedefinput* e ...)])) + (titled-interaction (pick-example-title e ...) racketdefinput* e ...)])) (define-syntax defexamples* (syntax-rules () [(_ #:eval ev example-title e ...) - (titled-interaction #:eval ev example-title schemedefinput* e ...)] + (titled-interaction #:eval ev example-title racketdefinput* e ...)] [(_ example-title e ...) - (titled-interaction example-title schemedefinput* e ...)])) + (titled-interaction example-title racketdefinput* e ...)])) (define blank-line (make-paragraph (list 'nbsp))) diff --git a/collects/scribble/extract.ss b/collects/scribble/extract.rkt similarity index 95% rename from collects/scribble/extract.ss rename to collects/scribble/extract.rkt index 66380c78..679b8042 100644 --- a/collects/scribble/extract.ss +++ b/collects/scribble/extract.rkt @@ -23,7 +23,15 @@ [else c])) (define-for-syntax (extract orig-path stx) - (let ([path (resolve-path-spec orig-path orig-path stx)]) + (let* ([n-path (resolve-path-spec orig-path orig-path stx)] + [path (if (regexp-match? #rx#"[.]rkt$" (path->bytes n-path)) + (if (file-exists? n-path) + n-path + (let ([ss (path-replace-suffix n-path #".ss")]) + (if (file-exists? ss) + ss + n-path))) + n-path)]) (let ([s-exp (parameterize ([current-namespace (make-base-namespace)] [read-accept-reader #t] diff --git a/collects/scribble/html-properties.ss b/collects/scribble/html-properties.rkt similarity index 100% rename from collects/scribble/html-properties.ss rename to collects/scribble/html-properties.rkt diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.rkt similarity index 94% rename from collects/scribble/html-render.ss rename to collects/scribble/html-render.rkt index 3abc86fb..cf595373 100644 --- a/collects/scribble/html-render.ss +++ b/collects/scribble/html-render.rkt @@ -486,56 +486,67 @@ (table-blockss table))) (define ps ((if (nearly-top? d) values cdr) - (let flatten ([d d]) - (append* - ;; don't include the section if it's in the TOC - (if (nearly-top? d) null (list d)) - ;; get internal targets: - (append-map block-targets (part-blocks d)) - (map (lambda (p) (if (part-whole-page? p ri) null (flatten p))) - (part-parts d)))))) - (define any-parts? (ormap part? ps)) + (let flatten ([d d][prefixes null][top? #t]) + (let ([prefixes (if (and (not top?) (part-tag-prefix d)) + (cons (part-tag-prefix d) prefixes) + prefixes)]) + (append* + ;; don't include the section if it's in the TOC + (if (nearly-top? d) null (list (cons d prefixes))) + ;; get internal targets: + (map (lambda (v) (cons v prefixes)) (append-map block-targets (part-blocks d))) + (map (lambda (p) (if (part-whole-page? p ri) null (flatten p prefixes #f))) + (part-parts d))))))) + (define any-parts? (ormap (compose part? car) ps)) (if (null? ps) null `((div ([class ,box-class]) ,@(get-onthispage-label) (table ([class "tocsublist"] [cellspacing "0"]) ,@(map (lambda (p) - `(tr - (td - ,@(if (part? p) - `((span ([class "tocsublinknumber"]) - ,@(format-number - (collected-info-number - (part-collected-info p ri)) - '((tt nbsp))))) - '("")) - ,@(if (toc-element? p) - (render-content (toc-element-toc-content p) - d ri) - (parameterize ([current-no-links #t] - [extra-breaking? #t]) - `((a ([href - ,(format - "#~a" - (anchor-name - (add-current-tag-prefix - (tag-key (if (part? p) - (car (part-tags p)) - (target-element-tag p)) - ri))))] - [class - ,(cond - [(part? p) "tocsubseclink"] - [any-parts? "tocsubnonseclink"] - [else "tocsublink"])] - [pltdoc "x"]) - ,@(render-content - (if (part? p) - (or (part-title-content p) - "???") - (element-content p)) - d ri)))))))) + (let ([p (car p)] + [prefixes (cdr p)] + [add-tag-prefixes + (lambda (t prefixes) + (if (null? prefixes) + t + (cons (car t) (append prefixes (cdr t)))))]) + `(tr + (td + ,@(if (part? p) + `((span ([class "tocsublinknumber"]) + ,@(format-number + (collected-info-number + (part-collected-info p ri)) + '((tt nbsp))))) + '("")) + ,@(if (toc-element? p) + (render-content (toc-element-toc-content p) + d ri) + (parameterize ([current-no-links #t] + [extra-breaking? #t]) + `((a ([href + ,(format + "#~a" + (anchor-name + (add-tag-prefixes + (tag-key (if (part? p) + (car (part-tags p)) + (target-element-tag p)) + ri) + prefixes)))] + [class + ,(cond + [(part? p) "tocsubseclink"] + [any-parts? "tocsubnonseclink"] + [else "tocsublink"])] + [pltdoc "x"]) + ,@(render-content + (if (part? p) + (or (part-title-content p) + "???") + (element-content p)) + d ri))))))))) ps)))))))) (define/public (extract-part-body-id d ri) diff --git a/collects/scribble/info.ss b/collects/scribble/info.rkt similarity index 65% rename from collects/scribble/info.ss rename to collects/scribble/info.rkt index a135983a..5d0130f0 100644 --- a/collects/scribble/info.ss +++ b/collects/scribble/info.rkt @@ -3,3 +3,7 @@ (define mzscheme-launcher-names '("scribble")) (define mzscheme-launcher-libraries '("run.ss")) (define compile-omit-paths '("test-reader.ss")) + +(define raco-commands + '(("scribble" scribble/run "render a Scribble document" #f))) + diff --git a/collects/scribble/jfp.ss b/collects/scribble/jfp.rkt similarity index 100% rename from collects/scribble/jfp.ss rename to collects/scribble/jfp.rkt diff --git a/collects/scribble/jfp/lang.ss b/collects/scribble/jfp/lang.rkt similarity index 100% rename from collects/scribble/jfp/lang.ss rename to collects/scribble/jfp/lang.rkt diff --git a/collects/scribble/jfp/lang/reader.rkt b/collects/scribble/jfp/lang/reader.rkt new file mode 100644 index 00000000..09e0da56 --- /dev/null +++ b/collects/scribble/jfp/lang/reader.rkt @@ -0,0 +1,3 @@ +#lang s-exp scribble/base/reader +scribble/jfp/lang +#:wrapper1 (lambda (t) (cons 'doc (t))) diff --git a/collects/scribble/jfp/lang/reader.ss b/collects/scribble/jfp/lang/reader.ss deleted file mode 100644 index 1f0c6c29..00000000 --- a/collects/scribble/jfp/lang/reader.ss +++ /dev/null @@ -1,15 +0,0 @@ -#lang s-exp syntax/module-reader - -scribble/jfp/lang - -#:read scribble:read-inside -#:read-syntax scribble:read-syntax-inside -#:whole-body-readers? #t -#:wrapper1 (lambda (t) (cons 'doc (t))) -#:info (lambda (key defval default) - (case key - [(color-lexer) - (dynamic-require 'syntax-color/scribble-lexer 'scribble-inside-lexer)] - [else (default key defval)])) - -(require (prefix-in scribble: "../../reader.ss")) diff --git a/collects/scribble/latex-properties.ss b/collects/scribble/latex-properties.rkt similarity index 100% rename from collects/scribble/latex-properties.ss rename to collects/scribble/latex-properties.rkt diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.rkt similarity index 100% rename from collects/scribble/latex-render.ss rename to collects/scribble/latex-render.rkt diff --git a/collects/scribble/lp-include.ss b/collects/scribble/lp-include.rkt similarity index 100% rename from collects/scribble/lp-include.ss rename to collects/scribble/lp-include.rkt diff --git a/collects/scribble/lp.ss b/collects/scribble/lp.rkt similarity index 100% rename from collects/scribble/lp.ss rename to collects/scribble/lp.rkt diff --git a/collects/scribble/lp/lang/lang.ss b/collects/scribble/lp/lang/lang.rkt similarity index 100% rename from collects/scribble/lp/lang/lang.ss rename to collects/scribble/lp/lang/lang.rkt diff --git a/collects/scribble/lp/lang/reader.rkt b/collects/scribble/lp/lang/reader.rkt new file mode 100644 index 00000000..4ddadb03 --- /dev/null +++ b/collects/scribble/lp/lang/reader.rkt @@ -0,0 +1,16 @@ +#lang s-exp syntax/module-reader + +scribble/lp/lang/lang + +#:read read-inside +#:read-syntax read-syntax-inside +#:whole-body-readers? #t +#:info (scribble-base-info) +#:language-info (scribble-base-language-info) + +(require scribble/reader + (only-in scribble/base/reader + scribble-base-info + scribble-base-language-info)) + + diff --git a/collects/scribble/lp/lang/reader.ss b/collects/scribble/lp/lang/reader.ss deleted file mode 100644 index adef6745..00000000 --- a/collects/scribble/lp/lang/reader.ss +++ /dev/null @@ -1,9 +0,0 @@ -#lang s-exp syntax/module-reader - -scribble/lp/lang/lang - -#:read read-inside -#:read-syntax read-syntax-inside -#:whole-body-readers? #t - -(require scribble/reader) diff --git a/collects/scribble/manual-struct.ss b/collects/scribble/manual-struct.rkt similarity index 100% rename from collects/scribble/manual-struct.ss rename to collects/scribble/manual-struct.rkt diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.rkt similarity index 86% rename from collects/scribble/manual.ss rename to collects/scribble/manual.rkt index 960b4cd8..d84a5bf7 100644 --- a/collects/scribble/manual.ss +++ b/collects/scribble/manual.rkt @@ -23,8 +23,9 @@ "private/manual-bib.ss" "private/manual-form.ss" "private/manual-class.ss" - "private/manual-unit.ss" - "private/manual-vars.ss") + "private/manual-unit.ss") + (except-out (all-from-out "private/manual-vars.ss") + *deftogether) (except-out (all-from-out "private/manual-proc.ss") *defthing)) diff --git a/collects/scribble/manual/lang.ss b/collects/scribble/manual/lang.rkt similarity index 100% rename from collects/scribble/manual/lang.ss rename to collects/scribble/manual/lang.rkt diff --git a/collects/scribble/manual/lang/reader.rkt b/collects/scribble/manual/lang/reader.rkt new file mode 100644 index 00000000..ec831697 --- /dev/null +++ b/collects/scribble/manual/lang/reader.rkt @@ -0,0 +1,3 @@ +#lang s-exp scribble/base/reader +scribble/manual/lang +#:wrapper1 (lambda (t) (cons 'doc (t))) diff --git a/collects/scribble/manual/lang/reader.ss b/collects/scribble/manual/lang/reader.ss deleted file mode 100644 index 4a8dc4b5..00000000 --- a/collects/scribble/manual/lang/reader.ss +++ /dev/null @@ -1,17 +0,0 @@ -#lang s-exp syntax/module-reader - -scribble/manual/lang - -#:read scribble:read-inside -#:read-syntax scribble:read-syntax-inside -#:whole-body-readers? #t -#:wrapper1 (lambda (t) (cons 'doc (t))) -#:info (lambda (key defval default) - (case key - [(color-lexer) - (dynamic-require 'syntax-color/scribble-lexer 'scribble-inside-lexer)] - [(drscheme:toolbar-buttons) - (dynamic-require 'scribble/tools/drscheme-buttons 'drscheme-buttons)] - [else (default key defval)])) - -(require (prefix-in scribble: "../../reader.ss")) diff --git a/collects/scribble/pdf-render.ss b/collects/scribble/pdf-render.rkt similarity index 100% rename from collects/scribble/pdf-render.ss rename to collects/scribble/pdf-render.rkt diff --git a/collects/scribble/private/defaults.ss b/collects/scribble/private/defaults.rkt similarity index 100% rename from collects/scribble/private/defaults.ss rename to collects/scribble/private/defaults.rkt diff --git a/collects/scribble/private/indirect-renderer.ss b/collects/scribble/private/indirect-renderer.rkt similarity index 100% rename from collects/scribble/private/indirect-renderer.ss rename to collects/scribble/private/indirect-renderer.rkt diff --git a/collects/scribble/private/lp.ss b/collects/scribble/private/lp.rkt similarity index 100% rename from collects/scribble/private/lp.ss rename to collects/scribble/private/lp.rkt diff --git a/collects/scribble/private/manual-bib.ss b/collects/scribble/private/manual-bib.rkt similarity index 100% rename from collects/scribble/private/manual-bib.ss rename to collects/scribble/private/manual-bib.rkt diff --git a/collects/scribble/private/manual-bind.ss b/collects/scribble/private/manual-bind.rkt similarity index 100% rename from collects/scribble/private/manual-bind.ss rename to collects/scribble/private/manual-bind.rkt diff --git a/collects/scribble/private/manual-class.ss b/collects/scribble/private/manual-class.rkt similarity index 100% rename from collects/scribble/private/manual-class.ss rename to collects/scribble/private/manual-class.rkt diff --git a/collects/scribble/private/manual-ex.ss b/collects/scribble/private/manual-ex.rkt similarity index 100% rename from collects/scribble/private/manual-ex.ss rename to collects/scribble/private/manual-ex.rkt diff --git a/collects/scribble/private/manual-form.ss b/collects/scribble/private/manual-form.rkt similarity index 91% rename from collects/scribble/private/manual-form.ss rename to collects/scribble/private/manual-form.rkt index f73671fd..f0ab889a 100644 --- a/collects/scribble/private/manual-form.ss +++ b/collects/scribble/private/manual-form.rkt @@ -20,12 +20,14 @@ (provide defform defform* defform/subs defform*/subs defform/none - defidform + defidform defidform/inline specform specform/subs specsubform specsubform/subs specspecsubform specspecsubform/subs specsubform/inline defsubform defsubform* - schemegrammar schemegrammar* + racketgrammar racketgrammar* + (rename-out [racketgrammar schemegrammar] + [racketgrammar* schemegrammar*]) var svar) (define-syntax (defform*/subs stx) @@ -171,6 +173,12 @@ (syntax/loc stx (fm #:literals () spec desc ...))])) +(define-syntax (defidform/inline stx) + (syntax-case stx () + [(_ id) + (identifier? #'id) + #'(defform-site (quote-syntax id))])) + (define-syntax (defidform stx) (syntax-case stx () [(_ spec-id desc ...) @@ -269,32 +277,32 @@ ([form/maybe (#f spec)]) (*specsubform 'spec null #f null null null (lambda () (list desc ...))))) -(define-syntax schemegrammar +(define-syntax racketgrammar (syntax-rules () [(_ #:literals (lit ...) id clause ...) (with-scheme-variables (lit ...) ([non-term (id clause ...)]) - (*schemegrammar '(lit ...) + (*racketgrammar '(lit ...) '(id clause ...) (lambda () (list (list (scheme id) (schemeblock0/form clause) ...)))))] - [(_ id clause ...) (schemegrammar #:literals () id clause ...)])) + [(_ id clause ...) (racketgrammar #:literals () id clause ...)])) -(define-syntax schemegrammar* +(define-syntax racketgrammar* (syntax-rules () [(_ #:literals (lit ...) [id clause ...] ...) (with-scheme-variables (lit ...) ([non-term (id clause ...)] ...) - (*schemegrammar '(lit ...) + (*racketgrammar '(lit ...) '(id ... clause ... ...) (lambda () (list (list (scheme id) (schemeblock0/form clause) ...) ...))))] [(_ [id clause ...] ...) - (schemegrammar* #:literals () [id clause ...] ...)])) + (racketgrammar* #:literals () [id clause ...] ...)])) (define-syntax-rule (var id) (*var 'id)) @@ -305,6 +313,29 @@ (define (meta-symbol? s) (memq s '(... ...+ ?))) +(define (defform-site kw-id) + (let ([target-maker (id-to-form-target-maker kw-id #t)] + [content (list (definition-site (syntax-e kw-id) + kw-id #t))]) + (if target-maker + (target-maker + content + (lambda (tag) + (make-toc-target-element + #f + (if kw-id + (list (make-index-element + #f content tag + (list (symbol->string (syntax-e kw-id))) + content + (with-exporting-libraries + (lambda (libs) + (make-form-index-desc (syntax-e kw-id) + libs))))) + content) + tag))) + (car content)))) + (define (*defforms kw-id forms form-procs subs sub-procs contract-procs content-thunk) (parameterize ([current-meta-list '(... ...+)]) (make-box-splice @@ -323,27 +354,7 @@ (list (to-element `(,x . ,(cdr form))))))) (and kw-id (eq? form (car forms)) - (let ([target-maker (id-to-form-target-maker kw-id #t)] - [content (list (definition-site (syntax-e kw-id) - kw-id #t))]) - (if target-maker - (target-maker - content - (lambda (tag) - (make-toc-target-element - #f - (if kw-id - (list (make-index-element - #f content tag - (list (symbol->string (syntax-e kw-id))) - content - (with-exporting-libraries - (lambda (libs) - (make-form-index-desc (syntax-e kw-id) - libs))))) - content) - tag))) - (car content))))))))) + (defform-site kw-id))))))) forms form-procs) (if (null? sub-procs) null @@ -409,7 +420,7 @@ (define (*schemerawgrammar style nonterm clause1 . clauses) (*schemerawgrammars style (list nonterm) (list (cons clause1 clauses)))) -(define (*schemegrammar lits s-expr clauseses-thunk) +(define (*racketgrammar lits s-expr clauseses-thunk) (let ([l (clauseses-thunk)]) (*schemerawgrammars #f (map (lambda (x) diff --git a/collects/scribble/private/manual-method.ss b/collects/scribble/private/manual-method.rkt similarity index 100% rename from collects/scribble/private/manual-method.ss rename to collects/scribble/private/manual-method.rkt diff --git a/collects/scribble/private/manual-mod.ss b/collects/scribble/private/manual-mod.rkt similarity index 100% rename from collects/scribble/private/manual-mod.ss rename to collects/scribble/private/manual-mod.rkt diff --git a/collects/scribble/private/manual-proc.ss b/collects/scribble/private/manual-proc.rkt similarity index 64% rename from collects/scribble/private/manual-proc.ss rename to collects/scribble/private/manual-proc.rkt index 9b8f4bb5..076a30d9 100644 --- a/collects/scribble/private/manual-proc.ss +++ b/collects/scribble/private/manual-proc.rkt @@ -1,4 +1,4 @@ -#lang scheme/base +#lang racket/base (require "../decode.ss" "../struct.ss" "../scheme.ss" @@ -16,11 +16,11 @@ "on-demand.ss" scheme/string scheme/list - (for-syntax scheme/base) - (for-label scheme/base - scheme/class)) + (for-syntax racket/base) + (for-label racket/base + racket/class)) -(provide defproc defproc* defstruct +(provide defproc defproc* defstruct defstruct* defparam defparam* defboolparam defthing defthing* defthing/proc ; XXX unknown contract @@ -485,42 +485,90 @@ ;; ---------------------------------------- -(define-syntax defstruct - (syntax-rules () - [(_ name fields #:mutable #:inspector #f desc ...) - (**defstruct name fields #f #t #f desc ...)] - [(_ name fields #:mutable #:transparent desc ...) - (**defstruct name fields #f #t #f desc ...)] - [(_ name fields #:mutable #:prefab desc ...) - (**defstruct name fields #f #t #t desc ...)] - [(_ name fields #:mutable desc ...) - (**defstruct name fields #f #f #f desc ...)] - [(_ name fields #:inspector #f desc ...) - (**defstruct name fields #t #t #f desc ...)] - [(_ name fields #:transparent desc ...) - (**defstruct name fields #t #t #f desc ...)] - [(_ name fields #:prefab desc ...) - (**defstruct name fields #t #t #t desc ...)] - [(_ name fields desc ...) - (**defstruct name fields #t #f #f desc ...)])) +(define-syntax-rule (define-defstruct defstruct default-cname) + (... + (define-syntax defstruct + (syntax-rules () + [(_ name fields #:constructor-name cname #:mutable #:inspector #f desc ...) + (**defstruct name fields #f #t #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:mutable #:inspector #f desc ...) + (**defstruct name fields #f #t #f cname #t desc ...)] + [(_ name fields #:mutable #:inspector #f desc ...) + (**defstruct name fields #f #t #f default-cname #t desc ...)] + [(_ name fields #:constructor-name cname #:mutable #:transparent desc ...) + (**defstruct name fields #f #t #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:mutable #:transparent desc ...) + (**defstruct name fields #f #t #f cname #t desc ...)] + [(_ name fields #:mutable #:transparent desc ...) + (**defstruct name fields #f #t #f default-cname #t desc ...)] + [(_ name fields #:constructor-name cname #:mutable #:prefab desc ...) + (**defstruct name fields #f #t #t cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:mutable #:prefab desc ...) + (**defstruct name fields #f #t #t cname #t desc ...)] + [(_ name fields #:mutable #:prefab desc ...) + (**defstruct name fields #f #t #t default-cname #t desc ...)] + [(_ name fields #:constructor-name cname #:mutable desc ...) + (**defstruct name fields #f #f #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:mutable desc ...) + (**defstruct name fields #f #f #f cname #t desc ...)] + [(_ name fields #:mutable desc ...) + (**defstruct name fields #f #f #f default-cname #f desc ...)] + [(_ name fields #:constructor-name cname #:inspector #f desc ...) + (**defstruct name fields #t #t #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:inspector #f desc ...) + (**defstruct name fields #t #t #f cname #t desc ...)] + [(_ name fields #:inspector #f desc ...) + (**defstruct name fields #t #t #f default-cname #t desc ...)] + [(_ name fields #:constructor-name cname #:transparent desc ...) + (**defstruct name fields #t #t #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:transparent desc ...) + (**defstruct name fields #t #t #f cname #t desc ...)] + [(_ name fields #:transparent desc ...) + (**defstruct name fields #t #t #f default-cname #t desc ...)] + [(_ name fields #:constructor-name cname #:prefab desc ...) + (**defstruct name fields #t #t #t cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname #:prefab desc ...) + (**defstruct name fields #t #t #t cname #t desc ...)] + [(_ name fields #:prefab desc ...) + (**defstruct name fields #t #t #t default-cname #t desc ...)] + [(_ name fields #:constructor-name cname desc ...) + (**defstruct name fields #t #f #f cname #f desc ...)] + [(_ name fields #:extra-constructor-name cname desc ...) + (**defstruct name fields #t #f #f cname #t desc ...)] + [(_ name fields desc ...) + (**defstruct name fields #t #f #f default-cname #t desc ...)])))) + +(define-defstruct defstruct #t) +(define-defstruct defstruct* #f) (define-syntax-rule (**defstruct name ([field field-contract] ...) immutable? - transparent? prefab? desc ...) + transparent? prefab? cname extra-cname? desc ...) (with-togetherable-scheme-variables () () - (*defstruct (quote-syntax/loc name) 'name + (*defstruct (quote-syntax/loc name) 'name (quote-syntax/loc cname) extra-cname? '([field field-contract] ...) (list (lambda () (schemeblock0 field-contract)) ...) immutable? transparent? prefab? (lambda () (list desc ...))))) -(define (*defstruct stx-id name fields field-contracts immutable? transparent? prefab? +(define (*defstruct stx-id name alt-cname-id extra-cname? + fields field-contracts immutable? transparent? prefab? content-thunk) (define (field-name f) ((if (pair? (car f)) caar car) f)) (define (field-view f) (if (pair? (car f)) (make-shaped-parens (car f) #\[) (car f))) - (make-box-splice - (cons + (define cname-id + (cond + [(identifier? alt-cname-id) alt-cname-id] + [(not (syntax-e alt-cname-id)) #f] + [else (let ([name-id (if (identifier? stx-id) + stx-id + (car (syntax-e stx-id)))]) + (datum->syntax name-id + (string->symbol (format "make-~a" (syntax-e name-id))) + name-id + name-id))])) + (define main-table (make-table 'boxed (cons @@ -543,8 +591,10 @@ (list* (list 'info name) (list 'type 'struct: name) (list 'predicate name '?) - (list 'constructor 'make- name) (append + (if cname-id + (list (list 'constructor (syntax-e cname-id))) + null) (map (lambda (f) (list 'accessor name '- (field-name f))) @@ -560,11 +610,15 @@ #f)) fields)))))]) (if (pair? name) - (to-element (list just-name - (make-just-context - (cadr name) - (cadr (syntax-e stx-id))))) - just-name))] + (make-element + #f + (list just-name + (hspace 1) + (to-element + (make-just-context + (cadr name) + (cadr (syntax-e stx-id)))))) + just-name))] [short-width (apply + (length fields) 8 (append @@ -580,93 +634,111 @@ fields)))]) (if (and (short-width . < . max-proto-width) immutable? - (not transparent?)) + (not transparent?) + (not cname-id)) (make-omitable-paragraph (list (to-element - `(,(schemeparenfont "struct") + `(,(scheme struct) ,the-name ,(map field-view fields))))) - (make-table - #f - (append - (list - (list (to-flow (schemeparenfont "(struct")) - flow-spacer - (to-flow the-name) - (if (or (null? fields) - (short-width . < . max-proto-width)) - flow-spacer - (to-flow (make-element - #f (list spacer (schemeparenfont "("))))) - (to-flow (if (or (null? fields) - (short-width . < . max-proto-width)) - (make-element - #f (cons (to-element (map field-view - fields)) - (if (and immutable? - (not transparent?)) - (list (schemeparenfont ")")) - null))) - (to-element (field-view (car fields))))))) - (if (short-width . < . max-proto-width) - null - (let loop ([fields (if (null? fields) - fields (cdr fields))]) - (if (null? fields) + (let* ([one-right-column? + (or (null? fields) + (short-width . < . max-proto-width))] + [a-right-column + (lambda (c) + (if one-right-column? + (list flow-spacer flow-spacer c) + (list flow-spacer flow-spacer c 'cont 'cont)))]) + (make-table + #f + (append + (list + (append + (list (to-flow (make-element #f + (list + (schemeparenfont "(") + (scheme struct)))) + flow-spacer) + (if one-right-column? + (list (to-flow (make-element + #f + (list* the-name + spacer + (to-element (map field-view + fields)) + (if (and immutable? + (not transparent?) + (not cname-id)) + (list (schemeparenfont ")")) + null))))) + (list (to-flow the-name) + (to-flow (make-element + #f (list spacer (schemeparenfont "(")))) + (to-flow (to-element (field-view (car fields)))))))) + (if (short-width . < . max-proto-width) null - (cons - (let ([fld (car fields)]) - (list flow-spacer flow-spacer - flow-spacer flow-spacer - (to-flow - (let ([e (to-element (field-view fld))]) - (if (null? (cdr fields)) - (make-element - #f - (list e (schemeparenfont - (if (and immutable? - (not transparent?)) - "))" ")")))) - e))))) - (loop (cdr fields)))))) - (cond - [(and (not immutable?) transparent?) - (list - (list flow-spacer flow-spacer - (to-flow (to-element '#:mutable)) - 'cont - 'cont) - (list flow-spacer flow-spacer - (to-flow (make-element - #f - (list (if prefab? - (to-element '#:prefab) - (to-element '#:transparent)) - (schemeparenfont ")")))) - 'cont - 'cont))] - [(not immutable?) - (list - (list flow-spacer flow-spacer - (to-flow (make-element - #f - (list (to-element '#:mutable) - (schemeparenfont ")")))) - 'cont - 'cont))] - [transparent? - (list - (list flow-spacer flow-spacer - (to-flow (make-element - #f - (list (if prefab? - (to-element '#:prefab) - (to-element '#:transparent)) - (schemeparenfont ")")))) - 'cont - 'cont))] - [else null])))))))) + (let loop ([fields (if (null? fields) + fields (cdr fields))]) + (if (null? fields) + null + (cons + (let ([fld (car fields)]) + (list flow-spacer flow-spacer + flow-spacer flow-spacer + (to-flow + (let ([e (to-element (field-view fld))]) + (if (null? (cdr fields)) + (make-element + #f + (list e (schemeparenfont + (if (and immutable? + (not transparent?) + (not cname-id)) + "))" + ")")))) + e))))) + (loop (cdr fields)))))) + (if cname-id + (list (a-right-column + (to-flow (make-element + #f + (append + (list (to-element (if extra-cname? + '#:extra-constructor-name + '#:constructor-name)) + (hspace 1) + (to-element cname-id)) + (if (and immutable? + (not transparent?)) + (list (schemeparenfont ")")) + null)))))) + null) + (cond + [(and (not immutable?) transparent?) + (list + (a-right-column (to-flow (to-element '#:mutable))) + (a-right-column (to-flow (make-element + #f + (list (if prefab? + (to-element '#:prefab) + (to-element '#:transparent)) + (schemeparenfont ")"))))))] + [(not immutable?) + (list + (a-right-column (to-flow (make-element + #f + (list (to-element '#:mutable) + (schemeparenfont ")"))))))] + [transparent? + (list + (a-right-column (to-flow (make-element + #f + (list (if prefab? + (to-element '#:prefab) + (to-element '#:transparent)) + (schemeparenfont ")"))))))] + [else null]))))))))) (map (lambda (v field-contract) (cond [(pair? v) @@ -681,7 +753,10 @@ flow-spacer (make-flow (list (field-contract))))))))] [else null])) - fields field-contracts))) + fields field-contracts)))) + (make-box-splice + (cons + main-table (content-thunk)))) ;; ---------------------------------------- @@ -702,49 +777,87 @@ (list (schemeblock0 result) ...) (lambda () (list desc ...))))) -(define (*defthing stx-ids names form? result-contracts content-thunk) +(define (*defthing stx-ids names form? result-contracts content-thunk + [result-values (map (lambda (x) #f) result-contracts)]) (make-box-splice (cons (make-table 'boxed (map - (lambda (stx-id name result-contract) + (lambda (stx-id name result-contract result-value) (list (make-flow (make-table-if-necessary "argcontract" - (list + (let* ([result-block + (and result-value + (if (block? result-value) + result-value + (make-omitable-paragraph (list result-value))))] + [contract-block + (if (block? result-contract) + result-contract + (make-omitable-paragraph (list result-contract)))] + [total-width (+ (string-length (format "~a" name)) + 3 + (block-width contract-block) + (if result-block + (+ (block-width result-block) 3) + 0))]) + (append (list - (make-flow + (append (list - (make-omitable-paragraph + (make-flow (list - (let ([target-maker - ((if form? id-to-form-target-maker id-to-target-maker) - stx-id #t)] - [content (list (definition-site name stx-id form?))]) - (if target-maker - (target-maker - content - (lambda (tag) - (make-toc-target-element - #f - (list - (make-index-element - #f - content - tag - (list (symbol->string name)) - content - (with-exporting-libraries - (lambda (libs) (make-thing-index-desc name libs))))) - tag))) - (car content))) - spacer ":" spacer)))) - (make-flow (list (if (block? result-contract) - result-contract - (make-omitable-paragraph (list result-contract))))))))))) - stx-ids names result-contracts)) + (make-omitable-paragraph + (list + (let ([target-maker + ((if form? id-to-form-target-maker id-to-target-maker) + stx-id #t)] + [content (list (definition-site name stx-id form?))]) + (if target-maker + (target-maker + content + (lambda (tag) + (make-toc-target-element + #f + (list + (make-index-element + #f + content + tag + (list (symbol->string name)) + content + (with-exporting-libraries + (lambda (libs) (make-thing-index-desc name libs))))) + tag))) + (car content))))))) + (make-flow + (list + (make-omitable-paragraph + (list + spacer ":" spacer)))) + (make-flow (list contract-block))) + (if (and result-value + (total-width . < . 60)) + (list + (to-flow (make-element #f (list spacer "=" spacer))) + (make-flow (list result-block))) + null))) + (if (and result-value + (total-width . >= . 60)) + (list + (list + (make-table-if-necessary + "argcontract" + (list + (list flow-spacer + (to-flow (make-element #f (list spacer "=" spacer))) + (make-flow (list result-block))))) + 'cont)) + null))))))) + stx-ids names result-contracts result-values)) (content-thunk)))) (define (defthing/proc id contract descs) diff --git a/collects/scribble/private/manual-scheme.ss b/collects/scribble/private/manual-scheme.rkt similarity index 52% rename from collects/scribble/private/manual-scheme.ss rename to collects/scribble/private/manual-scheme.rkt index 4e1bf23a..016a2afd 100644 --- a/collects/scribble/private/manual-scheme.ss +++ b/collects/scribble/private/manual-scheme.rkt @@ -1,38 +1,57 @@ -#lang scheme/base +#lang racket/base (require "../decode.ss" "../struct.ss" "../scheme.ss" "../search.ss" "../basic.ss" - scheme/list + racket/list "manual-utils.ss" "manual-style.ss" - (for-syntax scheme/base) - (for-label scheme/base)) + (for-syntax racket/base) + (for-label racket/base)) -(provide schemeblock SCHEMEBLOCK schemeblock/form - schemeblock0 SCHEMEBLOCK0 schemeblock0/form - schemeblockelem - schemeinput - schememod - scheme SCHEME scheme/form schemeresult schemeid - schememodname - schememodlink indexed-scheme - schemelink) +(provide racketblock RACKETBLOCK racketblock/form + racketblock0 RACKETBLOCK0 racketblock0/form + racketblockelem + racketinput + racketmod + racket RACKET racket/form racketresult racketid + racketmodname + racketmodlink indexed-racket + racketlink + + (rename-out [racketblock schemeblock] + [RACKETBLOCK SCHEMEBLOCK] + [racketblock/form schemeblock/form] + [racketblock0 schemeblock0] + [RACKETBLOCK0 SCHEMEBLOCK0] + [racketblock0/form schemeblock0/form] + [racketblockelem schemeblockelem] + [racketinput schemeinput] + [racketmod schememod] + [racket scheme] + [RACKET SCHEME] + [racket/form scheme/form] + [racketresult schemeresult] + [racketid schemeid] + [racketmodname schememodname] + [racketmodlink schememodlink] + [indexed-racket indexed-scheme] + [racketlink schemelink])) -(define-code schemeblock0 to-paragraph) -(define-code schemeblock (to-paragraph/prefix (hspace 2) (hspace 2) "")) -(define-code SCHEMEBLOCK (to-paragraph/prefix (hspace 2) (hspace 2) "") +(define-code racketblock0 to-paragraph) +(define-code racketblock (to-paragraph/prefix (hspace 2) (hspace 2) "")) +(define-code RACKETBLOCK (to-paragraph/prefix (hspace 2) (hspace 2) "") UNSYNTAX) -(define-code SCHEMEBLOCK0 to-paragraph UNSYNTAX) +(define-code RACKETBLOCK0 to-paragraph UNSYNTAX) (define interaction-prompt (make-element 'tt (list "> " ))) -(define-code schemeinput +(define-code racketinput (to-paragraph/prefix (make-element #f (list (hspace 2) interaction-prompt)) (hspace 4) "")) -(define-syntax (schememod stx) +(define-syntax (racketmod stx) (syntax-case stx () [(_ #:file filename lang rest ...) (with-syntax ([modtag (datum->syntax @@ -41,9 +60,11 @@ #f (list (hash-lang) spacer - (as-modname-link - ',#'lang - (to-element ',#'lang))))) + ,(if (identifier? #'lang) + `(as-modname-link + ',#'lang + (to-element ',#'lang)) + #'(racket lang))))) #'lang)] [(file ...) (if (syntax-e #'filename) @@ -53,9 +74,9 @@ `(code:comment (unsyntax (t "In \"" ,(syntax-e #'filename) "\":"))) #'filename)) null)]) - (syntax/loc stx (schemeblock file ... modtag rest ...)))] + (syntax/loc stx (racketblock file ... modtag rest ...)))] [(_ lang rest ...) - (syntax/loc stx (schememod #:file #f lang rest ...))])) + (syntax/loc stx (racketmod #:file #f lang rest ...))])) (define (to-element/result s) (make-element result-color (list (to-element/no-color s)))) @@ -89,25 +110,25 @@ (make-shaped-parens s val) s)) -(define-code schemeblockelem to-element) +(define-code racketblockelem to-element) -(define-code scheme to-element unsyntax keep-s-expr add-sq-prop) -(define-code SCHEME to-element UNSYNTAX keep-s-expr add-sq-prop) -(define-code schemeresult to-element/result unsyntax keep-s-expr add-sq-prop) -(define-code schemeid to-element/id unsyntax keep-s-expr add-sq-prop) -(define-code *schememodname to-element unsyntax keep-s-expr add-sq-prop) +(define-code racket to-element unsyntax keep-s-expr add-sq-prop) +(define-code RACKET to-element UNSYNTAX keep-s-expr add-sq-prop) +(define-code racketresult to-element/result unsyntax keep-s-expr add-sq-prop) +(define-code racketid to-element/id unsyntax keep-s-expr add-sq-prop) +(define-code *racketmodname to-element unsyntax keep-s-expr add-sq-prop) -(define-syntax schememodname +(define-syntax racketmodname (syntax-rules (unsyntax) - [(schememodname #,n) + [(racketmodname #,n) (let ([sym n]) (as-modname-link sym (to-element sym)))] - [(schememodname n) - (as-modname-link 'n (*schememodname n))])) + [(racketmodname n) + (as-modname-link 'n (*racketmodname n))])) -(define-syntax schememodlink +(define-syntax racketmodlink (syntax-rules (unsyntax) - [(schememodlink n content ...) + [(racketmodlink n content ...) (*as-modname-link 'n (elem #:style #f content ...))])) (define (as-modname-link s e) @@ -120,10 +141,10 @@ (list e) `(mod-path ,(format "~s" s)))) -(define-syntax-rule (indexed-scheme x) - (add-scheme-index 'x (scheme x))) +(define-syntax-rule (indexed-racket x) + (add-racket-index 'x (racket x))) -(define (add-scheme-index s e) +(define (add-racket-index s e) (let ([k (cond [(and (pair? s) (eq? (car s) 'quote)) (format "~s" (cadr s))] [(string? s) s] [else (format "~s" s)])]) @@ -137,11 +158,11 @@ #'(let ([ellipses #f]) (base a)))]))) -(define-/form schemeblock0/form schemeblock0) -(define-/form schemeblock/form schemeblock) -(define-/form scheme/form scheme) +(define-/form racketblock0/form racketblock0) +(define-/form racketblock/form racketblock) +(define-/form racket/form racket) -(define (*schemelink stx-id id . s) +(define (*racketlink stx-id id . s) (let ([content (decode-content s)]) (make-delayed-element (lambda (r p ri) @@ -149,11 +170,11 @@ (make-link-element #f content - (or (find-scheme-tag p ri stx-id #f) + (or (find-racket-tag p ri stx-id #f) `(undef ,(format "--UNDEFINED:~a--" (syntax-e stx-id))))))) (lambda () content) (lambda () content)))) -(define-syntax-rule (schemelink id . content) - (*schemelink (quote-syntax id) 'id . content)) +(define-syntax-rule (racketlink id . content) + (*racketlink (quote-syntax id) 'id . content)) diff --git a/collects/scribble/private/manual-sprop.ss b/collects/scribble/private/manual-sprop.rkt similarity index 100% rename from collects/scribble/private/manual-sprop.ss rename to collects/scribble/private/manual-sprop.rkt diff --git a/collects/scribble/private/manual-style.ss b/collects/scribble/private/manual-style.rkt similarity index 81% rename from collects/scribble/private/manual-style.ss rename to collects/scribble/private/manual-style.rkt index 14ed9193..5c7087aa 100644 --- a/collects/scribble/private/manual-style.ss +++ b/collects/scribble/private/manual-style.rkt @@ -1,4 +1,4 @@ -#lang scheme/base +#lang racket/base (require "../decode.ss" "../struct.ss" "../base.ss" @@ -7,9 +7,9 @@ (only-in "../core.ss" make-style plain) "manual-utils.ss" "on-demand.ss" - scheme/list - scheme/contract - scheme/string) + racket/list + racket/contract + racket/string) (provide (rename-out [hyperlink link]) (rename-out [other-doc other-manual]) @@ -23,12 +23,26 @@ (() () #:rest (listof pre-content?) . ->* . element?)) (define-syntax-rule (provide-styling id ...) (provide/contract [id styling-f/c] ...)) -(provide-styling schememodfont schemeoutput - schemeerror schemefont schemevalfont schemeresultfont schemeidfont schemevarfont - schemeparenfont schemekeywordfont schememetafont +(provide-styling racketmodfont racketoutput + racketerror racketfont racketvalfont racketresultfont racketidfont racketvarfont + racketparenfont racketkeywordfont racketmetafont onscreen defterm filepath exec envvar Flag DFlag PFlag DPFlag math procedure indexed-file indexed-envvar idefterm pidefterm) +(define-syntax-rule (provide-scheme-styling [rid sid] ...) + (provide/contract [rename rid sid styling-f/c] ...)) +(provide-scheme-styling [racketmodfont schememodfont] + [racketoutput schemeoutput] + [racketerror schemeerror] + [racketfont schemefont] + [racketvalfont schemevalfont] + [racketresultfont schemeresultfont] + [racketidfont schemeidfont] + [racketvarfont schemevarfont] + [racketparenfont schemeparenfont] + [racketkeywordfont schemekeywordfont] + [racketmetafont schememetafont]) + (provide void-const undefined-const) (provide/contract @@ -68,23 +82,23 @@ (define (idefterm . str) (let ([c (decode-content str)]) (make-element 'italic c))) -(define (schemefont . str) +(define (racketfont . str) (apply tt str)) -(define (schemevalfont . str) +(define (racketvalfont . str) (make-element value-color (decode-content str))) -(define (schemeresultfont . str) +(define (racketresultfont . str) (make-element result-color (decode-content str))) -(define (schemeidfont . str) +(define (racketidfont . str) (make-element symbol-color (decode-content str))) -(define (schemevarfont . str) +(define (racketvarfont . str) (make-element variable-color (decode-content str))) -(define (schemeparenfont . str) +(define (racketparenfont . str) (make-element paren-color (decode-content str))) -(define (schememetafont . str) +(define (racketmetafont . str) (make-element meta-color (decode-content str))) -(define (schememodfont . str) +(define (racketmodfont . str) (make-element module-color (decode-content str))) -(define (schemekeywordfont . str) +(define (racketkeywordfont . str) (make-element keyword-color (decode-content str))) (define (filepath . str) (make-element 'tt (append (list "\"") (decode-content str) (list "\"")))) @@ -124,9 +138,9 @@ (define (procedure . str) (make-element result-color `("#"))) -(define (schemeoutput . str) +(define (racketoutput . str) (make-element output-color (decode-content str))) -(define (schemeerror . str) +(define (racketerror . str) (make-element error-color (decode-content str))) (define (t . str) @@ -150,13 +164,13 @@ (define (hash-lang) (make-link-element module-link-color - (list (schememodfont "#lang")) + (list (racketmodfont "#lang")) `(part ,(doc-prefix '(lib "scribblings/guide/guide.scrbl") "hash-lang")))) (define-on-demand void-const - (schemeresultfont "#")) + (racketresultfont "#")) (define-on-demand undefined-const - (schemeresultfont "#")) + (racketresultfont "#")) (define (link url #:underline? [underline? #t] diff --git a/collects/scribble/private/manual-tech.ss b/collects/scribble/private/manual-tech.rkt similarity index 100% rename from collects/scribble/private/manual-tech.ss rename to collects/scribble/private/manual-tech.rkt diff --git a/collects/scribble/private/manual-unit.ss b/collects/scribble/private/manual-unit.rkt similarity index 100% rename from collects/scribble/private/manual-unit.ss rename to collects/scribble/private/manual-unit.rkt diff --git a/collects/scribble/private/manual-utils.ss b/collects/scribble/private/manual-utils.rkt similarity index 100% rename from collects/scribble/private/manual-utils.ss rename to collects/scribble/private/manual-utils.rkt diff --git a/collects/scribble/private/manual-vars.ss b/collects/scribble/private/manual-vars.rkt similarity index 99% rename from collects/scribble/private/manual-vars.ss rename to collects/scribble/private/manual-vars.rkt index 40e42936..8ab617b8 100644 --- a/collects/scribble/private/manual-vars.ss +++ b/collects/scribble/private/manual-vars.rkt @@ -14,7 +14,7 @@ (provide/contract [struct (box-splice splice) ([run list?])]) ; XXX ugly copying -(provide deftogether +(provide deftogether *deftogether with-scheme-variables with-togetherable-scheme-variables) @@ -109,7 +109,7 @@ (define (*deftogether boxes body-thunk) - (make-splice + (make-box-splice (cons (make-table 'boxed diff --git a/collects/scribble/private/on-demand.ss b/collects/scribble/private/on-demand.rkt similarity index 100% rename from collects/scribble/private/on-demand.ss rename to collects/scribble/private/on-demand.rkt diff --git a/collects/scribble/private/provide-structs.ss b/collects/scribble/private/provide-structs.rkt similarity index 100% rename from collects/scribble/private/provide-structs.ss rename to collects/scribble/private/provide-structs.rkt diff --git a/collects/scribble/private/qsloc.ss b/collects/scribble/private/qsloc.rkt similarity index 100% rename from collects/scribble/private/qsloc.ss rename to collects/scribble/private/qsloc.rkt diff --git a/collects/scribble/private/render-utils.ss b/collects/scribble/private/render-utils.rkt similarity index 100% rename from collects/scribble/private/render-utils.ss rename to collects/scribble/private/render-utils.rkt diff --git a/collects/scribble/private/run-pdflatex.ss b/collects/scribble/private/run-pdflatex.rkt similarity index 100% rename from collects/scribble/private/run-pdflatex.ss rename to collects/scribble/private/run-pdflatex.rkt diff --git a/collects/scribble/provide-doc-transform.ss b/collects/scribble/provide-doc-transform.rkt similarity index 100% rename from collects/scribble/provide-doc-transform.ss rename to collects/scribble/provide-doc-transform.rkt diff --git a/collects/scribble/racket.rkt b/collects/scribble/racket.rkt new file mode 100644 index 00000000..2ccb86b7 --- /dev/null +++ b/collects/scribble/racket.rkt @@ -0,0 +1,1254 @@ +(module racket racket/base + (require "core.ss" + "basic.ss" + "search.ss" + "private/manual-sprop.ss" + "private/on-demand.ss" + mzlib/class + mzlib/for + syntax/modresolve + syntax/modcode + (for-syntax racket/base)) + + (provide define-code + to-element + to-element/no-color + to-paragraph + to-paragraph/prefix + syntax-ize + syntax-ize-hook + current-keyword-list + current-variable-list + current-meta-list + + input-color + output-color + input-background-color + no-color + reader-color + result-color + keyword-color + comment-color + paren-color + meta-color + value-color + symbol-color + variable-color + opt-color + error-color + syntax-link-color + value-link-color + module-color + module-link-color + block-color + highlighted-color + + (struct-out var-id) + (struct-out shaped-parens) + (struct-out just-context) + (struct-out alternate-display) + (struct-out literal-syntax) + (for-syntax make-variable-id + variable-id? + make-element-id-transformer + element-id-transformer?)) + + (define (make-racket-style s #:tt? [tt? #t]) + (make-style s (if tt? + (cons 'tt-chars scheme-properties) + scheme-properties))) + + (define-on-demand output-color (make-racket-style "ScmOut")) + (define-on-demand input-color (make-racket-style "ScmIn")) + (define-on-demand input-background-color (make-racket-style "ScmInBG")) + (define-on-demand no-color (make-racket-style "ScmPlain")) + (define-on-demand reader-color (make-racket-style "ScmRdr")) + (define-on-demand result-color (make-racket-style "ScmRes")) + (define-on-demand keyword-color (make-racket-style "ScmKw")) + (define-on-demand comment-color (make-racket-style "ScmCmt")) + (define-on-demand paren-color (make-racket-style "ScmPn")) + (define-on-demand meta-color (make-racket-style "ScmMeta")) + (define-on-demand value-color (make-racket-style "ScmVal")) + (define-on-demand symbol-color (make-racket-style "ScmSym")) + (define-on-demand variable-color (make-racket-style "ScmVar")) + (define-on-demand opt-color (make-racket-style "ScmOpt")) + (define-on-demand error-color (make-racket-style "ScmErr" #:tt? #f)) + (define-on-demand syntax-link-color (make-racket-style "ScmStxLink")) + (define-on-demand value-link-color (make-racket-style "ScmValLink")) + (define-on-demand module-color (make-racket-style "ScmMod")) + (define-on-demand module-link-color (make-racket-style "ScmModLink")) + (define-on-demand block-color (make-racket-style "ScmBlk")) + (define-on-demand highlighted-color (make-racket-style "highlighted" #:tt? #f)) + + (define current-keyword-list + (make-parameter null)) + (define current-variable-list + (make-parameter null)) + (define current-meta-list + (make-parameter null)) + + (define defined-names (make-hasheq)) + + (define-struct (sized-element element) (length)) + + (define-struct (spaces element) (cnt)) + + (define (literalize-spaces i) + (let ([m (regexp-match-positions #rx" +" i)]) + (if m + (let ([cnt (- (cdar m) (caar m))]) + (make-spaces #f + (list + (literalize-spaces (substring i 0 (caar m))) + (hspace cnt) + (literalize-spaces (substring i (cdar m)))) + cnt)) + i))) + + + (define line-breakable-space (make-element 'tt " ")) + + ;; These caches intentionally record a key with the value. + ;; That way, when the value is no longer used, the key + ;; goes away, and the entry is gone. + + (define id-element-cache (make-weak-hash)) + (define element-cache (make-weak-hash)) + + (define-struct (cached-delayed-element delayed-element) (cache-key)) + (define-struct (cached-element element) (cache-key)) + + (define qq-ellipses (string->uninterned-symbol "...")) + + (define (make-id-element c s) + (let* ([key (and id-element-cache + (let ([b (identifier-label-binding c)]) + (vector (syntax-e c) + (module-path-index->taglet (caddr b)) + (cadddr b) + (list-ref b 5))))]) + (or (and key + (let ([b (hash-ref id-element-cache key #f)]) + (and b + (weak-box-value b)))) + (let ([e (make-cached-delayed-element + (lambda (renderer sec ri) + (let* ([tag (find-racket-tag sec ri c #f)]) + (if tag + (list + (case (car tag) + [(form) + (make-link-element syntax-link-color (list s) tag)] + [else + (make-link-element value-link-color (list s) tag)])) + (list + (make-element "badlink" + (make-element value-link-color s)))))) + (lambda () s) + (lambda () s) + key)]) + (when key + (hash-set! id-element-cache key (make-weak-box e))) + e)))) + + (define (make-element/cache style content) + (if (and element-cache + (string? content)) + (let ([key (vector style content)]) + (let ([b (hash-ref element-cache key #f)]) + (or (and b (weak-box-value b)) + (let ([e (make-cached-element style content key)]) + (hash-set! element-cache key (make-weak-box e)) + e)))) + (make-element style content))) + + (define (to-quoted obj expr? quote-depth out color? inc!) + (if (and expr? + (zero? quote-depth) + (quotable? obj)) + (begin + (out "'" (and color? value-color)) + (inc!) + (add1 quote-depth)) + quote-depth)) + + (define (to-unquoted expr? quote-depth out color? inc!) + (if (or (not expr?) (zero? quote-depth)) + quote-depth + (begin + (out "," (and color? meta-color)) + (inc!) + (to-unquoted expr? (sub1 quote-depth) out color? inc!)))) + + (define (typeset-atom c out color? quote-depth expr?) + (if (and (var-id? (syntax-e c)) + (zero? quote-depth)) + (out (format "~s" (let ([v (var-id-sym (syntax-e c))]) + (if (syntax? v) + (syntax-e v) + v))) + variable-color) + (let*-values ([(is-var?) (and (identifier? c) + (memq (syntax-e c) (current-variable-list)))] + [(s it? sub?) + (let ([sc (syntax-e c)]) + (let ([s (or (syntax-property c 'display-string) + (format "~s" (if (literal-syntax? sc) + (literal-syntax-stx sc) + (if (var-id? sc) + (var-id-sym sc) + sc))))]) + (if (and (symbol? sc) + ((string-length s) . > . 1) + (char=? (string-ref s 0) #\_) + (not (or (identifier-label-binding c) + is-var?))) + (values (substring s 1) #t #f) + (values s #f #f))))]) + (let ([quote-depth (if (and expr? (identifier? c) (not (eq? qq-ellipses (syntax-e c)))) + (let ([quote-depth + (if (and (quote-depth . < . 2) + (memq (syntax-e c) '(unquote unquote-splicing))) + (to-unquoted expr? quote-depth out color? void) + quote-depth)]) + (to-quoted c expr? quote-depth out color? void)) + quote-depth)]) + (if (or (element? (syntax-e c)) + (delayed-element? (syntax-e c)) + (part-relative-element? (syntax-e c))) + (out (syntax-e c) #f) + (out (if (and (identifier? c) + color? + (quote-depth . <= . 0) + (not (or it? is-var?))) + (if (pair? (identifier-label-binding c)) + (make-id-element c s) + s) + (literalize-spaces s)) + (cond + [(positive? quote-depth) value-color] + [(let ([v (syntax-e c)]) + (or (number? v) + (string? v) + (bytes? v) + (char? v) + (regexp? v) + (byte-regexp? v) + (boolean? v))) + value-color] + [(identifier? c) + (cond + [is-var? + variable-color] + [(and (identifier? c) + (memq (syntax-e c) (current-keyword-list))) + keyword-color] + [(and (identifier? c) + (memq (syntax-e c) (current-meta-list))) + meta-color] + [it? variable-color] + [else symbol-color])] + [else paren-color]) + (string-length s))))))) + + (define omitable (make-style #f '(omitable))) + + (define (gen-typeset c multi-line? prefix1 prefix suffix color? expr?) + (let* ([c (syntax-ize c 0 #:expr? expr?)] + [content null] + [docs null] + [first (syntax-case c (code:line) + [(code:line e . rest) #'e] + [else c])] + [init-col (or (syntax-column first) 0)] + [src-col init-col] + [inc-src-col (lambda () (set! src-col (add1 src-col)))] + [dest-col 0] + [highlight? #f] + [col-map (make-hash)] + [next-col-map (make-hash)] + [line (or (syntax-line first) 0)]) + (define (finish-line!) + (when multi-line? + (set! docs (cons (make-paragraph omitable (reverse content)) + docs)) + (set! content null))) + (define out + (case-lambda + [(v cls) + (out v cls (let sz-loop ([v v]) + (cond + [(string? v) (string-length v)] + [(list? v) (for/fold ([s 0]) ([v (in-list v)]) (+ s (sz-loop v)))] + [(sized-element? v) (sized-element-length v)] + [(element? v) + (sz-loop (element-content v))] + [(delayed-element? v) + (content-width v)] + [(part-relative-element? v) + (content-width v)] + [(spaces? v) + (+ (sz-loop (car (element-content v))) + (spaces-cnt v) + (sz-loop (caddr (element-content v))))] + [else 1])))] + [(v cls len) + (unless (equal? v "") + (cond + [(spaces? v) + (out (car (element-content v)) cls 0) + (out (cadr (element-content v)) #f 0) + (out (caddr (element-content v)) cls len)] + [(equal? v "\n") + (if multi-line? + (begin + (finish-line!) + (out prefix cls)) + (out " " cls))] + [else + (set! content (cons ((if highlight? + (lambda (c) + (make-element highlighted-color c)) + values) + (if (and color? cls) + (make-element/cache cls v) + v)) + content)) + (set! dest-col (+ dest-col len))]))])) + (define advance + (case-lambda + [(c init-line! delta) + (let ([c (+ delta (or (syntax-column c) 0))] + [l (syntax-line c)]) + (let ([new-line? (and l (l . > . line))]) + (when new-line? + (for ([i (in-range (- l line))]) + (out "\n" no-color)) + (set! line l) + (set! col-map next-col-map) + (set! next-col-map (make-hash)) + (init-line!)) + (let ([d-col (let ([def-val (+ dest-col (- c src-col))]) + (if new-line? + (hash-ref col-map c def-val) + def-val))]) + (let ([amt (- d-col dest-col)]) + (when (positive? amt) + (let ([old-dest-col dest-col]) + (out (if (and (= 1 amt) (not multi-line?)) + line-breakable-space ; allows a line break to replace the space + (hspace amt)) + #f) + (set! dest-col (+ old-dest-col amt)))))) + (set! src-col c) + (hash-set! next-col-map src-col dest-col)))] + [(c init-line!) (advance c init-line! 0)])) + (define (convert-infix c quote-depth expr?) + (let ([l (syntax->list c)]) + (and l + ((length l) . >= . 3) + ((or (syntax-position (car l)) -inf.0) + . > . + (or (syntax-position (cadr l)) +inf.0)) + (let ([a (car l)]) + (let loop ([l (cdr l)] + [prev null]) + (cond + [(null? l) #f] ; couldn't unwind + [else (let ([p2 (syntax-position (car l))]) + (if (and p2 + (p2 . > . (syntax-position a))) + (datum->syntax c + (append + (reverse prev) + (list + (datum->syntax + a + (let ([val? (positive? quote-depth)]) + (make-sized-element + (if val? value-color #f) + (list + (make-element/cache (if val? value-color paren-color) '". ") + (typeset a #f "" "" "" (not val?) expr?) + (make-element/cache (if val? value-color paren-color) '" .")) + (+ (syntax-span a) 4))) + (list (syntax-source a) + (syntax-line a) + (- (syntax-column a) 2) + (- (syntax-position a) 2) + (+ (syntax-span a) 4)) + a)) + l) + c + c) + (loop (cdr l) + (cons (car l) prev))))])))))) + (define (no-fancy-chars s) + (cond + [(eq? s 'rsquo) "'"] + [else s])) + (define (loop init-line! quote-depth expr? no-cons?) + (lambda (c) + (cond + [(eq? 'code:blank (syntax-e c)) + (advance c init-line!)] + [(and (pair? (syntax-e c)) + (eq? (syntax-e (car (syntax-e c))) 'code:comment)) + (let ([l (syntax->list c)]) + (unless (and l (= 2 (length l))) + (raise-syntax-error + #f + "does not have a single sub-form" + c))) + (advance c init-line!) + (out ";" comment-color) + (out 'nbsp comment-color) + (let ([v (syntax->datum (cadr (syntax->list c)))]) + (if (paragraph? v) + (map (lambda (v) + (let ([v (no-fancy-chars v)]) + (if (or (string? v) (symbol? v)) + (out v comment-color) + (out v #f)))) + (paragraph-content v)) + (out (no-fancy-chars v) comment-color)))] + [(and (pair? (syntax-e c)) + (eq? (syntax-e (car (syntax-e c))) 'code:contract)) + (advance c init-line!) + (out "; " comment-color) + (let* ([l (cdr (syntax->list c))] + [s-col (or (syntax-column (car l)) src-col)]) + (set! src-col s-col) + (for-each (loop (lambda () + (set! src-col s-col) + (set! dest-col 0) + (out "; " comment-color)) + 0 + expr? + #f) + l))] + [(and (pair? (syntax-e c)) + (eq? (syntax-e (car (syntax-e c))) 'code:line)) + (let ([l (cdr (syntax->list c))]) + (for-each (loop init-line! quote-depth expr? #f) + l))] + [(and (pair? (syntax-e c)) + (eq? (syntax-e (car (syntax-e c))) 'code:hilite)) + (let ([l (syntax->list c)] + [h? highlight?]) + (unless (and l (= 2 (length l))) + (error "bad code:redex: ~e" (syntax->datum c))) + (advance c init-line!) + (set! src-col (syntax-column (cadr l))) + (hash-set! next-col-map src-col dest-col) + (set! highlight? #t) + ((loop init-line! quote-depth expr? #f) (cadr l)) + (set! highlight? h?) + (set! src-col (add1 src-col)))] + [(and (pair? (syntax-e c)) + (eq? (syntax-e (car (syntax-e c))) 'code:quote)) + (advance c init-line!) + (let ([quote-depth (to-quoted c expr? quote-depth out color? inc-src-col)]) + (out "(" (if (positive? quote-depth) value-color paren-color)) + (set! src-col (+ src-col 1)) + (hash-set! next-col-map src-col dest-col) + ((loop init-line! quote-depth expr? #f) + (datum->syntax #'here 'quote (car (syntax-e c)))) + (for-each (loop init-line! (add1 quote-depth) expr? #f) + (cdr (syntax->list c))) + (out ")" (if (positive? quote-depth) value-color paren-color)) + (set! src-col (+ src-col 1)) + #; + (hash-set! next-col-map src-col dest-col))] + [(and (pair? (syntax-e c)) + (memq (syntax-e (car (syntax-e c))) + '(quote quasiquote unquote unquote-splicing + quasisyntax syntax unsyntax unsyntax-splicing)) + (let ([v (syntax->list c)]) + (and v (= 2 (length v)))) + (or (not expr?) + (positive? quote-depth) + (quotable? c))) + (advance c init-line!) + (let ([quote-depth (to-quoted c expr? quote-depth out color? inc-src-col)]) + (let-values ([(str quote-delta) + (case (syntax-e (car (syntax-e c))) + [(quote) (values "'" +inf.0)] + [(unquote) (values "," -1)] + [(unquote-splicing) (values ",@" -1)] + [(quasiquote) (values "`" +1)] + [(syntax) (values "#'" 0)] + [(quasisyntax) (values "#`" 0)] + [(unsyntax) (values "#," 0)] + [(unsyntax-splicing) (values "#,@" 0)])]) + (out str (if (positive? (+ quote-depth quote-delta)) + value-color + reader-color)) + (let ([i (cadr (syntax->list c))]) + (set! src-col (or (syntax-column i) src-col)) + (hash-set! next-col-map src-col dest-col) + ((loop init-line! (max 0 (+ quote-depth quote-delta)) expr? #f) i))))] + [(and (pair? (syntax-e c)) + (or (not expr?) + (positive? quote-depth) + (quotable? c)) + (convert-infix c quote-depth expr?)) + => (lambda (converted) + ((loop init-line! quote-depth expr? #f) converted))] + [(or (pair? (syntax-e c)) + (mpair? (syntax-e c)) + (forced-pair? (syntax-e c)) + (null? (syntax-e c)) + (vector? (syntax-e c)) + (and (struct? (syntax-e c)) + (prefab-struct-key (syntax-e c))) + (struct-proxy? (syntax-e c))) + (let* ([sh (or (syntax-property c 'paren-shape) + (if (and (mpair? (syntax-e c)) + (not (and expr? (zero? quote-depth)))) + #\{ + #\())] + [quote-depth (if (and (not expr?) + (zero? quote-depth) + (or (vector? (syntax-e c)) + (struct? (syntax-e c)))) + 1 + quote-depth)] + [p-color (if (positive? quote-depth) + value-color + (if (eq? sh #\?) + opt-color + paren-color))]) + (advance c init-line!) + (let ([quote-depth (if (struct-proxy? (syntax-e c)) + quote-depth + (to-quoted c expr? quote-depth out color? inc-src-col))]) + (when (and expr? (zero? quote-depth)) + (out "(" p-color) + (unless no-cons? + (out (let ([s (cond + [(pair? (syntax-e c)) + (if (syntax->list c) + "list" + (if (let ([d (cdr (syntax-e c))]) + (or (pair? d) + (and (syntax? d) + (pair? (syntax-e d))))) + "list*" + "cons"))] + [(vector? (syntax-e c)) "vector"] + [(mpair? (syntax-e c)) "mcons"] + [else (format "~a" + (if (struct-proxy? (syntax-e c)) + (syntax-e (struct-proxy-name (syntax-e c))) + (object-name (syntax-e c))))])]) + (set! src-col (+ src-col (string-length s))) + s) + symbol-color) + (out " " no-color))) + (when (vector? (syntax-e c)) + (unless (and expr? (zero? quote-depth)) + (let ([vec (syntax-e c)]) + (out "#" p-color) + (if (zero? (vector-length vec)) + (set! src-col (+ src-col (- (syntax-span c) 2))) + (set! src-col (+ src-col (- (syntax-column (vector-ref vec 0)) + (syntax-column c) + 1))))))) + (when (struct? (syntax-e c)) + (unless (and expr? (zero? quote-depth)) + (out "#s" p-color) + (set! src-col (+ src-col 2)))) + (unless (and expr? (zero? quote-depth)) + (out (case sh + [(#\[ #\?) "["] + [(#\{) "{"] + [else "("]) + p-color)) + (set! src-col (+ src-col 1)) + (hash-set! next-col-map src-col dest-col) + (let lloop ([l (cond + [(vector? (syntax-e c)) + (vector->short-list (syntax-e c) syntax-e)] + [(struct? (syntax-e c)) + (let ([l (vector->list (struct->vector (syntax-e c)))]) + ;; Need to build key datum, syntax-ize it internally, and + ;; set the overall width to fit right: + (if (and expr? (zero? quote-depth)) + (cdr l) + (cons (let ([key (syntax-ize (prefab-struct-key (syntax-e c)) + (+ 3 (or (syntax-column c) 0)) + (or (syntax-line c) 1))] + [end (if (pair? (cdr l)) + (and (equal? (syntax-line c) (syntax-line (cadr l))) + (syntax-column (cadr l))) + (and (syntax-column c) + (+ (syntax-column c) (syntax-span c))))]) + (if end + (datum->syntax #f + (syntax-e key) + (vector #f (syntax-line key) + (syntax-column key) + (syntax-position key) + (max 1 (- end 1 (syntax-column key))))) + end)) + (cdr l))))] + [(struct-proxy? (syntax-e c)) + (struct-proxy-content (syntax-e c))] + [(forced-pair? (syntax-e c)) + (syntax-e c)] + [(mpair? (syntax-e c)) + (syntax-e c)] + [else c])] + [first-expr? (and expr? (not (struct-proxy? (syntax-e c))) (not no-cons?))] + [dotted? #f]) + (cond + [(and (syntax? l) + (pair? (syntax-e l)) + (not dotted?) + (not (and (memq (syntax-e (car (syntax-e l))) + '(quote unquote syntax unsyntax quasiquote quasiunsyntax)) + (let ([v (syntax->list l)]) + (and v (= 2 (length v)))) + (or (not expr?) + (quote-depth . > . 1) + (not (memq (syntax-e (car (syntax-e l))) + '(unquote unquote-splicing))))))) + (lloop (syntax-e l) first-expr? #f)] + [(and (or (null? l) + (and (syntax? l) + (null? (syntax-e l))))) + (void)] + [(and (pair? l) (not dotted?)) + ((loop init-line! quote-depth first-expr? #f) (car l)) + (lloop (cdr l) expr? #f)] + [(forced-pair? l) + ((loop init-line! quote-depth first-expr? #f) (forced-pair-car l)) + (lloop (forced-pair-cdr l) expr? #t)] + [(mpair? l) + ((loop init-line! quote-depth first-expr? #f) (mcar l)) + (lloop (mcdr l) expr? #t)] + [else + (unless (and expr? (zero? quote-depth)) + (advance l init-line! -2) + (out ". " (if (positive? quote-depth) value-color paren-color)) + (set! src-col (+ src-col 3))) + (hash-set! next-col-map src-col dest-col) + ((loop init-line! quote-depth first-expr? #f) l)])) + (out (case sh + [(#\[ #\?) "]"] + [(#\{) "}"] + [else ")"]) + p-color) + (set! src-col (+ src-col 1))))] + [(box? (syntax-e c)) + (advance c init-line!) + (let ([quote-depth (to-quoted c expr? quote-depth out color? inc-src-col)]) + (if (and expr? (zero? quote-depth)) + (begin + (out "(" paren-color) + (out "box" symbol-color) + (out " " no-color) + (set! src-col (+ src-col 5))) + (begin + (out "#&" value-color) + (set! src-col (+ src-col 2)))) + (hash-set! next-col-map src-col dest-col) + ((loop init-line! (if expr? quote-depth +inf.0) expr? #f) (unbox (syntax-e c))) + (when (and expr? (zero? quote-depth)) + (out ")" paren-color)))] + [(hash? (syntax-e c)) + (advance c init-line!) + (let ([equal-table? (hash-equal? (syntax-e c))] + [eqv-table? (hash-eq? (syntax-e c))] + [quote-depth (to-quoted c expr? quote-depth out color? inc-src-col)]) + (unless (and expr? (zero? quote-depth)) + (out (if equal-table? + "#hash" + (if eqv-table? + "#hasheqv" + "#hasheq")) + value-color)) + (let ([delta (+ 5 (if equal-table? 0 (if eqv-table? 3 2)) + (if (and expr? (zero? quote-depth)) 1 0))] + [orig-col src-col]) + (set! src-col (+ src-col delta)) + (hash-set! next-col-map src-col dest-col) + ((loop init-line! (if expr? quote-depth +inf.0) expr? (and expr? (zero? quote-depth))) + (let*-values ([(l) (sort (hash-map (syntax-e c) cons) + (lambda (a b) + (< (or (syntax-position (cdr a)) -inf.0) + (or (syntax-position (cdr b)) -inf.0))))] + [(sep cap) (if (and expr? (zero? quote-depth)) + (values 1 0) + (values 3 1))] + [(col0) (+ (syntax-column c) delta cap 1)] + [(l2 pos line) (for/fold ([l2 null][col col0][line (syntax-line c)]) + ([p (in-list l)]) + (let* ([tentative (syntax-ize (car p) 0 + #:expr? (and expr? (zero? quote-depth)))] + [width (syntax-span tentative)] + [col (if (= line (syntax-line (cdr p))) + col + col0)]) + (let ([key + (let ([e (syntax-ize (car p) + (max 0 (- (syntax-column (cdr p)) + width + sep)) + (syntax-line (cdr p)) + #:expr? (and expr? (zero? quote-depth)))]) + (if ((syntax-column e) . <= . col) + e + (datum->syntax #f + (syntax-e e) + (vector (syntax-source e) + (syntax-line e) + col + (syntax-position e) + (+ (syntax-span e) (- (syntax-column e) col))))))]) + (let ([elem + (datum->syntax + #f + (make-forced-pair key (cdr p)) + (vector 'here + (syntax-line (cdr p)) + (max 0 (- (syntax-column key) cap)) + (max 1 (- (syntax-position key) cap)) + (+ (syntax-span (cdr p)) (syntax-span key) sep cap cap)))]) + (values (cons elem l2) + (+ (syntax-column elem) (syntax-span elem) 2) + (syntax-line elem))))))]) + (if (and expr? (zero? quote-depth)) + ;; constructed: + (let ([l (apply append + (map (lambda (p) + (let ([p (syntax-e p)]) + (list (forced-pair-car p) + (forced-pair-cdr p)))) + (reverse l2)))]) + (datum->syntax + #f + (cons (let ([s (if equal-table? + 'hash + (if eqv-table? + 'hasheqv + 'hasheq))]) + (datum->syntax #f + s + (vector (syntax-source c) + (syntax-line c) + (+ (syntax-column c) 1) + (+ (syntax-position c) 1) + (string-length (symbol->string s))))) + l) + c)) + ;; quoted: + (datum->syntax #f (reverse l2) (vector (syntax-source c) + (syntax-line c) + (+ (syntax-column c) delta) + (+ (syntax-position c) delta) + (max 1 (- (syntax-span c) delta))))))) + (set! src-col (+ orig-col (syntax-span c)))))] + [(graph-reference? (syntax-e c)) + (advance c init-line!) + (out (format "#~a#" (unbox (graph-reference-bx (syntax-e c)))) + (if (positive? quote-depth) + value-color + paren-color)) + (set! src-col (+ src-col (syntax-span c)))] + [(graph-defn? (syntax-e c)) + (advance c init-line!) + (let ([bx (graph-defn-bx (syntax-e c))]) + (out (format "#~a=" (unbox bx)) + (if (positive? quote-depth) + value-color + paren-color)) + (set! src-col (+ src-col 3)) + ((loop init-line! quote-depth expr? #f) (graph-defn-r (syntax-e c))))] + [(and (keyword? (syntax-e c)) expr?) + (advance c init-line!) + (let ([quote-depth (to-quoted c expr? quote-depth out color? inc-src-col)]) + (typeset-atom c out color? quote-depth expr?) + (set! src-col (+ src-col (or (syntax-span c) 1))))] + [else + (advance c init-line!) + (typeset-atom c out color? quote-depth expr?) + (set! src-col (+ src-col (or (syntax-span c) 1))) + #; + (hash-set! next-col-map src-col dest-col)]))) + (out prefix1 #f) + (set! dest-col 0) + (hash-set! next-col-map init-col dest-col) + ((loop (lambda () (set! src-col init-col) (set! dest-col 0)) 0 expr? #f) c) + (if (list? suffix) + (map (lambda (sfx) + (finish-line!) + (out sfx #f)) + suffix) + (out suffix #f)) + (unless (null? content) + (finish-line!)) + (if multi-line? + (if (= 1 (length docs)) + (car docs) + (make-table block-color (map list (reverse docs)))) + (make-sized-element #f (reverse content) dest-col)))) + + (define (typeset c multi-line? prefix1 prefix suffix color? expr?) + (let* ([c (syntax-ize c 0 #:expr? expr?)] + [s (syntax-e c)]) + (if (or multi-line? + (eq? 'code:blank s) + (pair? s) + (mpair? s) + (vector? s) + (struct? s) + (box? s) + (null? s) + (hash? s) + (graph-defn? s) + (graph-reference? s) + (struct-proxy? s) + (and expr? (or (identifier? c) + (keyword? (syntax-e c))))) + (gen-typeset c multi-line? prefix1 prefix suffix color? expr?) + (typeset-atom c + (letrec ([mk + (case-lambda + [(elem color) + (mk elem color (or (syntax-span c) 1))] + [(elem color len) + (if (and (string? elem) + (= len (string-length elem))) + (make-element/cache (and color? color) elem) + (make-sized-element (and color? color) elem len))])]) + mk) + color? 0 expr?)))) + + (define (to-element c #:expr? [expr? #f]) + (typeset c #f "" "" "" #t expr?)) + + (define (to-element/no-color c #:expr? [expr? #f]) + (typeset c #f "" "" "" #f expr?)) + + (define (to-paragraph c #:expr? [expr? #f]) + (typeset c #t "" "" "" #t expr?)) + + (define ((to-paragraph/prefix pfx1 pfx sfx) c #:expr? [expr? #f]) + (typeset c #t pfx1 pfx sfx #t expr?)) + + (begin-for-syntax + (define-struct variable-id (sym) + #:omit-define-syntaxes + #:property prop:procedure (lambda (self stx) + (raise-syntax-error + #f + (string-append + "misuse of an identifier (not in `racket', etc.) that is" + " bound as a code-typesetting variable") + stx))) + (define-struct element-id-transformer (proc) + #:omit-define-syntaxes + #:property prop:procedure (lambda (self stx) + (raise-syntax-error + #f + (string-append + "misuse of an identifier (not in `racket', etc.) that is" + " bound as an code-typesetting element transformer") + stx)))) + + (define-syntax (define-code stx) + (syntax-case stx () + [(_ code typeset-code uncode d->s stx-prop) + (syntax/loc stx + (define-syntax (code stx) + (define (wrap-loc v ctx e) + `(,#'d->s ,ctx + ,e + #(code + ,(syntax-line v) + ,(syntax-column v) + ,(syntax-position v) + ,(syntax-span v)))) + (define (stx->loc-s-expr v) + (let ([slv (and (identifier? v) + (syntax-local-value v (lambda () #f)))]) + (cond + [(variable-id? slv) + (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))] + [(element-id-transformer? slv) + (wrap-loc v #f ((element-id-transformer-proc slv) v))] + [(syntax? v) + (let ([mk (wrap-loc + v + `(quote-syntax ,(datum->syntax v 'defcode)) + (syntax-case v (uncode) + [(uncode e) #'e] + [else (stx->loc-s-expr (syntax-e v))]))]) + (let ([prop (syntax-property v 'paren-shape)]) + (if prop + `(,#'stx-prop ,mk 'paren-shape ,prop) + mk)))] + [(null? v) 'null] + [(list? v) `(list . ,(map stx->loc-s-expr v))] + [(pair? v) `(cons ,(stx->loc-s-expr (car v)) + ,(stx->loc-s-expr (cdr v)))] + [(vector? v) `(vector ,@(map + stx->loc-s-expr + (vector->list v)))] + [(and (struct? v) (prefab-struct-key v)) + `(make-prefab-struct (quote ,(prefab-struct-key v)) + ,@(map + stx->loc-s-expr + (cdr (vector->list (struct->vector v)))))] + [(box? v) `(box ,(stx->loc-s-expr (unbox v)))] + [(hash? v) `(,(cond + [(hash-eq? v) 'make-immutable-hasheq] + [(hash-eqv? v) 'make-immutable-hasheqv] + [else 'make-immutable-hash]) + (list + ,@(hash-map + v + (lambda (k v) + `(cons (quote ,k) + ,(stx->loc-s-expr v))))))] + [else `(quote ,v)]))) + (define (cvt s) + (datum->syntax #'here (stx->loc-s-expr s) #f)) + (if (eq? (syntax-local-context) 'expression) + (syntax-case stx () + [(_ expr) #`(typeset-code #,(cvt #'expr))] + [(_ expr (... ...)) + #`(typeset-code #,(cvt #'(code:line expr (... ...))))]) + (quasisyntax/loc stx + (#%expression #,stx)))))] + [(_ code typeset-code uncode d->s) + #'(define-code code typeset-code uncode d->s syntax-property)] + [(_ code typeset-code uncode) + #'(define-code code typeset-code uncode datum->syntax syntax-property)] + [(_ code typeset-code) #'(define-code code typeset-code unsyntax)])) + + + (define syntax-ize-hook (make-parameter (lambda (v col) #f))) + + (define (vector->short-list v extract) + (vector->list v) + #; + (let ([l (vector->list v)]) + (reverse (list-tail + (reverse l) + (- (vector-length v) + (let loop ([i (sub1 (vector-length v))]) + (cond + [(zero? i) 1] + [(eq? (extract (vector-ref v i)) + (extract (vector-ref v (sub1 i)))) + (loop (sub1 i))] + [else (add1 i)]))))))) + + (define (short-list->vector v l) + (list->vector + (let ([n (length l)]) + (if (n . < . (vector-length v)) + (reverse (let loop ([r (reverse l)][i (- (vector-length v) n)]) + (if (zero? i) + r + (loop (cons (car r) r) (sub1 i))))) + l)))) + + (define-struct var-id (sym)) + (define-struct shaped-parens (val shape)) + (define-struct just-context (val ctx)) + (define-struct alternate-display (id string)) + (define-struct literal-syntax (stx)) + (define-struct struct-proxy (name content)) + + (define-struct graph-reference (bx)) + (define-struct graph-defn (r bx)) + + (define (syntax-ize v col [line 1] #:expr? [expr? #f]) + (do-syntax-ize v col line (box #hasheq()) #f (and expr? 0) #f)) + + (define (graph-count ht graph?) + (and graph? + (let ([n (hash-ref (unbox ht) '#%graph-count 0)]) + (set-box! ht (hash-set (unbox ht) '#%graph-count (add1 n))) + n))) + + (define-struct forced-pair (car cdr)) + + (define (quotable? v) + (define graph (make-hasheq)) + (let quotable? ([v v]) + (if (hash-ref graph v #f) + #t + (begin + (hash-set! graph v #t) + (cond + [(syntax? v) (quotable? (syntax-e v))] + [(pair? v) (and (quotable? (car v)) + (quotable? (cdr v)))] + [(vector? v) (andmap quotable? (vector->list v))] + [(hash? v) (for/and ([(k v) (in-hash v)]) + (and (quotable? k) + (quotable? v)))] + [(box? v) (quotable? (unbox v))] + [(and (struct? v) + (prefab-struct-key v)) + (andmap quotable? (vector->list (struct->vector v)))] + [(struct? v) (if (custom-write? v) + (case (or (and (custom-print-quotable? v) + (custom-print-quotable-accessor v)) + 'self) + [(self always) #t] + [(never) #f] + [(maybe) + (andmap quotable? (vector->list (struct->vector v)))]) + #f)] + [(struct-proxy? v) #f] + [(mpair? v) #f] + [else #t]))))) + + (define (do-syntax-ize v col line ht graph? qq no-cons?) + (cond + [((syntax-ize-hook) v col) + => (lambda (r) r)] + [(shaped-parens? v) + (syntax-property (do-syntax-ize (shaped-parens-val v) col line ht #f qq #f) + 'paren-shape + (shaped-parens-shape v))] + [(just-context? v) + (let ([s (do-syntax-ize (just-context-val v) col line ht #f qq #f)]) + (datum->syntax (just-context-ctx v) + (syntax-e s) + s + s + (just-context-ctx v)))] + [(alternate-display? v) + (let ([s (do-syntax-ize (alternate-display-id v) col line ht #f qq #f)]) + (syntax-property s + 'display-string + (alternate-display-string v)))] + [(hash-ref (unbox ht) v #f) + => (lambda (m) + (unless (unbox m) + (set-box! m #t)) + (datum->syntax #f + (make-graph-reference m) + (vector #f line col (+ 1 col) 1)))] + [(and qq + (zero? qq) + (or (pair? v) + (forced-pair? v) + (vector? v) + (hash? v) + (box? v) + (and (struct? v) + (prefab-struct-key v))) + (quotable? v) + (not no-cons?)) + ;; Add a quote: + (let ([l (do-syntax-ize v (add1 col) line ht #f 1 #f)]) + (datum->syntax #f + (syntax-e l) + (vector (syntax-source l) + (syntax-line l) + (sub1 (syntax-column l)) + (max 0 (sub1 (syntax-position l))) + (add1 (syntax-span l)))))] + [(and (list? v) + (pair? v) + (or (not qq) + (positive? qq) + (quotable? v)) + (let ([s (let ([s (car v)]) + (if (just-context? s) + (just-context-val s) + s))]) + (memq s '(quote unquote unquote-splicing))) + (not no-cons?)) + => (lambda (s) + (let* ([delta (if (and qq (zero? qq)) + 1 + 0)] + [c (do-syntax-ize (cadr v) (+ col delta) line ht #f qq #f)]) + (datum->syntax #f + (list (do-syntax-ize (car v) col line ht #f qq #f) + c) + (vector #f line col (+ 1 col) + (+ 1 + (if (and qq (zero? qq)) 1 0) + (syntax-span c))))))] + [(or (list? v) + (vector? v) + (and (struct? v) + (or (and qq + ;; Watch out for partially transparent subtypes of `element': + (not (element? v))) + (prefab-struct-key v)))) + (let ([orig-ht (unbox ht)] + [graph-box (box (graph-count ht graph?))]) + (set-box! ht (hash-set (unbox ht) v graph-box)) + (let* ([graph-sz (if graph? + (+ 2 (string-length (format "~a" (unbox graph-box)))) + 0)] + [vec-sz (cond + [(vector? v) + (if (and qq (zero? qq)) 0 1)] + [(struct? v) + (if (and (prefab-struct-key v) + (or (not qq) (positive? qq))) + 2 + 0)] + [else 0])] + [delta (if (and qq (zero? qq)) + (cond + [(vector? v) 8] + [(struct? v) 1] + [no-cons? 1] + [else 5]) + 1)] + [r (let ([l (let loop ([col (+ col delta vec-sz graph-sz)] + [v (cond + [(vector? v) + (vector->short-list v values)] + [(struct? v) + (cons (let ([pf (prefab-struct-key v)]) + (if pf + (prefab-struct-key v) + (object-name v))) + (cdr (vector->list (struct->vector v qq-ellipses))))] + [else v])]) + (if (null? v) + null + (let ([i (do-syntax-ize (car v) col line ht #f qq #f)]) + (cons i + (loop (+ col 1 (syntax-span i)) (cdr v))))))]) + (datum->syntax #f + (cond + [(vector? v) (short-list->vector v l)] + [(struct? v) + (let ([pf (prefab-struct-key v)]) + (if pf + (apply make-prefab-struct (prefab-struct-key v) (cdr l)) + (make-struct-proxy (car l) (cdr l))))] + [else l]) + (vector #f line + (+ graph-sz col) + (+ 1 graph-sz col) + (+ 1 + vec-sz + delta + (if (zero? (length l)) + 0 + (sub1 (length l))) + (apply + (map syntax-span l))))))]) + (unless graph? + (set-box! ht (hash-set (unbox ht) v #f))) + (cond + [graph? (datum->syntax #f + (make-graph-defn r graph-box) + (vector #f (syntax-line r) + (- (syntax-column r) graph-sz) + (- (syntax-position r) graph-sz) + (+ (syntax-span r) graph-sz)))] + [(unbox graph-box) + ;; Go again, this time knowing that there will be a graph: + (set-box! ht orig-ht) + (do-syntax-ize v col line ht #t qq #f)] + [else r])))] + [(or (pair? v) + (mpair? v) + (forced-pair? v)) + (let ([carv (if (pair? v) (car v) (if (mpair? v) (mcar v) (forced-pair-car v)))] + [cdrv (if (pair? v) (cdr v) (if (mpair? v) (mcdr v) (forced-pair-cdr v)))] + [orig-ht (unbox ht)] + [graph-box (box (graph-count ht graph?))]) + (set-box! ht (hash-set (unbox ht) v graph-box)) + (let* ([delta (if (and qq (zero? qq) (not no-cons?)) + (if (mpair? v) + 7 ; "(mcons " + (if (or (list? cdrv) + (not (pair? cdrv))) + 6 ; "(cons " + 7)) ; "(list* " + 1)] + [inc (if graph? + (+ 2 (string-length (format "~a" (unbox graph-box)))) + 0)] + [a (do-syntax-ize carv (+ col delta inc) line ht #f qq #f)] + [sep (if (and (pair? v) + (pair? cdrv) + ;; FIXME: what if it turns out to be a graph reference? + (not (hash-ref (unbox ht) cdrv #f))) + 0 + (if (and qq (zero? qq)) + 1 + 3))] + [b (do-syntax-ize cdrv (+ col delta inc (syntax-span a) sep) line ht #f qq #t)]) + (let ([r (datum->syntax #f + (if (mpair? v) + (mcons a b) + (cons a b)) + (vector #f line (+ col inc) (+ delta col inc) + (+ 1 delta + (if (and qq (zero? qq)) 1 0) + sep (syntax-span a) (syntax-span b))))]) + (unless graph? + (set-box! ht (hash-set (unbox ht) v #f))) + (cond + [graph? (datum->syntax #f + (make-graph-defn r graph-box) + (vector #f line col (+ delta col) + (+ inc (syntax-span r))))] + [(unbox graph-box) + ;; Go again... + (set-box! ht orig-ht) + (do-syntax-ize v col line ht #t qq #f)] + [else r]))))] + [(box? v) + (let* ([delta (if (and qq (zero? qq)) + 5 ; "(box " + 2)] ; "#&" + [a (do-syntax-ize (unbox v) (+ col delta) line ht #f qq #f)]) + (datum->syntax #f + (box a) + (vector #f line col (+ 1 col) + (+ delta (if (and qq (zero? qq)) 1 0) (syntax-span a)))))] + [(hash? v) + (let* ([delta (cond + [(hash-eq? v) 7] + [(hash-eqv? v) 8] + [else 6])] + [undelta (if (and qq (zero? qq)) + (- delta 1) + 0)] + [pairs (if (and qq (zero? qq)) + (let ([ls (do-syntax-ize (apply append (hash-map v (lambda (k v) (list k v)))) + (+ col delta -1) line ht #f qq #t)]) + (datum->syntax + #f + (let loop ([l (syntax->list ls)]) + (if (null? l) + null + (cons (cons (car l) (cadr l)) (loop (cddr l))))) + ls)) + (do-syntax-ize (hash-map v make-forced-pair) (+ col delta) line ht #f qq #f))]) + (datum->syntax #f + ((cond + [(hash-eq? v) make-immutable-hasheq] + [(hash-eqv? v) make-immutable-hasheqv] + [else make-immutable-hash]) + (map (lambda (p) + (let ([p (syntax-e p)]) + (cons (syntax->datum (car p)) + (cdr p)))) + (syntax->list pairs))) + (vector (syntax-source pairs) + (syntax-line pairs) + (max 0 (- (syntax-column pairs) undelta)) + (max 1 (- (syntax-position pairs) undelta)) + (+ (syntax-span pairs) undelta))))] + [else + (datum->syntax #f v (vector #f line col (+ 1 col) 1))]))) diff --git a/collects/scribble/render-struct.ss b/collects/scribble/render-struct.rkt similarity index 100% rename from collects/scribble/render-struct.ss rename to collects/scribble/render-struct.rkt diff --git a/collects/scribble/run.ss b/collects/scribble/run.rkt similarity index 97% rename from collects/scribble/run.ss rename to collects/scribble/run.rkt index e6dc7078..828cffaf 100644 --- a/collects/scribble/run.ss +++ b/collects/scribble/run.rkt @@ -1,4 +1,4 @@ -#lang scheme/base +#lang racket/base (require "core.ss" "base-render.ss" @@ -6,6 +6,7 @@ scheme/cmdline scheme/file scheme/class + raco/command-name (prefix-in text: "text-render.ss") (prefix-in html: "html-render.ss") (prefix-in latex: "latex-render.ss") @@ -33,11 +34,14 @@ (let ([v (read i)]) (and (eof-object? (read i)) v))))) +(current-render-mixin html:render-mixin) + (define (run) (command-line + #:program (short-program+command-name) #:once-any [("--text") "generate text-format output (the default)" - (void)] + (current-render-mixin text:render-mixin)] [("--html") "generate HTML-format output file" (current-render-mixin html:render-mixin)] [("--htmls") "generate HTML-format output directory" diff --git a/collects/scribble/scheme.rkt b/collects/scribble/scheme.rkt new file mode 100644 index 00000000..67b1f198 --- /dev/null +++ b/collects/scribble/scheme.rkt @@ -0,0 +1,3 @@ +#lang racket/base +(require "racket.ss") +(provide (all-from-out "racket.ss")) diff --git a/collects/scribble/scheme.ss b/collects/scribble/scheme.ss deleted file mode 100644 index be6e3453..00000000 --- a/collects/scribble/scheme.ss +++ /dev/null @@ -1,910 +0,0 @@ -(module scheme scheme/base - (require "core.ss" - "basic.ss" - "search.ss" - "private/manual-sprop.ss" - "private/on-demand.ss" - mzlib/class - mzlib/for - syntax/modresolve - syntax/modcode - (for-syntax scheme/base)) - - (provide define-code - to-element - to-element/no-color - to-paragraph - to-paragraph/prefix - syntax-ize - syntax-ize-hook - current-keyword-list - current-variable-list - current-meta-list - - input-color - output-color - input-background-color - no-color - reader-color - result-color - keyword-color - comment-color - paren-color - meta-color - value-color - symbol-color - variable-color - opt-color - error-color - syntax-link-color - value-link-color - module-color - module-link-color - block-color - highlighted-color - - (struct-out var-id) - (struct-out shaped-parens) - (struct-out just-context) - (struct-out alternate-display) - (struct-out literal-syntax) - (for-syntax make-variable-id - variable-id? - make-element-id-transformer - element-id-transformer?)) - - (define (make-scheme-style s #:tt? [tt? #t]) - (make-style s (if tt? - (cons 'tt-chars scheme-properties) - scheme-properties))) - - (define-on-demand output-color (make-scheme-style "ScmOut")) - (define-on-demand input-color (make-scheme-style "ScmIn")) - (define-on-demand input-background-color (make-scheme-style "ScmInBG")) - (define-on-demand no-color (make-scheme-style "ScmPlain")) - (define-on-demand reader-color (make-scheme-style "ScmRdr")) - (define-on-demand result-color (make-scheme-style "ScmRes")) - (define-on-demand keyword-color (make-scheme-style "ScmKw")) - (define-on-demand comment-color (make-scheme-style "ScmCmt")) - (define-on-demand paren-color (make-scheme-style "ScmPn")) - (define-on-demand meta-color (make-scheme-style "ScmMeta")) - (define-on-demand value-color (make-scheme-style "ScmVal")) - (define-on-demand symbol-color (make-scheme-style "ScmSym")) - (define-on-demand variable-color (make-scheme-style "ScmVar")) - (define-on-demand opt-color (make-scheme-style "ScmOpt")) - (define-on-demand error-color (make-scheme-style "ScmErr" #:tt? #f)) - (define-on-demand syntax-link-color (make-scheme-style "ScmStxLink")) - (define-on-demand value-link-color (make-scheme-style "ScmValLink")) - (define-on-demand module-color (make-scheme-style "ScmMod")) - (define-on-demand module-link-color (make-scheme-style "ScmModLink")) - (define-on-demand block-color (make-scheme-style "ScmBlk")) - (define-on-demand highlighted-color (make-scheme-style "highlighted" #:tt? #f)) - - (define current-keyword-list - (make-parameter null)) - (define current-variable-list - (make-parameter null)) - (define current-meta-list - (make-parameter null)) - - (define defined-names (make-hasheq)) - - (define-struct (sized-element element) (length)) - - (define-struct (spaces element) (cnt)) - - (define (literalize-spaces i) - (let ([m (regexp-match-positions #rx" +" i)]) - (if m - (let ([cnt (- (cdar m) (caar m))]) - (make-spaces #f - (list - (literalize-spaces (substring i 0 (caar m))) - (hspace cnt) - (literalize-spaces (substring i (cdar m)))) - cnt)) - i))) - - - (define line-breakable-space (make-element 'tt " ")) - - ;; These caches intentionally record a key with the value. - ;; That way, when the value is no longer used, the key - ;; goes away, and the entry is gone. - - (define id-element-cache (make-weak-hash)) - (define element-cache (make-weak-hash)) - - (define-struct (cached-delayed-element delayed-element) (cache-key)) - (define-struct (cached-element element) (cache-key)) - - (define (make-id-element c s) - (let* ([key (and id-element-cache - (let ([b (identifier-label-binding c)]) - (vector (syntax-e c) - (module-path-index->taglet (caddr b)) - (cadddr b) - (list-ref b 5))))]) - (or (and key - (let ([b (hash-ref id-element-cache key #f)]) - (and b - (weak-box-value b)))) - (let ([e (make-cached-delayed-element - (lambda (renderer sec ri) - (let* ([tag (find-scheme-tag sec ri c #f)]) - (if tag - (list - (case (car tag) - [(form) - (make-link-element syntax-link-color (list s) tag)] - [else - (make-link-element value-link-color (list s) tag)])) - (list - (make-element "badlink" - (make-element value-link-color s)))))) - (lambda () s) - (lambda () s) - key)]) - (when key - (hash-set! id-element-cache key (make-weak-box e))) - e)))) - - (define (make-element/cache style content) - (if (and element-cache - (string? content)) - (let ([key (vector style content)]) - (let ([b (hash-ref element-cache key #f)]) - (or (and b (weak-box-value b)) - (let ([e (make-cached-element style content key)]) - (hash-set! element-cache key (make-weak-box e)) - e)))) - (make-element style content))) - - (define (typeset-atom c out color? quote-depth) - (if (and (var-id? (syntax-e c)) - (zero? quote-depth)) - (out (format "~s" (let ([v (var-id-sym (syntax-e c))]) - (if (syntax? v) - (syntax-e v) - v))) - variable-color) - (let*-values ([(is-var?) (and (identifier? c) - (memq (syntax-e c) (current-variable-list)))] - [(s it? sub?) - (let ([sc (syntax-e c)]) - (let ([s (or (syntax-property c 'display-string) - (format "~s" (if (literal-syntax? sc) - (literal-syntax-stx sc) - (if (var-id? sc) - (var-id-sym sc) - sc))))]) - (if (and (symbol? sc) - ((string-length s) . > . 1) - (char=? (string-ref s 0) #\_) - (not (or (identifier-label-binding c) - is-var?))) - (values (substring s 1) #t #f) - (values s #f #f))))]) - (if (or (element? (syntax-e c)) - (delayed-element? (syntax-e c)) - (part-relative-element? (syntax-e c))) - (out (syntax-e c) #f) - (out (if (and (identifier? c) - color? - (quote-depth . <= . 0) - (not (or it? is-var?))) - (if (pair? (identifier-label-binding c)) - (make-id-element c s) - s) - (literalize-spaces s)) - (cond - [(positive? quote-depth) value-color] - [(let ([v (syntax-e c)]) - (or (number? v) - (string? v) - (bytes? v) - (char? v) - (regexp? v) - (byte-regexp? v) - (boolean? v))) - value-color] - [(identifier? c) - (cond - [is-var? - variable-color] - [(and (identifier? c) - (memq (syntax-e c) (current-keyword-list))) - keyword-color] - [(and (identifier? c) - (memq (syntax-e c) (current-meta-list))) - meta-color] - [it? variable-color] - [else symbol-color])] - [else paren-color]) - (string-length s)))))) - - (define omitable (make-style #f '(omitable))) - - (define (gen-typeset c multi-line? prefix1 prefix suffix color?) - (let* ([c (syntax-ize c 0)] - [content null] - [docs null] - [first (syntax-case c (code:line) - [(code:line e . rest) #'e] - [else c])] - [init-col (or (syntax-column first) 0)] - [src-col init-col] - [dest-col 0] - [highlight? #f] - [col-map (make-hash)] - [next-col-map (make-hash)] - [line (or (syntax-line first) 0)]) - (define (finish-line!) - (when multi-line? - (set! docs (cons (make-paragraph omitable (reverse content)) - docs)) - (set! content null))) - (define out - (case-lambda - [(v cls) - (out v cls (let sz-loop ([v v]) - (cond - [(string? v) (string-length v)] - [(list? v) (for/fold ([s 0]) ([v (in-list v)]) (+ s (sz-loop v)))] - [(sized-element? v) (sized-element-length v)] - [(element? v) - (sz-loop (element-content v))] - [(delayed-element? v) - (content-width v)] - [(part-relative-element? v) - (content-width v)] - [(spaces? v) - (+ (sz-loop (car (element-content v))) - (spaces-cnt v) - (sz-loop (caddr (element-content v))))] - [else 1])))] - [(v cls len) - (unless (equal? v "") - (cond - [(spaces? v) - (out (car (element-content v)) cls 0) - (out (cadr (element-content v)) #f 0) - (out (caddr (element-content v)) cls len)] - [(equal? v "\n") - (if multi-line? - (begin - (finish-line!) - (out prefix cls)) - (out " " cls))] - [else - (set! content (cons ((if highlight? - (lambda (c) - (make-element highlighted-color c)) - values) - (if (and color? cls) - (make-element/cache cls v) - v)) - content)) - (set! dest-col (+ dest-col len))]))])) - (define advance - (case-lambda - [(c init-line! delta) - (let ([c (+ delta (or (syntax-column c) 0))] - [l (syntax-line c)]) - (let ([new-line? (and l (l . > . line))]) - (when new-line? - (for ([i (in-range (- l line))]) - (out "\n" no-color)) - (set! line l) - (set! col-map next-col-map) - (set! next-col-map (make-hash)) - (init-line!)) - (let ([d-col (let ([def-val (+ dest-col (- c src-col))]) - (if new-line? - (hash-ref col-map c def-val) - def-val))]) - (let ([amt (- d-col dest-col)]) - (when (positive? amt) - (let ([old-dest-col dest-col]) - (out (if (and (= 1 amt) (not multi-line?)) - line-breakable-space ; allows a line break to replace the space - (hspace amt)) - #f) - (set! dest-col (+ old-dest-col amt)))))) - (set! src-col c) - (hash-set! next-col-map src-col dest-col)))] - [(c init-line!) (advance c init-line! 0)])) - (define (convert-infix c quote-depth) - (let ([l (syntax->list c)]) - (and l - ((length l) . >= . 3) - ((or (syntax-position (car l)) -inf.0) - . > . - (or (syntax-position (cadr l)) +inf.0)) - (let ([a (car l)]) - (let loop ([l (cdr l)] - [prev null]) - (cond - [(null? l) #f] ; couldn't unwind - [else (let ([p2 (syntax-position (car l))]) - (if (and p2 - (p2 . > . (syntax-position a))) - (datum->syntax c - (append - (reverse prev) - (list - (datum->syntax - a - (let ([val? (positive? quote-depth)]) - (make-sized-element - (if val? value-color #f) - (list - (make-element/cache (if val? value-color paren-color) '". ") - (typeset a #f "" "" "" (not val?)) - (make-element/cache (if val? value-color paren-color) '" .")) - (+ (syntax-span a) 4))) - (list (syntax-source a) - (syntax-line a) - (- (syntax-column a) 2) - (- (syntax-position a) 2) - (+ (syntax-span a) 4)) - a)) - l) - c - c) - (loop (cdr l) - (cons (car l) prev))))])))))) - (define (no-fancy-chars s) - (cond - [(eq? s 'rsquo) "'"] - [else s])) - (define (loop init-line! quote-depth) - (lambda (c) - (cond - [(eq? 'code:blank (syntax-e c)) - (advance c init-line!)] - [(and (pair? (syntax-e c)) - (eq? (syntax-e (car (syntax-e c))) 'code:comment)) - (let ([l (syntax->list c)]) - (unless (and l (= 2 (length l))) - (raise-syntax-error - #f - "does not have a single sub-form" - c))) - (advance c init-line!) - (out ";" comment-color) - (out 'nbsp comment-color) - (let ([v (syntax->datum (cadr (syntax->list c)))]) - (if (paragraph? v) - (map (lambda (v) - (let ([v (no-fancy-chars v)]) - (if (or (string? v) (symbol? v)) - (out v comment-color) - (out v #f)))) - (paragraph-content v)) - (out (no-fancy-chars v) comment-color)))] - [(and (pair? (syntax-e c)) - (eq? (syntax-e (car (syntax-e c))) 'code:contract)) - (advance c init-line!) - (out "; " comment-color) - (let* ([l (cdr (syntax->list c))] - [s-col (or (syntax-column (car l)) src-col)]) - (set! src-col s-col) - (for-each (loop (lambda () - (set! src-col s-col) - (set! dest-col 0) - (out "; " comment-color)) - 0) - l))] - [(and (pair? (syntax-e c)) - (eq? (syntax-e (car (syntax-e c))) 'code:line)) - (let ([l (cdr (syntax->list c))]) - (for-each (loop init-line! quote-depth) - l))] - [(and (pair? (syntax-e c)) - (eq? (syntax-e (car (syntax-e c))) 'code:hilite)) - (let ([l (syntax->list c)] - [h? highlight?]) - (unless (and l (= 2 (length l))) - (error "bad code:redex: ~e" (syntax->datum c))) - (advance c init-line!) - (set! src-col (syntax-column (cadr l))) - (hash-set! next-col-map src-col dest-col) - (set! highlight? #t) - ((loop init-line! quote-depth) (cadr l)) - (set! highlight? h?) - (set! src-col (add1 src-col)))] - [(and (pair? (syntax-e c)) - (eq? (syntax-e (car (syntax-e c))) 'code:quote)) - (advance c init-line!) - (out "(" (if (positive? quote-depth) value-color paren-color)) - (set! src-col (+ src-col 1)) - (hash-set! next-col-map src-col dest-col) - ((loop init-line! quote-depth) - (datum->syntax #'here 'quote (car (syntax-e c)))) - (for-each (loop init-line! (add1 quote-depth)) - (cdr (syntax->list c))) - (out ")" (if (positive? quote-depth) value-color paren-color)) - (set! src-col (+ src-col 1)) - #; - (hash-set! next-col-map src-col dest-col)] - [(and (pair? (syntax-e c)) - (memq (syntax-e (car (syntax-e c))) - '(quote quasiquote unquote unquote-splicing - quasisyntax syntax unsyntax unsyntax-splicing)) - (let ([v (syntax->list c)]) - (and v (= 2 (length v))))) - (advance c init-line!) - (let-values ([(str quote-delta) - (case (syntax-e (car (syntax-e c))) - [(quote) (values "'" +inf.0)] - [(unquote) (values "," -1)] - [(unquote-splicing) (values ",@" -1)] - [(quasiquote) (values "`" +1)] - [(syntax) (values "#'" 0)] - [(quasisyntax) (values "#`" 0)] - [(unsyntax) (values "#," 0)] - [(unsyntax-splicing) (values "#,@" 0)])]) - (out str (if (positive? (+ quote-depth quote-delta)) - value-color - reader-color)) - (let ([i (cadr (syntax->list c))]) - (set! src-col (or (syntax-column i) src-col)) - (hash-set! next-col-map src-col dest-col) - ((loop init-line! (+ quote-depth quote-delta)) i)))] - [(and (pair? (syntax-e c)) - (convert-infix c quote-depth)) - => (lambda (converted) - ((loop init-line! quote-depth) converted))] - [(or (pair? (syntax-e c)) - (null? (syntax-e c)) - (vector? (syntax-e c)) - (and (struct? (syntax-e c)) - (prefab-struct-key (syntax-e c)))) - (let* ([sh (or (syntax-property c 'paren-shape) - #\()] - [quote-depth (if (and (zero? quote-depth) - (or (vector? (syntax-e c)) - (struct? (syntax-e c)))) - +inf.0 - quote-depth)] - [p-color (if (positive? quote-depth) - value-color - (if (eq? sh #\?) - opt-color - paren-color))]) - (advance c init-line!) - (when (vector? (syntax-e c)) - (let ([vec (syntax-e c)]) - (out "#" #;(format "#~a" (vector-length vec)) p-color) - (if (zero? (vector-length vec)) - (set! src-col (+ src-col (- (syntax-span c) 2))) - (set! src-col (+ src-col (- (syntax-column (vector-ref vec 0)) - (syntax-column c) - 1)))))) - (when (struct? (syntax-e c)) - (out "#s" p-color) - (set! src-col (+ src-col 2))) - (out (case sh - [(#\[ #\?) "["] - [(#\{) "{"] - [else "("]) - p-color) - (set! src-col (+ src-col 1)) - (hash-set! next-col-map src-col dest-col) - (let lloop ([l (cond - [(vector? (syntax-e c)) - (vector->short-list (syntax-e c) syntax-e)] - [(struct? (syntax-e c)) - (let ([l (vector->list (struct->vector (syntax-e c)))]) - ;; Need to build key datum, syntax-ize it internally, and - ;; set the overall width to fit right: - (cons (let ([key (syntax-ize (prefab-struct-key (syntax-e c)) - (+ 3 (or (syntax-column c) 0)) - (or (syntax-line c) 1))] - [end (if (pair? (cdr l)) - (and (equal? (syntax-line c) (syntax-line (cadr l))) - (syntax-column (cadr l))) - (and (syntax-column c) - (+ (syntax-column c) (syntax-span c))))]) - (if end - (datum->syntax #f - (syntax-e key) - (vector #f (syntax-line key) - (syntax-column key) - (syntax-position key) - (- end 1 (syntax-column key)))) - end)) - (cdr l)))] - [else c])]) - (cond - [(and (syntax? l) - (pair? (syntax-e l)) - (not (and (memq (syntax-e (car (syntax-e l))) - '(quote unquote syntax unsyntax quasiquote quasiunsyntax)) - (let ([v (syntax->list l)]) - (and v (= 2 (length v))))))) - (lloop (syntax-e l))] - [(or (null? l) - (and (syntax? l) - (null? (syntax-e l)))) - (void)] - [(pair? l) - ((loop init-line! quote-depth) (car l)) - (lloop (cdr l))] - [else - (advance l init-line! -2) - (out ". " (if (positive? quote-depth) value-color paren-color)) - (set! src-col (+ src-col 3)) - (hash-set! next-col-map src-col dest-col) - ((loop init-line! quote-depth) l)])) - (out (case sh - [(#\[ #\?) "]"] - [(#\{) "}"] - [else ")"]) - p-color) - (set! src-col (+ src-col 1)) - #; - (hash-set! next-col-map src-col dest-col))] - [(box? (syntax-e c)) - (advance c init-line!) - (out "#&" value-color) - (set! src-col (+ src-col 2)) - (hash-set! next-col-map src-col dest-col) - ((loop init-line! +inf.0) (unbox (syntax-e c)))] - [(hash? (syntax-e c)) - (advance c init-line!) - (let ([equal-table? (not (hash-eq? (syntax-e c)))]) - (out (if equal-table? - "#hash" - "#hasheq") - value-color) - (let ([delta (+ 5 (if equal-table? 2 0))] - [orig-col src-col]) - (set! src-col (+ src-col delta)) - (hash-set! next-col-map src-col dest-col) - ((loop init-line! +inf.0) - (syntax-ize (hash-map (syntax-e c) cons) - (+ (syntax-column c) delta))) - (set! src-col (+ orig-col (syntax-span c)))))] - [(graph-reference? (syntax-e c)) - (advance c init-line!) - (out (format "#~a#" (unbox (graph-reference-bx (syntax-e c)))) - (if (positive? quote-depth) - value-color - paren-color)) - (set! src-col (+ src-col (syntax-span c)))] - [(graph-defn? (syntax-e c)) - (advance c init-line!) - (let ([bx (graph-defn-bx (syntax-e c))]) - (out (format "#~a=" (unbox bx)) - (if (positive? quote-depth) - value-color - paren-color)) - (set! src-col (+ src-col 3)) - ((loop init-line! quote-depth) (graph-defn-r (syntax-e c))))] - [else - (advance c init-line!) - (typeset-atom c out color? quote-depth) - (set! src-col (+ src-col (or (syntax-span c) 1))) - #; - (hash-set! next-col-map src-col dest-col)]))) - (out prefix1 #f) - (set! dest-col 0) - (hash-set! next-col-map init-col dest-col) - ((loop (lambda () (set! src-col init-col) (set! dest-col 0)) 0) c) - (if (list? suffix) - (map (lambda (sfx) - (finish-line!) - (out sfx #f)) - suffix) - (out suffix #f)) - (unless (null? content) - (finish-line!)) - (if multi-line? - (if (= 1 (length docs)) - (car docs) - (make-table block-color (map list (reverse docs)))) - (make-sized-element #f (reverse content) dest-col)))) - - (define (typeset c multi-line? prefix1 prefix suffix color?) - (let* ([c (syntax-ize c 0)] - [s (syntax-e c)]) - (if (or multi-line? - (eq? 'code:blank s) - (pair? s) - (vector? s) - (struct? s) - (box? s) - (null? s) - (hash? s) - (graph-defn? s) - (graph-reference? s)) - (gen-typeset c multi-line? prefix1 prefix suffix color?) - (typeset-atom c - (letrec ([mk - (case-lambda - [(elem color) - (mk elem color (or (syntax-span c) 1))] - [(elem color len) - (if (and (string? elem) - (= len (string-length elem))) - (make-element/cache (and color? color) elem) - (make-sized-element (and color? color) elem len))])]) - mk) - color? 0)))) - - (define (to-element c) - (typeset c #f "" "" "" #t)) - - (define (to-element/no-color c) - (typeset c #f "" "" "" #f)) - - (define (to-paragraph c) - (typeset c #t "" "" "" #t)) - - (define ((to-paragraph/prefix pfx1 pfx sfx) c) - (typeset c #t pfx1 pfx sfx #t)) - - (begin-for-syntax - (define-struct variable-id (sym) - #:omit-define-syntaxes - #:property prop:procedure (lambda (self stx) - (raise-syntax-error - #f - (string-append - "misuse of an identifier (not in `scheme', etc.) that is" - " bound as a code-typesetting variable") - stx))) - (define-struct element-id-transformer (proc) - #:omit-define-syntaxes - #:property prop:procedure (lambda (self stx) - (raise-syntax-error - #f - (string-append - "misuse of an identifier (not in `scheme', etc.) that is" - " bound as an code-typesetting element transformer") - stx)))) - - (define-syntax (define-code stx) - (syntax-case stx () - [(_ code typeset-code uncode d->s stx-prop) - (syntax/loc stx - (define-syntax (code stx) - (define (wrap-loc v ctx e) - `(,#'d->s ,ctx - ,e - #(code - ,(syntax-line v) - ,(syntax-column v) - ,(syntax-position v) - ,(syntax-span v)))) - (define (stx->loc-s-expr v) - (let ([slv (and (identifier? v) - (syntax-local-value v (lambda () #f)))]) - (cond - [(variable-id? slv) - (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))] - [(element-id-transformer? slv) - (wrap-loc v #f ((element-id-transformer-proc slv) v))] - [(syntax? v) - (let ([mk (wrap-loc - v - `(quote-syntax ,(datum->syntax v 'defcode)) - (syntax-case v (uncode) - [(uncode e) #'e] - [else (stx->loc-s-expr (syntax-e v))]))]) - (let ([prop (syntax-property v 'paren-shape)]) - (if prop - `(,#'stx-prop ,mk 'paren-shape ,prop) - mk)))] - [(null? v) 'null] - [(list? v) `(list . ,(map stx->loc-s-expr v))] - [(pair? v) `(cons ,(stx->loc-s-expr (car v)) - ,(stx->loc-s-expr (cdr v)))] - [(vector? v) `(vector ,@(map - stx->loc-s-expr - (vector->list v)))] - [(and (struct? v) (prefab-struct-key v)) - `(make-prefab-struct (quote ,(prefab-struct-key v)) - ,@(map - stx->loc-s-expr - (cdr (vector->list (struct->vector v)))))] - [(box? v) `(box ,(stx->loc-s-expr (unbox v)))] - [else `(quote ,v)]))) - (define (cvt s) - (datum->syntax #'here (stx->loc-s-expr s) #f)) - (if (eq? (syntax-local-context) 'expression) - (syntax-case stx () - [(_ expr) #`(typeset-code #,(cvt #'expr))] - [(_ expr (... ...)) - #`(typeset-code #,(cvt #'(code:line expr (... ...))))]) - (quasisyntax/loc stx - (#%expression #,stx)))))] - [(_ code typeset-code uncode d->s) - #'(define-code code typeset-code uncode d->s syntax-property)] - [(_ code typeset-code uncode) - #'(define-code code typeset-code uncode datum->syntax syntax-property)] - [(_ code typeset-code) #'(define-code code typeset-code unsyntax)])) - - - (define syntax-ize-hook (make-parameter (lambda (v col) #f))) - - (define (vector->short-list v extract) - (vector->list v) - #; - (let ([l (vector->list v)]) - (reverse (list-tail - (reverse l) - (- (vector-length v) - (let loop ([i (sub1 (vector-length v))]) - (cond - [(zero? i) 1] - [(eq? (extract (vector-ref v i)) - (extract (vector-ref v (sub1 i)))) - (loop (sub1 i))] - [else (add1 i)]))))))) - - (define (short-list->vector v l) - (list->vector - (let ([n (length l)]) - (if (n . < . (vector-length v)) - (reverse (let loop ([r (reverse l)][i (- (vector-length v) n)]) - (if (zero? i) - r - (loop (cons (car r) r) (sub1 i))))) - l)))) - - (define-struct var-id (sym)) - (define-struct shaped-parens (val shape)) - (define-struct just-context (val ctx)) - (define-struct alternate-display (id string)) - (define-struct literal-syntax (stx)) - - (define-struct graph-reference (bx)) - (define-struct graph-defn (r bx)) - - (define (syntax-ize v col [line 1]) - (do-syntax-ize v col line (box #hasheq()) #f)) - - (define (graph-count ht graph?) - (and graph? - (let ([n (hash-ref (unbox ht) '#%graph-count 0)]) - (set-box! ht (hash-set (unbox ht) '#%graph-count (add1 n))) - n))) - - (define (do-syntax-ize v col line ht graph?) - (cond - [((syntax-ize-hook) v col) - => (lambda (r) r)] - [(shaped-parens? v) - (syntax-property (do-syntax-ize (shaped-parens-val v) col line ht #f) - 'paren-shape - (shaped-parens-shape v))] - [(just-context? v) - (let ([s (do-syntax-ize (just-context-val v) col line ht #f)]) - (datum->syntax (just-context-ctx v) - (syntax-e s) - s - s - (just-context-ctx v)))] - [(alternate-display? v) - (let ([s (do-syntax-ize (alternate-display-id v) col line ht #f)]) - (syntax-property s - 'display-string - (alternate-display-string v)))] - [(hash-ref (unbox ht) v #f) - => (lambda (m) - (unless (unbox m) - (set-box! m #t)) - (datum->syntax #f - (make-graph-reference m) - (vector #f line col (+ 1 col) 1)))] - [(and (list? v) - (pair? v) - (memq (let ([s (car v)]) - (if (just-context? s) - (just-context-val s) - s)) - '(quote unquote unquote-splicing))) - (let ([c (do-syntax-ize (cadr v) (+ col 1) line ht #f)]) - (datum->syntax #f - (list (do-syntax-ize (car v) col line ht #f) - c) - (vector #f line col (+ 1 col) - (+ 1 (syntax-span c)))))] - [(or (list? v) - (vector? v) - (and (struct? v) - (prefab-struct-key v))) - (let ([orig-ht (unbox ht)] - [graph-box (box (graph-count ht graph?))]) - (set-box! ht (hash-set (unbox ht) v graph-box)) - (let* ([graph-sz (if graph? - (+ 2 (string-length (format "~a" (unbox graph-box)))) - 0)] - [vec-sz (cond - [(vector? v) - (+ 1 #;(string-length (format "~a" (vector-length v))))] - [(struct? v) 2] - [else 0])] - [r (let ([l (let loop ([col (+ col 1 vec-sz graph-sz)] - [v (cond - [(vector? v) - (vector->short-list v values)] - [(struct? v) - (cons (prefab-struct-key v) - (cdr (vector->list (struct->vector v))))] - [else v])]) - (if (null? v) - null - (let ([i (do-syntax-ize (car v) col line ht #f)]) - (cons i - (loop (+ col 1 (syntax-span i)) (cdr v))))))]) - (datum->syntax #f - (cond - [(vector? v) (short-list->vector v l)] - [(struct? v) - (apply make-prefab-struct (prefab-struct-key v) (cdr l))] - [else l]) - (vector #f line - (+ graph-sz col) - (+ 1 graph-sz col) - (+ 2 - vec-sz - (if (zero? (length l)) - 0 - (sub1 (length l))) - (apply + (map syntax-span l))))))]) - (unless graph? - (set-box! ht (hash-set (unbox ht) v #f))) - (cond - [graph? (datum->syntax #f - (make-graph-defn r graph-box) - (vector #f (syntax-line r) - (- (syntax-column r) graph-sz) - (- (syntax-position r) graph-sz) - (+ (syntax-span r) graph-sz)))] - [(unbox graph-box) - ;; Go again, this time knowing that there will be a graph: - (set-box! ht orig-ht) - (do-syntax-ize v col line ht #t)] - [else r])))] - [(pair? v) - (let ([orig-ht (unbox ht)] - [graph-box (box (graph-count ht graph?))]) - (set-box! ht (hash-set (unbox ht) v graph-box)) - (let* ([inc (if graph? - (+ 2 (string-length (format "~a" (unbox graph-box)))) - 0)] - [a (do-syntax-ize (car v) (+ col 1 inc) line ht #f)] - [sep (if (and (pair? (cdr v)) - ;; FIXME: what if it turns out to be a graph reference? - (not (hash-ref (unbox ht) (cdr v) #f))) - 0 - 3)] - [b (do-syntax-ize (cdr v) (+ col 1 inc (syntax-span a) sep) line ht #f)]) - (let ([r (datum->syntax #f - (cons a b) - (vector #f line (+ col inc) (+ 1 col inc) - (+ 2 sep (syntax-span a) (syntax-span b))))]) - (unless graph? - (set-box! ht (hash-set (unbox ht) v #f))) - (cond - [graph? (datum->syntax #f - (make-graph-defn r graph-box) - (vector #f line col (+ 1 col) - (+ inc (syntax-span r))))] - [(unbox graph-box) - ;; Go again... - (set-box! ht orig-ht) - (do-syntax-ize v col line ht #t)] - [else r]))))] - [(box? v) - (let ([a (do-syntax-ize (unbox v) (+ col 2) line ht #f)]) - (datum->syntax #f - (box a) - (vector #f line col (+ 1 col) - (+ 2 (syntax-span a)))))] - [else - (datum->syntax #f v (vector #f line col (+ 1 col) 1))]))) diff --git a/collects/scribble/scribble-common.js b/collects/scribble/scribble-common.js index cc37899a..09c33909 100644 --- a/collects/scribble/scribble-common.js +++ b/collects/scribble/scribble-common.js @@ -54,8 +54,11 @@ function MergePageArgsIntoLink(a) { // Cookies -------------------------------------------------------------------- function GetCookie(key, def) { - if (document.cookie.length <= 0) return def; - var i, cookiestrs = document.cookie.split(/; */); + var i, cookiestrs; + try { + if (document.cookie.length <= 0) return def; + cookiestrs = document.cookie.split(/; */); + } catch (e) { return def; } for (i = 0; i < cookiestrs.length; i++) { var cur = cookiestrs[i]; var eql = cur.indexOf('='); @@ -68,8 +71,10 @@ function GetCookie(key, def) { function SetCookie(key, val) { var d = new Date(); d.setTime(d.getTime()+(365*24*60*60*1000)); - document.cookie = - key + "=" + escape(val) + "; expires="+ d.toGMTString() + "; path=/"; + try { + document.cookie = + key + "=" + escape(val) + "; expires="+ d.toGMTString() + "; path=/"; + } catch (e) {} } // note that this always stores a directory name, ending with a "/" diff --git a/collects/scribble/search.ss b/collects/scribble/search.rkt similarity index 97% rename from collects/scribble/search.ss rename to collects/scribble/search.rkt index 796ef575..f5187add 100644 --- a/collects/scribble/search.ss +++ b/collects/scribble/search.rkt @@ -1,10 +1,11 @@ -(module search scheme/base +(module search racket/base (require "struct.ss" "basic.ss" setup/main-collects syntax/modcode) - (provide find-scheme-tag) + (provide find-racket-tag + (rename-out [find-racket-tag find-scheme-tag])) (define module-info-cache (make-hasheq)) @@ -21,7 +22,7 @@ (with-handlers* ([exn:fail? (lambda (exn) (fail-thunk))]) (thunk))) - (define (find-scheme-tag part ri stx/binding phase-level) + (define (find-racket-tag part ri stx/binding phase-level) ;; The phase-level argument is used only when `stx/binding' ;; is an identifier. ;; @@ -169,7 +170,7 @@ ;; have changed in inconsistent ways. So just say #f ;; for now. #; - (error 'find-scheme-tag + (error 'find-racket-tag "dead end when looking for binding source: ~e" id) (loop queue rqueue need-result?))))) diff --git a/collects/scribble/sigplan.ss b/collects/scribble/sigplan.rkt similarity index 100% rename from collects/scribble/sigplan.ss rename to collects/scribble/sigplan.rkt diff --git a/collects/scribble/sigplan/lang.ss b/collects/scribble/sigplan/lang.rkt similarity index 100% rename from collects/scribble/sigplan/lang.ss rename to collects/scribble/sigplan/lang.rkt diff --git a/collects/scribble/sigplan/lang/reader.rkt b/collects/scribble/sigplan/lang/reader.rkt new file mode 100644 index 00000000..3963d6e5 --- /dev/null +++ b/collects/scribble/sigplan/lang/reader.rkt @@ -0,0 +1,3 @@ +#lang s-exp scribble/base/reader +scribble/sigplan/lang +#:wrapper1 (lambda (t) (cons 'doc (t))) diff --git a/collects/scribble/sigplan/lang/reader.ss b/collects/scribble/sigplan/lang/reader.ss deleted file mode 100644 index a1712dc6..00000000 --- a/collects/scribble/sigplan/lang/reader.ss +++ /dev/null @@ -1,15 +0,0 @@ -#lang s-exp syntax/module-reader - -scribble/sigplan/lang - -#:read scribble:read-inside -#:read-syntax scribble:read-syntax-inside -#:whole-body-readers? #t -#:wrapper1 (lambda (t) (cons 'doc (t))) -#:info (lambda (key defval default) - (case key - [(color-lexer) - (dynamic-require 'syntax-color/scribble-lexer 'scribble-inside-lexer)] - [else (default key defval)])) - -(require (prefix-in scribble: "../../reader.ss")) diff --git a/collects/scribble/srcdoc.ss b/collects/scribble/srcdoc.rkt similarity index 100% rename from collects/scribble/srcdoc.ss rename to collects/scribble/srcdoc.rkt diff --git a/collects/scribble/struct.ss b/collects/scribble/struct.rkt similarity index 100% rename from collects/scribble/struct.ss rename to collects/scribble/struct.rkt diff --git a/collects/scribble/text-render.ss b/collects/scribble/text-render.rkt similarity index 100% rename from collects/scribble/text-render.ss rename to collects/scribble/text-render.rkt diff --git a/collects/scribble/text.rkt b/collects/scribble/text.rkt new file mode 100644 index 00000000..90c106d5 --- /dev/null +++ b/collects/scribble/text.rkt @@ -0,0 +1,5 @@ +#lang racket/base + +(require racket/promise "text/output.ss" "text/syntax-utils.ss") +(provide (all-from-out racket/promise "text/output.ss") + begin/text include/text) diff --git a/collects/scribble/text.ss b/collects/scribble/text.ss deleted file mode 100644 index 65329845..00000000 --- a/collects/scribble/text.ss +++ /dev/null @@ -1,5 +0,0 @@ -#lang scheme/base - -(require scheme/promise "text/output.ss" "text/syntax-utils.ss") -(provide (all-from-out scheme/promise "text/output.ss") - begin/text include/text) diff --git a/collects/scribble/text/lang/reader.rkt b/collects/scribble/text/lang/reader.rkt new file mode 100644 index 00000000..d9660753 --- /dev/null +++ b/collects/scribble/text/lang/reader.rkt @@ -0,0 +1,12 @@ +#lang s-exp syntax/module-reader + +scribble/text/textlang + +#:read scribble:read-inside +#:read-syntax scribble:read-syntax-inside +#:whole-body-readers? #t +#:info (scribble-base-reader-info) + +(require (prefix-in scribble: "../../reader.ss") + (only-in scribble/base/reader + scribble-base-reader-info)) diff --git a/collects/scribble/text/lang/reader.ss b/collects/scribble/text/lang/reader.ss deleted file mode 100644 index 245b6282..00000000 --- a/collects/scribble/text/lang/reader.ss +++ /dev/null @@ -1,9 +0,0 @@ -#lang s-exp syntax/module-reader - -scribble/text/textlang - -#:read scribble:read-inside -#:read-syntax scribble:read-syntax-inside -#:whole-body-readers? #t - -(require (prefix-in scribble: "../../reader.ss")) diff --git a/collects/scribble/text/output.ss b/collects/scribble/text/output.rkt similarity index 100% rename from collects/scribble/text/output.ss rename to collects/scribble/text/output.rkt diff --git a/collects/scribble/text/syntax-utils.ss b/collects/scribble/text/syntax-utils.rkt similarity index 100% rename from collects/scribble/text/syntax-utils.ss rename to collects/scribble/text/syntax-utils.rkt diff --git a/collects/scribble/text/textlang.rkt b/collects/scribble/text/textlang.rkt new file mode 100644 index 00000000..0708781f --- /dev/null +++ b/collects/scribble/text/textlang.rkt @@ -0,0 +1,9 @@ +#lang racket/base + +(require "syntax-utils.ss" "output.ss" racket/promise) + +(provide (except-out (all-from-out racket/base) #%module-begin) + (all-from-out "output.ss" racket/promise) + begin/text + (rename-out [module-begin/text #%module-begin] + [include/text include])) diff --git a/collects/scribble/text/textlang.ss b/collects/scribble/text/textlang.ss deleted file mode 100644 index 9a31fa34..00000000 --- a/collects/scribble/text/textlang.ss +++ /dev/null @@ -1,9 +0,0 @@ -#lang scheme/base - -(require "syntax-utils.ss" "output.ss" scheme/promise) - -(provide (except-out (all-from-out scheme/base) #%module-begin) - (all-from-out "output.ss" scheme/promise) - begin/text - (rename-out [module-begin/text #%module-begin] - [include/text include])) diff --git a/collects/scribble/urls.rkt b/collects/scribble/urls.rkt new file mode 100644 index 00000000..c4604c25 --- /dev/null +++ b/collects/scribble/urls.rkt @@ -0,0 +1,10 @@ +#lang racket/base + +(provide (all-defined-out) + (rename-out [url:drracket url:drscheme] + [url:download-drracket url:download-drscheme])) + +(define url:drracket "http://racket-lang.org/") +(define url:download-drracket "http://racket-lang.org/") + +(define url:planet "http://planet.plt-scheme.org/") diff --git a/collects/scribble/urls.ss b/collects/scribble/urls.ss deleted file mode 100644 index ba8f0538..00000000 --- a/collects/scribble/urls.ss +++ /dev/null @@ -1,8 +0,0 @@ - -(module urls mzscheme - (provide (all-defined)) - - (define url:drscheme "http://www.drscheme.org/") - (define url:download-drscheme "http://download.plt-scheme.org/drscheme/") - - (define url:planet "http://planet.plt-scheme.org/")) diff --git a/collects/scribble/xref.ss b/collects/scribble/xref.rkt similarity index 100% rename from collects/scribble/xref.ss rename to collects/scribble/xref.rkt diff --git a/collects/scribblings/scribble/base.scrbl b/collects/scribblings/scribble/base.scrbl index 7daf57a3..dbfc66b3 100644 --- a/collects/scribblings/scribble/base.scrbl +++ b/collects/scribblings/scribble/base.scrbl @@ -1,7 +1,7 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label setup/main-collects)) @(define-syntax def-section-like @@ -23,23 +23,26 @@ @(define-syntax def-style-proc (syntax-rules () [(_ id) - @def-elem-proc[id]{Like @scheme[elem], but with style @scheme['id].}])) + @def-elem-proc[id]{Like @racket[elem], but with style @racket['id].}])) @title[#:tag "base"]{Base Document Format} -@defmodulelang[scribble/base]{The @schememodname[scribble/base] language -provides functions and forms that can be used from code written either -in Scheme or with @elem["@"] expressions. +@defmodulelang[scribble/base]{The @racketmodname[scribble/base] +language provides functions and forms that can be used from code +written either in Racket or with @elem["@"] expressions. It +essentially extends @racketmodname[racket/base], except that top-level +forms within a module using the @racketmodname[scribble/base] language +are treated as document content (like @racketmodname[scribble/doclang]). -The @schememodname[scribble/base] name can also be used as a -library with @scheme[require], in which case it provides all of the same -bindings, but without setting the reader or setting the default -rendering format to the PLT Scheme manual format.} +The @racketmodname[scribble/base] name can also be used as a library +with @racket[require], in which case it provides only the bindings +defined in this section, and it also does not set the reader or +set the default rendering format to the Racket manual format.} -Functions provided by this library, such as @scheme[title] and -@scheme[italic], might be called from Scheme as +Functions provided by this library, such as @racket[title] and +@racket[italic], might be called from Racket as -@schemeblock[ +@racketblock[ (title #:tag "how-to" "How to Design " (italic "Great") " Programs") ] @@ -51,8 +54,8 @@ They can also be called with @elem["@"] notation as }| Although the procedures are mostly design to be used from @elem["@"] -mode, they are easier to document in Scheme mode (partly because we -have @schememodname[scribble/manual]). +mode, they are easier to document in Racket mode (partly because we +have @racketmodname[scribble/manual]). @; ------------------------------------------------------------------------ @@ -65,70 +68,70 @@ have @schememodname[scribble/manual]). [pre-content pre-content?] ...+) title-decl?]{ -Generates a @scheme[title-decl] to be picked up by @scheme[decode] or -@scheme[decode-part]. The @tech{decode}d @scheme[pre-content] (i.e., -parsed with @scheme[decode-content]) supplies the title content. If -@scheme[tag] is @scheme[#f], a tag string is generated automatically +Generates a @racket[title-decl] to be picked up by @racket[decode] or +@racket[decode-part]. The @tech{decode}d @racket[pre-content] (i.e., +parsed with @racket[decode-content]) supplies the title content. If +@racket[tag] is @racket[#f], a tag string is generated automatically from the content. The tag string is combined with the symbol -@scheme['part] to form the full tag. +@racket['part] to form the full tag. -The @scheme[style] argument can be a style structure, or it can be one -of the following: a @scheme[#f] that corresponds to a ``plain'' style, +The @racket[style] argument can be a style structure, or it can be one +of the following: a @racket[#f] that corresponds to a ``plain'' style, a string that is used as a @tech{style name}, a symbol that is used as a @tech{style property}, or a list of symbols to be used as @tech{style properties}. -For information on styles, see @scheme[part]. For example, a style of -@scheme['toc] causes sub-sections to be generated as separate pages in +For information on styles, see @racket[part]. For example, a style of +@racket['toc] causes sub-sections to be generated as separate pages in multi-page HTML output. -The @scheme[tag-prefix] argument is propagated to the generated -structure (see @secref["tags"]). If @scheme[tag-prefix] is a module +The @racket[tag-prefix] argument is propagated to the generated +structure (see @secref["tags"]). If @racket[tag-prefix] is a module path, it is converted to a string using -@scheme[module-path-prefix->string]. +@racket[module-path-prefix->string]. -The @scheme[vers] argument is propagated to the @scheme[title-decl] -structure. Use @scheme[""] as @scheme[vers] to suppress version +The @racket[vers] argument is propagated to the @racket[title-decl] +structure. Use @racket[""] as @racket[vers] to suppress version rendering in the output. The section title is automatically indexed by -@scheme[decode-part]. For the index key, leading whitespace and a +@racket[decode-part]. For the index key, leading whitespace and a leading ``A'', ``An'', or ``The'' (followed by more whitespace) is removed.} -@def-section-like[section part-start?]{ Like @scheme[title], but - generates a @scheme[part-start] of depth @scheme[0] to be by - @scheme[decode] or @scheme[decode-part].} +@def-section-like[section part-start?]{ Like @racket[title], but + generates a @racket[part-start] of depth @racket[0] to be by + @racket[decode] or @racket[decode-part].} -@def-section-like[subsection part-start?]{ Like @scheme[section], but - generates a @scheme[part-start] of depth @scheme[1].} +@def-section-like[subsection part-start?]{ Like @racket[section], but + generates a @racket[part-start] of depth @racket[1].} -@def-section-like[subsubsection part-start?]{ Like @scheme[section], but - generates a @scheme[part-start] of depth @scheme[2].} +@def-section-like[subsubsection part-start?]{ Like @racket[section], but + generates a @racket[part-start] of depth @racket[2].} @def-section-like[subsubsub*section paragraph?]{ Similar to - @scheme[section], but merely generates a paragraph that looks like an + @racket[section], but merely generates a paragraph that looks like an unnumbered section heading (for when the nesting gets too deep to include in a table of contents).} -@defform[(include-section module-path)]{ Requires @scheme[module-path] - and returns its @scheme[doc] export (without making any imports +@defform[(include-section module-path)]{ Requires @racket[module-path] + and returns its @racket[doc] export (without making any imports visible to the enclosing context). Since this form expands to - @scheme[require], it must be used in a module or top-level context.} + @racket[require], it must be used in a module or top-level context.} @defproc[(author [auth content?] ...) block?]{ -Generates a @scheme[paragraph] with style name @scheme['author] to +Generates a @racket[paragraph] with style name @racket['author] to show the author(s) of a document, where each author is represented by @tech{content}. Normally, this function is used after -@scheme[title] for the beginning of a document. See also -@scheme[author+email].} +@racket[title] for the beginning of a document. See also +@racket[author+email].} @defproc[(author+email [author elem] [email string?] [#:obfuscate? obfuscate? any/c #f]) element?]{ -Combines an author name with an e-mail address. If @scheme[obfuscate?] +Combines an author name with an e-mail address. If @racket[obfuscate?] is true, then the result obscures the e-mail address slightly to avoid address-harvesting robots.} @@ -140,23 +143,23 @@ address-harvesting robots.} [pre-content pre-content?] ...) paragraph?]{ Creates a @tech{paragraph} containing the @tech{decode}d - @scheme[pre-content] (i.e., parsed with @scheme[decode-paragraph]). + @racket[pre-content] (i.e., parsed with @racket[decode-paragraph]). - The @scheme[style] argument can be a style, @scheme[#f] to indicate a + The @racket[style] argument can be a style, @racket[#f] to indicate a ``plain'' style, a string that is used as a @tech{style name}, or a symbol that is used as a @tech{style name}. (Note that - @scheme[section] and @scheme[para] treat symbols differently as - @scheme[style] arguments.)} + @racket[section] and @racket[para] treat symbols differently as + @racket[style] arguments.)} @defproc[(nested [#:style style (or/c style? string? symbol? #f)] [pre-flow pre-flow?] ...) nested-flow?]{ Creates a @tech{nested flow} containing the @tech{decode}d - @scheme[pre-flow] (i.e., parsed with @scheme[decode-flow]). + @racket[pre-flow] (i.e., parsed with @racket[decode-flow]). - The @scheme[style] argument is handled the same as @scheme[para]. - The @scheme['inset] style causes the nested flow to be inset compared + The @racket[style] argument is handled the same as @racket[para]. + The @racket['inset] style causes the nested flow to be inset compared to surrounding text.} @@ -175,25 +178,25 @@ of inlined.} [#:style style (or/c style? string? symbol? #f) #f]) itemization?]{ - Constructs an @scheme[itemization] given a sequence of items - constructed by @scheme[item]. + Constructs an @racket[itemization] given a sequence of items + constructed by @racket[item]. - The @scheme[style] argument is handled the same as @scheme[para]. The - @scheme['ordered] style numbers items, instead of just using a + The @racket[style] argument is handled the same as @racket[para]. The + @racket['ordered] style numbers items, instead of just using a bullet.} @defproc[(item [pre-flow pre-flow?] ...) item?]{ -Creates an item for use with @scheme[itemlist]. The @tech{decode}d -@scheme[pre-flow] (i.e., parsed with @scheme[decode-flow]) is the item +Creates an item for use with @racket[itemlist]. The @tech{decode}d +@racket[pre-flow] (i.e., parsed with @racket[decode-flow]) is the item content.} @defproc[(item? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is an item produced by -@scheme[item], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is an item produced by +@racket[item], @racket[#f] otherwise.} @defproc[(tabular [cells (listof (listof (or/c block? content? 'cont)))] @@ -204,29 +207,29 @@ Creates a @tech{table} with the given content, which is supplies as a list of rows, where each row has a list of cells. The length of all rows must match. -Use @scheme['cont] as a cell to continue the content of the preceding +Use @racket['cont] as a cell to continue the content of the preceding cell in a row in the space that would otherwise be used for a new -cell. A @scheme['cont] must not appear as the first cell in a row. +cell. A @racket['cont] must not appear as the first cell in a row. -The @scheme[style] argument is handled the same as @scheme[para].} +The @racket[style] argument is handled the same as @racket[para].} @defproc[(verbatim [#:indent indent exact-nonnegative-integer? 0] [str string?] ...+) block?]{ -Typesets @scheme[str]s in typewriter font with the linebreaks -specified by newline characters in @scheme[str]. Consecutive spaces in -the @scheme[str]s are converted to @scheme[hspace] to ensure that they +Typesets @racket[str]s in typewriter font with the linebreaks +specified by newline characters in @racket[str]. Consecutive spaces in +the @racket[str]s are converted to @racket[hspace] to ensure that they are all preserved in the output. Additional space (via -@scheme[hspace]) as specified by @scheme[indent] is added to the +@racket[hspace]) as specified by @racket[indent] is added to the beginning of each line. -The @scheme[str]s are @emph{not} decoded with @scheme[decode-content], -so @scheme[(verbatim "---")] renders with three hyphens instead of an -em-dash. Beware, however, that @litchar["@"] for a @scheme[verbatim] +The @racket[str]s are @emph{not} decoded with @racket[decode-content], +so @racket[(verbatim "---")] renders with three hyphens instead of an +em-dash. Beware, however, that @litchar["@"] for a @racket[verbatim] call performs some processing before delivering arguments to -@scheme[verbatim]. The @scheme[verbatim] form is typically used with +@racket[verbatim]. The @racket[verbatim] form is typically used with @litchar["|{"]...@litchar["}|"] or similar brackets to disable -@litchar["@"] notation within the @scheme[verbatim] argument, like +@litchar["@"] notation within the @racket[verbatim] argument, like this: @verbatim[#:indent 2]|{ @@ -245,7 +248,7 @@ Even with @litchar["|{"]...@litchar["}|"], beware that consistent leading whitespace is removed; see @secref["alt-body-syntax"] for more information. -See also @scheme[literal].} +See also @racket[literal].} @; ------------------------------------------------------------------------ @@ -255,8 +258,8 @@ See also @scheme[literal].} [#:style style (or style? string? symbol? #f) #f]) element?]{ -Wraps the @tech{decode}d @scheme[pre-content] as an element with style -@scheme[style].} +Wraps the @tech{decode}d @racket[pre-content] as an element with style +@racket[style].} @def-style-proc[italic] @@ -265,35 +268,35 @@ Wraps the @tech{decode}d @scheme[pre-content] as an element with style @def-style-proc[subscript] @def-style-proc[superscript] -@def-elem-proc[smaller]{Like @scheme[elem], but with style -@scheme['smaller]. When uses of @scheme[smaller] are nested, text +@def-elem-proc[smaller]{Like @racket[elem], but with style +@racket['smaller]. When uses of @racket[smaller] are nested, text gets progressively smaller.} -@def-elem-proc[larger]{Like @scheme[elem], but with style -@scheme['larger]. When uses of @scheme[larger] are nested, text +@def-elem-proc[larger]{Like @racket[elem], but with style +@racket['larger]. When uses of @racket[larger] are nested, text gets progressively larger.} @defproc[(emph [pre-content pre-content?] ...) element?]{ -The same as @scheme[italic].} +The same as @racket[italic].} @defproc[(linebreak) element?]{ Produces an element that forces a line break.} @defproc[(hspace [n exact-nonnegative-integer?]) element?]{ -Produces an element containing @scheme[n] spaces and style -@scheme['hspace].} +Produces an element containing @racket[n] spaces and style +@racket['hspace].} @defproc[(literal [str string?] ...+) element?]{ -Produces an element containing literally @scheme[str]s with no -decoding via @scheme[decode-content]. +Produces an element containing literally @racket[str]s with no +decoding via @racket[decode-content]. -Beware that @litchar["@"] for a @scheme[literal] call performs some -processing before delivering arguments to @scheme[literal]. The -@scheme[literal] form can be used with @litchar["|{"]...@litchar["}|"] +Beware that @litchar["@"] for a @racket[literal] call performs some +processing before delivering arguments to @racket[literal]. The +@racket[literal] form can be used with @litchar["|{"]...@litchar["}|"] or similar brackets to disable @litchar["@"] notation within the -@scheme[literal] argument, like this: +@racket[literal] argument, like this: @verbatim[#:indent 2]|{ @literal|{@bold{---}}| @@ -305,7 +308,7 @@ which renders as @literal|{@bold{---}}| }| -See also @scheme[verbatim].} +See also @racket[verbatim].} @defproc[(image [path (or/c path-string? (cons/c 'collects (listof bytes?)))] @@ -315,21 +318,21 @@ See also @scheme[verbatim].} element?]{ Creates an image element from the given path. The @tech{decode}d - @scheme[pre-content] serves as the alternate text for contexts where + @racket[pre-content] serves as the alternate text for contexts where the image cannot be displayed. The path is relative to the current directory, which is set by @exec{setup-plt} and @exec{scribble} to the directory of the main - document file. The @scheme[path] argument also can be a result of - @scheme[path->main-collects-relative]. + document file. The @racket[path] argument also can be a result of + @racket[path->main-collects-relative]. - The strings in @scheme[suffixes] are filtered to those supported by + The strings in @racket[suffixes] are filtered to those supported by given renderer, and then the acceptable suffixes are tried in - order. The HTML renderer supports @scheme[".png"] and - @scheme[".gif"], while the Latex renderer supports @scheme[".png"], - @scheme[".pdf"], and @scheme[".ps"] (but @scheme[".ps"] works only - when converting Latex output to DVI, and @scheme[".png"] and - @scheme[".pdf"] work only for converting Latex output to PDF).} + order. The HTML renderer supports @racket[".png"] and + @racket[".gif"], while the Latex renderer supports @racket[".png"], + @racket[".pdf"], and @racket[".ps"] (but @racket[".ps"] works only + when converting Latex output to DVI, and @racket[".png"] and + @racket[".pdf"] work only for converting Latex output to PDF).} @; ------------------------------------------------------------------------ @@ -340,9 +343,9 @@ See also @scheme[verbatim].} [#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")]) element?]{ -The @tech{decode}d @scheme[pre-content] is hyperlinked to -@scheme[url]. If @scheme[style] is not supplied, then -@scheme[underline?] determines how the link is rendered.} +The @tech{decode}d @racket[pre-content] is hyperlinked to +@racket[url]. If @racket[style] is not supplied, then +@racket[underline?] determines how the link is rendered.} @defproc[(url [dest string?]) element?]{ @@ -356,27 +359,27 @@ Generates a literal hyperlinked URL.} [#:underline? underline? any/c #t]) element?]{ -Inserts the hyperlinked title of the section tagged @scheme[tag], but -elements in the title content with the @scheme['aux] @tech{style property} +Inserts the hyperlinked title of the section tagged @racket[tag], but +elements in the title content with the @racket['aux] @tech{style property} are omitted in the hyperlink label. -If @scheme[#:doc module-path] is provided, the @scheme[tag] refers to -a tag with a prefix determined by @scheme[module-path]. When +If @racket[#:doc module-path] is provided, the @racket[tag] refers to +a tag with a prefix determined by @racket[module-path]. When @exec{setup-plt} renders documentation, it automatically adds a tag prefix to the document based on the source module. Thus, for example, -to refer to a section of the PLT Scheme reference, -@scheme[module-path] would be @scheme['(lib +to refer to a section of the Racket reference, +@racket[module-path] would be @racket['(lib "scribblings/reference/reference.scrbl")]. -The @scheme[#:tag-prefixes prefixes] argument similarly supports +The @racket[#:tag-prefixes prefixes] argument similarly supports selecting a particular section as determined by a path of tag -prefixes. When a @scheme[#:doc] argument is provided, then -@scheme[prefixes] should trace a path of tag-prefixed subsections to -reach the @scheme[tag] section. When @scheme[#:doc] is not provided, -the @scheme[prefixes] path is relative to any enclosing section (i.e., +prefixes. When a @racket[#:doc] argument is provided, then +@racket[prefixes] should trace a path of tag-prefixed subsections to +reach the @racket[tag] section. When @racket[#:doc] is not provided, +the @racket[prefixes] path is relative to any enclosing section (i.e., the youngest ancestor that produces a match). -If @scheme[underline?] is @scheme[#f], then the hyperlink is rendered +If @racket[underline?] is @racket[#f], then the hyperlink is rendered in HTML without an underline.} @@ -386,37 +389,37 @@ in HTML without an underline.} [#:underline? underline? any/c #t] [pre-content pre-content?] ...) element?]{ -Like @scheme[secref], but the link label is the @tech{decode}d -@scheme[pre-content] instead of the target section's name.} +Like @racket[secref], but the link label is the @tech{decode}d +@racket[pre-content] instead of the target section's name.} @defproc[(other-doc [module-path module-path?] [#:underline? underline? any/c #t]) element?]{ -Like @scheme[secref] for the document's implicit @scheme["top"] +Like @racket[secref] for the document's implicit @racket["top"] tag. Use this function to refer to a whole manual instead of -@scheme[secref], in case a special style in the future is used for +@racket[secref], in case a special style in the future is used for manual titles.} @defproc[(elemtag [t (or/c tag? string?)] [pre-content pre-content?] ...) element?]{ -The tag @scheme[t] refers to the content form of -@scheme[pre-content].} +The tag @racket[t] refers to the content form of +@racket[pre-content].} @defproc[(elemref [t (or/c tag? string?)] [pre-content pre-content?] ... [#:underline? underline? any/c #t]) element?]{ -The @tech{decode}d @scheme[pre-content] is hyperlinked to @scheme[t], -which is normally defined using @scheme[elemtag].} +The @tech{decode}d @racket[pre-content] is hyperlinked to @racket[t], +which is normally defined using @racket[elemtag].} @defproc[(module-path-prefix->string [mod-path module-path?]) string?]{ Converts a module path to a string by resolving it to a path, and -using @scheme[path->main-collects-relative].} +using @racket[path->main-collects-relative].} @; ------------------------------------------------------------------------ @@ -427,16 +430,16 @@ using @scheme[path->main-collects-relative].} index-element?]{ Creates an index element given a plain-text string---or list of -strings for a hierarchy, such as @scheme['("strings" "plain")] for a +strings for a hierarchy, such as @racket['("strings" "plain")] for a ``plain'' entry below a more general ``strings'' entry. As index keys, -the strings are ``cleaned'' using @scheme[clean-up-index-strings]. The +the strings are ``cleaned'' using @racket[clean-up-index-strings]. The strings (without clean-up) also serve as the text to render in the -index. The @tech{decode}d @scheme[pre-content] is the text to appear +index. The @tech{decode}d @racket[pre-content] is the text to appear inline as the index target. -Use @scheme[index] when an index entry should point to a specific word +Use @racket[index] when an index entry should point to a specific word or phrase within the typeset document (i.e., the -@scheme[pre-content]). Use @scheme[section-index], instead, to create +@racket[pre-content]). Use @racket[section-index], instead, to create an index entry that leads to a section, instead of a specific word or phrase within the section.} @@ -445,23 +448,23 @@ phrase within the section.} [word-contents (listof list?)] [pre-content pre-content?] ...) index-element?]{ -Like @scheme[index], except that @scheme[words] must be a list, and +Like @racket[index], except that @racket[words] must be a list, and the list of contents render in the index (in parallel to -@scheme[words]) is supplied as @scheme[word-contents]. +@racket[words]) is supplied as @racket[word-contents]. } @defproc[(as-index [pre-content pre-content?] ...) index-element?]{ -Like @scheme[index], but the word to index is determined by applying -@scheme[content->string] on the @tech{decode}d @scheme[pre-content].} +Like @racket[index], but the word to index is determined by applying +@racket[content->string] on the @tech{decode}d @racket[pre-content].} @defproc[(section-index [word string?] ...) part-index-decl?]{ -Creates a @scheme[part-index-decl] to be associated with the enclosing -section by @scheme[decode]. The @scheme[word]s serve as both the keys +Creates a @racket[part-index-decl] to be associated with the enclosing +section by @racket[decode]. The @racket[word]s serve as both the keys and as the rendered forms of the keys within the index.} @@ -469,7 +472,7 @@ and as the rendered forms of the keys within the index.} part?]{ Produces a part that shows the index the enclosing document. The -optional @scheme[tag] argument is used as the index section's tag.} +optional @racket[tag] argument is used as the index section's tag.} @; ------------------------------------------------------------------------ @@ -491,10 +494,10 @@ for the enclosing section, depending on the output type. For multi-page HTML output, the flow element is a table of contents; for Latex output, the flow element is empty. -The meaning of the @scheme[style] argument depends on the output type, -but @scheme['immediate-only] normally creates a table of contents that +The meaning of the @racket[style] argument depends on the output type, +but @racket['immediate-only] normally creates a table of contents that contains only immediate sub-sections of the enclosing section. See -also the @scheme['quiet] style of @scheme[part] (i.e., in a -@scheme[part] structure, not supplied as the @scheme[style] argument -to @scheme[local-table-of-contents]), which normally suppresses +also the @racket['quiet] style of @racket[part] (i.e., in a +@racket[part] structure, not supplied as the @racket[style] argument +to @racket[local-table-of-contents]), which normally suppresses sub-part entries in a table of contents.} diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index 8eebd3de..2b94d9f6 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -7,15 +7,15 @@ @title[#:tag "basic"]{Compatibility Basic Functions} -@defmodule[scribble/basic]{The @schememodname[scribble/basic] +@defmodule[scribble/basic]{The @racketmodname[scribble/basic] compatibility library mostly just re-exports -@schememodname[scribble/base].} +@racketmodname[scribble/base].} @defproc[(span-class [style-name string?] [pre-content any/c] ...) element?]{ @compat[] Wraps the @tech{decode}d -@scheme[pre-content] as an element with style @scheme[style-name].} +@racket[pre-content] as an element with style @racket[style-name].} @@ -23,5 +23,5 @@ compatibility library mostly just re-exports [#:style style (or/c style? string? symbol? #f) #f]) itemization?]{ -@compat[] Like @scheme[itemlist], but whitespace strings among the -@scheme[itm]s are ignored.} +@compat[] Like @racket[itemlist], but whitespace strings among the +@racket[itm]s are ignored.} diff --git a/collects/scribblings/scribble/bnf.scrbl b/collects/scribblings/scribble/bnf.scrbl index a8dc78af..46509979 100644 --- a/collects/scribblings/scribble/bnf.scrbl +++ b/collects/scribblings/scribble/bnf.scrbl @@ -5,17 +5,17 @@ @title[#:tag "bnf"]{BNF Grammars} -@defmodule[scribble/bnf]{The @scheme[scribble/bnf] library +@defmodule[scribble/bnf]{The @racket[scribble/bnf] library provides utilities for typesetting grammars.} -See also @scheme[schemegrammar]. +See also @racket[racketgrammar]. @defproc[(BNF [prod (cons element? (listof element?))] ...) table?]{ Typesets a grammar table. Each production starts with an element -(typically constructed with @scheme[nonterm]) for the non-terminal +(typically constructed with @racket[nonterm]) for the non-terminal being defined, and then a list of possibilities (typically constructed -with @scheme[BNF-seq], etc.) to show on separate lines.} +with @racket[BNF-seq], etc.) to show on separate lines.} @defproc[(nonterm (pre-content any/c) ...) element?]{ @@ -44,15 +44,15 @@ Typesets a 1-or-more repetition.} @defproc[(kleenerange [n any/c] [m any/c] [pre-content any/c] ...) element?]{ -Typesets a @scheme[n]-to-@scheme[m] repetition. The @scheme[n] and -@scheme[m] arguments are converted to a string using @scheme[(format -"~a" n)] and @scheme[(format "~a" m)].} +Typesets a @racket[n]-to-@racket[m] repetition. The @racket[n] and +@racket[m] arguments are converted to a string using @racket[(format +"~a" n)] and @racket[(format "~a" m)].} @defproc[(BNF-alt [elem element?] ...) element?]{ Typesets alternatives for a production's right-hand side to appear on a single line. The result is normally used as a single possibility in -a production list for @scheme[BNF].} +a production list for @racket[BNF].} @defthing[BNF-etc string?]{ diff --git a/collects/scribblings/scribble/config.scrbl b/collects/scribblings/scribble/config.scrbl index e7c7c229..fd94a427 100644 --- a/collects/scribblings/scribble/config.scrbl +++ b/collects/scribblings/scribble/config.scrbl @@ -5,7 +5,7 @@ scribble/html-properties scribble/latex-properties "utils.ss" - (for-label scheme/base)) + (for-label racket/base)) @(define (fake-title . str) (apply bold str)) @@ -20,16 +20,16 @@ extend or configure Scribble fall into two groups: @item{You may need to drop into the back-end ``language'' of CSS or Latex to create a specific output effect. For this kind of extension, you will mostly likely attach a - @scheme[css-addition] or @scheme[tex-addition] @tech{style property} + @racket[css-addition] or @racket[tex-addition] @tech{style property} to style, where the addition implements the style name. 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 + different from the Racket documentation style. For that kind of configuration, you can run the @exec{scribble} command-line tool and supply flags like @DFlag{prefix} or @DPFlag{style}, or - you can associate a @scheme[html-defaults] or - @scheme[latex-defaults] @tech{style property} to the main document's + you can associate a @racket[html-defaults] or + @racket[latex-defaults] @tech{style property} to the main document's style. This kind of configuration is described in @secref["config-style"].} @@ -42,46 +42,46 @@ extend or configure Scribble fall into two groups: (make-tex-addition "inbox.tex"))) ]{Implementing Styles} -When a string is uses as a style in an @scheme[element], -a @scheme[multiarg-element], @scheme[paragraph], @scheme[table], -@scheme[itemization], @scheme[nested-flow], or -@scheme[compound-paragraph], it corresponds to a CSS class for HTML +When a string is uses as a style in an @racket[element], +a @racket[multiarg-element], @racket[paragraph], @racket[table], +@racket[itemization], @racket[nested-flow], or +@racket[compound-paragraph], it corresponds to a CSS class for HTML output or a Latex macro/environment for Latex output. In Latex output, -the string is used as a command name for a @scheme[paragraph] -and an environment name for a @scheme[table], @scheme[itemization], -@scheme[nested-flow], or @scheme[compound-paragraph]; the if style has -a @scheme['command] @tech{style property} for a @scheme[nested-flow] or -@scheme[compound-paragraph], then the style name is used as a command +the string is used as a command name for a @racket[paragraph] +and an environment name for a @racket[table], @racket[itemization], +@racket[nested-flow], or @racket[compound-paragraph]; the if style has +a @racket['command] @tech{style property} for a @racket[nested-flow] or +@racket[compound-paragraph], then the style name is used as a command instead of an environment. In addition, for an itemization, the style -string is suffixed with @scheme["Item"] and used as a CSS class or Latex +string is suffixed with @racket["Item"] and used as a CSS class or Latex macro name to use for the itemization's items (in place of @tt{item} in the case of Latex). To add a mapping from your own style name to a CSS configuration, add -a @scheme[css-addition] structure instance to a style's @tech{style property} +a @racket[css-addition] structure instance to a style's @tech{style property} list. To map a style name to a Latex macro or environment, add a -@scheme[tex-addition] structure instance. A @scheme[css-addition] or -@scheme[tex-addition] is normally associated with the style whose name +@racket[tex-addition] structure instance. A @racket[css-addition] or +@racket[tex-addition] is normally associated with the style whose name is implemented by the adition, but it can also be added to the style for an enclosing part. Scribble includes a number of predefined styles that are used by the -exports of @scheme[scribble/base]. You can use them or redefine +exports of @racket[scribble/base]. You can use them or redefine them. The styles are specified by @filepath{scribble.css} and @filepath{scribble.tex} in the @filepath{scribble} collection. -The styles used by @schememodname[scribble/manual] are implemented by -@filepath{scheme.css} and @filepath{scheme.tex} in the +The styles used by @racketmodname[scribble/manual] are implemented by +@filepath{racket.css} and @filepath{racket.tex} in the @filepath{scribble} collection. Other libraries, such as -@schememodname[scriblib/autobib], similarly implement styles through files -that are associated by @scheme[css-addition] and @scheme[tex-addition] +@racketmodname[scriblib/autobib], similarly implement styles through files +that are associated by @racket[css-addition] and @racket[tex-addition] @tech{style properties}. 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 @schememodname[scribble/base] and -@schememodname[scribble/manual] will start with @litchar{S}. +Latex packages, and future styles needed by @racketmodname[scribble/base] and +@racketmodname[scribble/manual] will start with @litchar{S}. For example, a Scribble document @@ -136,9 +136,9 @@ set of page-layout and font properties that are used by other commands. The style-replacement kind of configuration corresponds to re-defining Latex macros or overriding CSS class attributes. When @exec{setup-plt} builds PDF documentation, it uses both kinds of -configuration to produce a standard layout for PLT Scheme manuals; +configuration to produce a standard layout for Racket manuals; that is, it selects a particular page layout, and it replaces some -@schememodname[scheme/base] styles. +@racketmodname[racket/base] styles. Two kinds of files implement the two kinds of configuration: @@ -155,7 +155,7 @@ Two kinds of files implement the two kinds of configuration: @item{A @deftech{style file} refines the implementation of styles nused in the document---typically just the ``built-in'' styles - used by @schememodname[scribble/base]. + used by @racketmodname[scribble/base]. The default style files, @filepath{scribble-style.css} and @filepath{scribble-style.tex} in the @filepath{scribble} @@ -185,30 +185,30 @@ accompanying files: flag. Add additional style definitions and re-definitions using the @as-index{@DPFlag{style}} flag.} - @item{Add additional accompanying files with @as-index{@DFlag{extra}}.} + @item{Add additional accompanying files with @as-index{@DPFlag{extra}}.} ] When using the @exec{scribble} command-line utility, a document can declare its default style, prefix, and extra files through a -@scheme[html-defaults] and/or @scheme[latex-defaults] +@racket[html-defaults] and/or @racket[latex-defaults] @tech{style property}. In particular, when using the @exec{scribble} command-line tool to generate Latex or PDF a document whose main part -is implemented with @scheme[#, @hash-lang[] #, -@schememodname[scribble/manual]], the result has the standard PLT -Scheme manual configuration, because @schememodname[scribble/manual] -associates a @scheme[latex-defaults] @tech{style property} with the exported -document. The @schememodname[scribble/sigplan] language similarly +is implemented with @racket[#, @hash-lang[] #, +@racketmodname[scribble/manual]], the result has the standard +Racket manual configuration, because @racketmodname[scribble/manual] +associates a @racket[latex-defaults] @tech{style property} with the exported +document. The @racketmodname[scribble/sigplan] language similarly associates a default configuration with an exported document. As -libraries imported with @scheme[require], however, -@schememodname[scribble/manual] and @schememodname[scribble/sigplan] +libraries imported with @racket[require], however, +@racketmodname[scribble/manual] and @racketmodname[scribble/sigplan] simply implement new styles in a composable way. Whether or not a document has a default prefix- and style-file configuration through a @tech{style property}, the defaults can be overridden using @exec{scribble} command-line flags. Furthermore, -languages like @schememodname[scribble/manual] and -@schememodname[scribble/sigplan] add a @scheme[html-defaults] and/or -@scheme[latex-defaults] @tech{style property} to a main-document part only if +languages like @racketmodname[scribble/manual] and +@racketmodname[scribble/sigplan] add a @racket[html-defaults] and/or +@racket[latex-defaults] @tech{style property} to a main-document part only if it does not already have such a property added through the -@scheme[#:style] argument of @scheme[title]. +@racket[#:style] argument of @racket[title]. diff --git a/collects/scribblings/scribble/core.scrbl b/collects/scribblings/scribble/core.scrbl index a1e34162..321e14a7 100644 --- a/collects/scribblings/scribble/core.scrbl +++ b/collects/scribblings/scribble/core.scrbl @@ -22,17 +22,17 @@ A document is processed in three passes. The first pass is the contribute new hyperlink targets). The final pass is the @deftech{render pass}, which generates the resulting document. None of the passes mutate the document, but instead collect information in - side @scheme[collect-info] and @scheme[resolve-info] tables. + side @racket[collect-info] and @racket[resolve-info] tables. @; ------------------------------------------------------------------------ @section[#:tag "parts"]{Parts} -A @deftech{part} is an instance of @scheme[part]; among other things, +A @deftech{part} is an instance of @racket[part]; among other things, it has a title @techlink{content}, an initial @techlink{flow}, and a list of subsection @techlink{parts}. There is no difference between a part and a full document; a particular source module just as easily - defines a subsection (incorporated via @scheme[include-section]) as a + defines a subsection (incorporated via @racket[include-section]) as a document. A @deftech{flow} is a list of @techlink{blocks}. @@ -43,25 +43,25 @@ A @deftech{block} is either a @techlink{table}, an @itemize[ - @item{A @deftech{table} is an instance of @scheme[table]; it + @item{A @deftech{table} is an instance of @racket[table]; it has a list of list of @techlink{blocks} corresponding to table cells.} - @item{A @deftech{itemization} is an instance of @scheme[itemization]; + @item{A @deftech{itemization} is an instance of @racket[itemization]; it has a list of @techlink{flows}.} @item{A @deftech{nested flow} is an instance of - @scheme[nested-flow]; it has a @tech{flow} that + @racket[nested-flow]; it has a @tech{flow} that is typeset as sub-flow.} @item{A @deftech{paragraph} is an instance of - @scheme[paragraph]; it has a @tech{content}: + @racket[paragraph]; it has a @tech{content}: @itemize[ @item{An @deftech{content} can be a string, one of a few - symbols, an instance of @scheme[element] (possibly - @scheme[link-element], etc.), a @scheme[multiarg-element], a + symbols, an instance of @racket[element] (possibly + @racket[link-element], etc.), a @racket[multiarg-element], a @techlink{part-relative element}, a @techlink{delayed element}, or a list of content. @@ -70,62 +70,62 @@ A @deftech{block} is either a @techlink{table}, an @item{A string is included in the result document verbatim, except for space, and unless the content's enclosing @tech{style} is - @scheme['hspace]. In a style other than - @scheme['hspace], consecutive spaces in the + @racket['hspace]. In a style other than + @racket['hspace], consecutive spaces in the output may be collapsed togther or replaced with a line break. In the style - @scheme['hspace], all text is converted to + @racket['hspace], all text is converted to uncollapsable spaces that cannot be broken across lines.} - @item{A symbol content is either @scheme['mdash], - @scheme['ndash], @scheme['ldquo], - @scheme['lsquo], @scheme['rsquo], @scheme['larr], - @scheme['rarr], or @scheme['prime]; it is + @item{A symbol content is either @racket['mdash], + @racket['ndash], @racket['ldquo], + @racket['lsquo], @racket['rsquo], @racket['larr], + @racket['rarr], or @racket['prime]; it is rendered as the corresponding HTML entity (even for Latex output).} - @item{An instance of @scheme[element] has a + @item{An instance of @racket[element] has a @techlink{content} plus a @tech{style}. The style's interpretation depends on the renderer, but it can be one of a few special symbols (such as - @scheme['bold]) that are recognized by all + @racket['bold]) that are recognized by all renderers.} - @item{An instance of @scheme[link-element] has a + @item{An instance of @racket[link-element] has a @techlink{tag} for the target of the link.} - @item{An instance of @scheme[target-element] has a + @item{An instance of @racket[target-element] has a @techlink{tag} to be referenced by - @scheme[link-element]s. An instance of the - subtype @scheme[toc-target-element] is + @racket[link-element]s. An instance of the + subtype @racket[toc-target-element] is treated like a kind of section label, to be shown in the ``on this page'' table for HTML output.} - @item{An instance of @scheme[index-element] has a + @item{An instance of @racket[index-element] has a @techlink{tag} (as a target), a list of strings for the keywords (for sorting and search), and a list of @techlink{contents} to appear in the end-of-document index.} - @item{An instance of @scheme[image-element] + @item{An instance of @racket[image-element] incorporates an image from a file into the rendered document.} - @item{An instance of @scheme[multiarg-element] + @item{An instance of @racket[multiarg-element] combines a style with a list of content, where the style corresponds to a rendered command that takes multiple arguments.} - @item{An instance of @scheme[collect-element] has a + @item{An instance of @racket[collect-element] has a procedure that is called in the @techlink{collect pass} of document processing to record information used by later passes.} @item{A @deftech{part-relative element} is an - instance of @scheme[part-relative-element], + instance of @racket[part-relative-element], which has a procedure that is called in the @techlink{collect pass} of document processing to obtain @defterm{content}. When the @@ -135,12 +135,12 @@ A @deftech{block} is either a @techlink{table}, an available.} @item{A @deftech{delayed element} is an instance of - @scheme[delayed-element], which has a + @racket[delayed-element], which has a procedure that is called in the @techlink{resolve pass} of document processing to obtain @defterm{content}.} - @item{An instance of @scheme[render-element] has a + @item{An instance of @racket[render-element] has a procedure that is called in the @techlink{render pass} of document processing.} @@ -148,13 +148,13 @@ A @deftech{block} is either a @techlink{table}, an ]}]} @item{A @deftech{compound paragraph} is an instance of - @scheme[compound-paragraph]; like @scheme[blockquote], it + @racket[compound-paragraph]; like @racket[blockquote], it has list of @tech{blocks}, but the blocks are typeset as a single paragraph (e.g., no indentation after the first block) instead of inset.} @item{A @deftech{delayed block} is an instance of - @scheme[delayed-block], which has a procedure that + @racket[delayed-block], which has a procedure that is called in the @techlink{resolve pass} of document processing to obtain a @defterm{block}.} @@ -165,20 +165,20 @@ A @deftech{block} is either a @techlink{table}, an @section[#:tag "tags"]{Tags} A @deftech{tag} is a list containing a symbol and either a string, a -@scheme[generated-tag] instance, or an arbitrary list. The symbol -effectively identifies the type of the tag, such as @scheme['part] for -a tag that links to a part, or @scheme['def] for a Scheme function +@racket[generated-tag] instance, or an arbitrary list. The symbol +effectively identifies the type of the tag, such as @racket['part] for +a tag that links to a part, or @racket['def] for a Racket function definition. The symbol also effectively determines the interpretation of the second half of the tag. A part can have a @deftech{tag prefix}, which is effectively added onto the second item within each tag whose first item is -@scheme['part] or @scheme['tech]. The prefix is added to a string +@racket['part] or @racket['tech]. The prefix is added to a string value by creating a list containing the prefix and string, and it is -added to a list value using @scheme[cons]; a prefix is not added to a -@scheme[generated-tag] instance. The prefix is used for reference +added to a list value using @racket[cons]; a prefix is not added to a +@racket[generated-tag] instance. The prefix is used for reference outside the part, including the use of tags in the part's -@scheme[tags] field. Typically, a document's main part has a tag +@racket[tags] field. Typically, a document's main part has a tag prefix that applies to the whole document; references to sections and defined terms within the document from other documents must include the prefix, while references within the same document omit the prefix. Part @@ -187,18 +187,18 @@ references within the document. Some procedures accept a ``tag'' that is just the string part of the full tag, where the symbol part is supplied automatically. For -example, @scheme[section] and @scheme[secref] both accept a string -``tag'', where @scheme['part] is implicit. +example, @racket[section] and @racket[secref] both accept a string +``tag'', where @racket['part] is implicit. @; ------------------------------------------------------------------------ @section[#:tag "style"]{Styles} A @deftech{style} combines a @tech{style name} with a list of -@tech{style properties} in a @scheme[style] structure. A @deftech{style name} -is either a string, symbol, of @scheme[#f]. A @deftech{style property} can be +@tech{style properties} in a @racket[style] structure. A @deftech{style name} +is either a string, symbol, of @racket[#f]. A @deftech{style property} can be anything, including a symbol a structure such as -@scheme[color-property]. +@racket[color-property]. A style has a single @tech{style name}, because the name typically corresponds to a configurable instruction to a renderer. For example, @@ -207,14 +207,14 @@ or environment. For more information on how string style names interact with configuration of a renderer, see @secref["config"]. Symbolic style names, meanwhile, provide a simple layer of abstraction between the renderer and documents for widely -supported style; for example, the @scheme['italic] style name is +supported style; for example, the @racket['italic] style name is supported by all renderers. @tech{Style properties} within a style compose with style names and other properties. Again, symbols are often used for properties that are directly -supported by renderers. For example, @scheme['unnumbered] style +supported by renderers. For example, @racket['unnumbered] style property for a @tech{part} renders the part without a section number. -Many properties are renderer-specific, such as a @scheme[hover-property] +Many properties are renderer-specific, such as a @racket[hover-property] structure that associates text with an element to be shown in an HTML display when the mouse hovers over the text. @@ -225,35 +225,35 @@ HTML display when the mouse hovers over the text. The @techlink{collect pass}, @techlink{resolve pass}, and @techlink{render pass} processing steps all produce information that is specific to a rendering mode. Concretely, the operations are all -represented as methods on a @scheme[render%] object. +represented as methods on a @racket[render%] object. The result of the @method[render% collect] method is a -@scheme[collect-info] instance. This result is provided back as an +@racket[collect-info] instance. This result is provided back as an argument to the @method[render% resolve] method, which produces a -@scheme[resolve-info] value that encapsulates the results from both -iterations. The @scheme[resolve-info] value is provided back to the +@racket[resolve-info] value that encapsulates the results from both +iterations. The @racket[resolve-info] value is provided back to the @method[render% resolve] method for final rendering. Optionally, before the @method[render% resolve] method is called, serialized information from other documents can be folded into the -@scheme[collect-info] instance via the @method[render% +@racket[collect-info] instance via the @method[render% deserialize-info] method. Other methods provide serialized information out of the collected and resolved records. During the @techlink{collect pass}, the procedure associated with a -@scheme[collect-element] instance can register information with -@scheme[collect-put!]. +@racket[collect-element] instance can register information with +@racket[collect-put!]. During the @techlink{resolve pass}, collected information for a part -can be extracted with @scheme[part-collected-info], which includes a -part's number and its parent part (or @scheme[#f]). More generally, -the @scheme[resolve-get] method looks up information previously +can be extracted with @racket[part-collected-info], which includes a +part's number and its parent part (or @racket[#f]). More generally, +the @racket[resolve-get] method looks up information previously collected. This resolve-time information is normally obtained by the procedure associated with a @techlink{delayed block} or @techlink{delayed element}. -The @scheme[resolve-get] information accepts both a @scheme[part] and -a @scheme[resolve-info] argument. The @scheme[part] argument enables +The @racket[resolve-get] information accepts both a @racket[part] and +a @racket[resolve-info] argument. The @racket[part] argument enables searching for information in each enclosing part before sibling parts. @; ------------------------------------------------------------------------ @@ -268,20 +268,20 @@ searching for information in each enclosing part before sibling parts. [blocks (listof block?)] [parts (listof part?)])]{ -The @scheme[tag-prefix] field determines the optional @techlink{tag +The @racket[tag-prefix] field determines the optional @techlink{tag prefix} for the part. -The @scheme[tags] indicates a list of @techlink{tags} that each link +The @racket[tags] indicates a list of @techlink{tags} that each link to the section. -The @scheme[title-content] field holds the part's title, if any. +The @racket[title-content] field holds the part's title, if any. -For the @scheme[style] field, the currently recognized symbolic style +For the @racket[style] field, the currently recognized symbolic style names are as follows: @itemize[ - @item{@scheme['index] --- The part represents an index.} + @item{@racket['index] --- The part represents an index.} ] @@ -289,63 +289,63 @@ The recognized @tech{style properties} are as follows: @itemize[ - @item{@scheme['unnumbered] --- A section number is computed for an + @item{@racket['unnumbered] --- A section number is computed for an unnumbered section during the @techlink{collect pass}, but the number is not rendered.} - @item{@scheme['toc] --- Sub-parts of the part are rendered on separate + @item{@racket['toc] --- Sub-parts of the part are rendered on separate pages for multi-page HTML mode.} - @item{@scheme['non-toc] --- Initial sub-parts of the part are + @item{@racket['non-toc] --- Initial sub-parts of the part are @emph{not} rendered on separate pages for multi-page HTML mode; this style applies only to the main part.} - @item{@scheme['reveal] --- Shows sub-parts when this part is + @item{@racket['reveal] --- Shows sub-parts when this part is displayed in a table-of-contents panel in HTML output (which normally shows only the top-level sections).} - @item{@scheme['hidden] --- The part title is not shown in rendered + @item{@racket['hidden] --- The part title is not shown in rendered HTML output.} - @item{@scheme['quiet] --- In HTML output and most other output modes, + @item{@racket['quiet] --- In HTML output and most other output modes, hides entries for sub-parts of this part in a - @scheme[table-of-contents] or @scheme[local-table-of-contents] + @racket[table-of-contents] or @racket[local-table-of-contents] listing except when those sub-parts are top-level entries in the listing.} - @item{@scheme['no-toc] --- As a style for the main part of a + @item{@racket['no-toc] --- As a style for the main part of a document, causes the HTML output to not include a margin box for the main table of contents; the ``on this page'' box that - contains @scheme[toc-element] and @scheme[toc-target-element] + contains @racket[toc-element] and @racket[toc-target-element] links (and that only includes an ``on this page'' label for multi-page documents) takes on the location and color of the main table of contents, instead.} - @item{@scheme[document-version] structure --- A version number for + @item{@racket[document-version] structure --- A version number for this part and its sub-parts (except as overridden). When it is - not @scheme[""] may be used when rendering a document; at a - minimum, a non-@scheme[""] version is rendered when it is + 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 @scheme[(version)].} + version for a document is @racket[(version)].} - @item{@scheme[body-id] structure --- Generated HTML uses the given + @item{@racket[body-id] structure --- Generated HTML uses the given string @tt{id} attribute of the @tt{body} tag; this style can be set separately for parts that start different HTML pages, otherwise it is effectively inherited by sub-parts; the - default is @scheme["scribble-plt-scheme.org"], but - @exec{setup-plt} installs @scheme["doc-plt-scheme.org"] as the + default is @racket["scribble-plt-scheme.org"], but + @exec{setup-plt} installs @racket["doc-plt-scheme.org"] as the @tt{id} for any document that it builds.} ] -The @scheme[to-collect] field contains @techlink{content} that is +The @racket[to-collect] field contains @techlink{content} that is inspected during the @techlink{collect pass}, but ignored in later passes (i.e., it doesn't directly contribute to the output). -The @scheme[blocks] field contains the part's initial flow (before +The @racket[blocks] field contains the part's initial flow (before sub-parts). -The @scheme[parts] field contains sub-parts. +The @racket[parts] field contains sub-parts. } @@ -354,16 +354,16 @@ The @scheme[parts] field contains sub-parts. A @techlink{paragraph} has a @tech{style} and a @tech{content}. -For the @scheme[style] field, a string @tech{style name} corresponds +For the @racket[style] field, a string @tech{style name} corresponds to a CSS class for HTML output or a macro for Latex output (see @secref["extra-style"]). The following symbolic @tech{style names} are recognized: @itemize[ - @item{@scheme['author] --- Typeset as the author of a document. Such + @item{@racket['author] --- Typeset as the author of a document. Such paragraphs normally should appear only in the initial flow of a - @scheme[part] for a document, where they are treated specially + @racket[part] for a document, where they are treated specially by the Latex renderer by moving the author information to the title.} @@ -373,21 +373,21 @@ The currently recognized @tech{style properties} are as follows: @itemize[ - @item{@scheme['omitable] --- When a table cell contains a single - @scheme[omitable-paragraph], then when rendering to HTML, no + @item{@racket['omitable] --- When a table cell contains a single + @racket[omitable-paragraph], then when rendering to HTML, no @tt{p} tag wraps the cell content.} - @item{@scheme['div] --- Generates @tt{
} HTML output instead of + @item{@racket['div] --- Generates @tt{
} HTML output instead of @tt{

}.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{

} or @tt{

} tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{

} or @tt{

} tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -396,20 +396,20 @@ The currently recognized @tech{style properties} are as follows: [blockss (listof (listof (or/c block? (one-of/c 'cont))))])]{ A @techlink{table} has, roughly, a list of list of blocks. A cell in -the table can span multiple columns by using @scheme['cont] instead of +the table can span multiple columns by using @racket['cont] instead of a block in the following columns (i.e., for all but the first in a set of cells that contain a single block). -Within @scheme[style], a string @tech{style name} corresponds to a CSS +Within @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output or an environment for Latex output (see @secref["extra-style"]). The following symbolic style names are also recognized: @itemize[ - @item{@scheme['boxed] --- Renders as a definition.} + @item{@racket['boxed] --- Renders as a definition.} - @item{@scheme['centered] --- Centers HTML output horizontally.} + @item{@racket['centered] --- Centers HTML output horizontally.} ] @@ -417,36 +417,36 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[table-columns] structure --- Provides column-specific - styles, but only if a @scheme[table-cells] structure is not + @item{@racket[table-columns] structure --- Provides column-specific + styles, but only if a @racket[table-cells] structure is not included as a @tech{style property}.} - @item{@scheme[table-cells] structure --- Provides cell-specific + @item{@racket[table-cells] structure --- Provides cell-specific styles.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{} tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
} tag.} - @item{@scheme['aux] --- For HTML, include the table in the + @item{@racket['aux] --- For HTML, include the table in the table-of-contents display for the enclosing part.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ] For Latex output, a paragraph as a cell value is not automatically line-wrapped, unless a vertical alignment is specified for the cell -through a @scheme[table-cells] or @scheme[table-columns] +through a @racket[table-cells] or @racket[table-columns] @tech{style property}. To get a line-wrapped paragraph, use a -@scheme[compound-paragraph] or use an element with a string style and +@racket[compound-paragraph] or use an element with a string style and define a corresponding Latex macro in terms of @tt{parbox}. For Latex -output of blocks in the flow that are @scheme[nested-flow]s, -@scheme[itemization]s, @scheme[compound-paragraph]s, or -@scheme[delayed-block]s, the block is wrapped with @tt{minipage} using +output of blocks in the flow that are @racket[nested-flow]s, +@racket[itemization]s, @racket[compound-paragraph]s, or +@racket[delayed-block]s, the block is wrapped with @tt{minipage} using @tt{linewidth} divided by the column count as the width.} @@ -455,16 +455,16 @@ output of blocks in the flow that are @scheme[nested-flow]s, A @techlink{itemization} has a @tech{style} and a list of @tech{flows}. -In @scheme[style], a string @tech{style name} corresponds to a CSS +In @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output or a macro for Latex output (see @secref["extra-style"]). In addition, the following symbolic style names are recognized: @itemize[ - @item{@scheme['compact] --- Reduces space between items.} + @item{@racket['compact] --- Reduces space between items.} - @item{@scheme['ordered] --- Generates @tt{
    } HTML output instead + @item{@racket['ordered] --- Generates @tt{
      } HTML output instead of @tt{
        } or an Latex enumeration instead of an itemization.} ] @@ -473,14 +473,14 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{
          } or @tt{
            } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
              } or @tt{
                } tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -490,14 +490,14 @@ The following @tech{style properties} are currently recognized: A @techlink{nested flow} has a style and a @tech{flow}. -In @scheme[style], the @scheme{style name} is normally a string that +In @racket[style], the @racket{style name} is normally a string that corresponds to a CSS class for HTML @tt{blockquote} output or a Latex environment (see @secref["extra-style"]). The following symbolic style names are recognized: @itemize[ - @item{@scheme['inset] --- Insets the nested flow relative to + @item{@racket['inset] --- Insets the nested flow relative to surrounding text.} ] @@ -506,18 +506,18 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme['command] --- For Latex output, a string @tech{style + @item{@racket['command] --- For Latex output, a string @tech{style name} is used as a command name instead of an environment name.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{
                } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{
                } tag.} - @item{@scheme['never-indents] --- For Latex and @tech{compound - paragraphs}; see @scheme[compound-paragraph].} + @item{@racket['never-indents] --- For Latex and @tech{compound + paragraphs}; see @racket[compound-paragraph].} ]} @@ -528,33 +528,33 @@ The following @tech{style properties} are currently recognized: A @techlink{compound paragraph} has a @tech{style} and a list of @tech{blocks}. -For HTML, a @scheme[paragraph] block in @scheme[blocks] is rendered +For HTML, a @racket[paragraph] block in @racket[blocks] is rendered without a @tt{

                } tag, unless the paragraph has a style with a -non-@scheme[#f] @tech{style name}. For Latex, each @tech{block} in -@scheme[blocks] is rendered with a preceding @tt{\noindent}, unless -the block has the @scheme['never-indents] property (checking -recursively in a @scheme[nested-flow] or @scheme[compound-paragraph] -if the @scheme[nested-flow] or @scheme[compound-paragraph] itself has -no @scheme['never-indents] property). +non-@racket[#f] @tech{style name}. For Latex, each @tech{block} in +@racket[blocks] is rendered with a preceding @tt{\noindent}, unless +the block has the @racket['never-indents] property (checking +recursively in a @racket[nested-flow] or @racket[compound-paragraph] +if the @racket[nested-flow] or @racket[compound-paragraph] itself has +no @racket['never-indents] property). -The @scheme[style] field of a compound paragraph is normally a string +The @racket[style] field of a compound paragraph is normally a string that corresponds to a CSS class for HTML output or Latex environment for Latex output (see @secref["extra-style"]). The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme['command] --- For Latex output, a string @tech{style + @item{@racket['command] --- For Latex output, a string @tech{style name} is used as a command name instead of an environment name.} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for the @tt{

                } tag.} - @item{@scheme[body-id] structure --- For HTML, uses the given string + @item{@racket[body-id] structure --- For HTML, uses the given string as an @tt{id} attribute of the @tt{

                } tag.} - @item{@scheme['never-indents] --- For Latex within another + @item{@racket['never-indents] --- For Latex within another @tech{compound paragraph}; see above.} ]} @@ -562,9 +562,9 @@ for Latex output (see @secref["extra-style"]). The following @defstruct[delayed-block ([resolve (any/c part? resolve-info? . -> . block?)])]{ -The @scheme[resolve] procedure is called during the @techlink{resolve +The @racket[resolve] procedure is called during the @techlink{resolve pass} to obtain a normal @tech{block}. The first argument to -@scheme[resolve] is the renderer. +@racket[resolve] is the renderer. } @@ -574,26 +574,26 @@ pass} to obtain a normal @tech{block}. The first argument to Styled @tech{content} within an enclosing @tech{paragraph} or other content. -The @scheme[style] field can be a @scheme[style] structure, but it can +The @racket[style] field can be a @racket[style] structure, but it can also be just a @tech{style name}. -In @scheme[style], a string @tech{style name} corresponds to a CSS +In @racket[style], a string @tech{style name} corresponds to a CSS class for HTML output and a macro name for Latex output (see @secref["extra-style"]). The following symbolic style names are recognized: @itemize[ - @item{@scheme['tt], @scheme['italic], @scheme['bold], @scheme['sf], - @scheme['url], @scheme['subscript], @scheme['superscript], - @scheme['smaller], @scheme['larger] --- + @item{@racket['tt], @racket['italic], @racket['bold], @racket['sf], + @racket['url], @racket['subscript], @racket['superscript], + @racket['smaller], @racket['larger] --- Basic styles recognized by all renders.} - @item{@scheme['hspace] --- Renders its @scheme[content] as monospace + @item{@racket['hspace] --- Renders its @racket[content] as monospace blanks.} - @item{@scheme['newline] --- Renders a line break independent of - the @scheme[content].} + @item{@racket['newline] --- Renders a line break independent of + the @racket[content].} ] @@ -601,39 +601,39 @@ The following @tech{style properties} are currently recognized: @itemize[ - @item{@scheme[target-url] structure --- Generates a hyperlink.} + @item{@racket[target-url] structure --- Generates a hyperlink.} - @item{@scheme[url-anchor] structure --- For HTML, inserts a hyperlink - target before @scheme[content].} + @item{@racket[url-anchor] structure --- For HTML, inserts a hyperlink + target before @racket[content].} - @item{@scheme[color-property] structure --- Applies a color to the - text of @scheme[content].} + @item{@racket[color-property] structure --- Applies a color to the + text of @racket[content].} - @item{@scheme[background-color-property] structure --- Applies a color to the - background of @scheme[content].} + @item{@racket[background-color-property] structure --- Applies a color to the + background of @racket[content].} - @item{@scheme[attributes] structure --- Provides additional HTML + @item{@racket[attributes] structure --- Provides additional HTML attributes for a @tt{} tag.} - @item{@scheme[hover-property] structure --- For HTML, adds a text + @item{@racket[hover-property] structure --- For HTML, adds a text label to the content to be shown when the mouse hovers over it.} - @item{@scheme[script-property] structure --- For HTML, supplies a - script alternative to @scheme[content].} + @item{@racket[script-property] structure --- For HTML, supplies a + script alternative to @racket[content].} - @item{@scheme[body-id] structure --- For HTML uses the given + @item{@racket[body-id] structure --- For HTML uses the given string as an @tt{id} attribute of the @tt{span} tag.} - @item{@scheme['aux] --- Intended for use in titles, where the + @item{@racket['aux] --- Intended for use in titles, where the auxiliary part of the title can be omitted in hyperlinks. See, - for example, @scheme[secref].} + for example, @racket[secref].} - @item{@scheme['tt-chars] --- For Latex output, when the @tech{style + @item{@racket['tt-chars] --- For Latex output, when the @tech{style name} is a string, render the element's content with escapes suitable for Latex @tt{tt} mode.} - @item{@scheme['exact-chars] --- For Latex output, when the @tech{style + @item{@racket['exact-chars] --- For Latex output, when the @tech{style name} is a string, render the elements content exactly (without escapes).} @@ -645,65 +645,65 @@ The following @tech{style properties} are currently recognized: [suffixes (listof #rx"^[.]")] [scale real?])]{ -Used as a style for an @scheme[element] to inline an image. The -@scheme[path] field can be a result of -@scheme[path->main-collects-relative]. +Used as a style for an @racket[element] to inline an image. The +@racket[path] field can be a result of +@racket[path->main-collects-relative]. -For each string in @scheme[suffixes], if the rendered works with the -corresponding suffix, the suffix is added to @scheme[path] and used if +For each string in @racket[suffixes], if the rendered works with the +corresponding suffix, the suffix is added to @racket[path] and used if the resulting path refers to a file that exists. The order in -@scheme[suffixes] determines the order in which suffixes are -tried. The HTML renderer supports @scheme[".png"] and @scheme[".gif"], -while the Latex renderer supports @scheme[".png"], @scheme[".pdf"], -and @scheme[".ps"] (but rendering Latex output to PDF will not work -with @scheme[".ps"] files, while rendering to Latex DVI output works -only with @scheme[".ps"] files). If @scheme[suffixes] is empty or if -none of the suffixes lead to files that exist, @scheme[path] is used +@racket[suffixes] determines the order in which suffixes are +tried. The HTML renderer supports @racket[".png"] and @racket[".gif"], +while the Latex renderer supports @racket[".png"], @racket[".pdf"], +and @racket[".ps"] (but rendering Latex output to PDF will not work +with @racket[".ps"] files, while rendering to Latex DVI output works +only with @racket[".ps"] files). If @racket[suffixes] is empty or if +none of the suffixes lead to files that exist, @racket[path] is used as-is. -The @scheme[scale] field scales the image in its rendered form.} +The @racket[scale] field scales the image in its rendered form.} @defstruct[(target-element element) ([tag tag?])]{ -Declares the content as a hyperlink target for @scheme[tag].} +Declares the content as a hyperlink target for @racket[tag].} @defstruct[(toc-target-element target-element) ()]{ -Like @scheme[target-element], the content is also a kind of section +Like @racket[target-element], the content is also a kind of section label to be shown in the ``on this page'' table for HTML output.} @defstruct[(page-target-element target-element) ()]{ -Like @scheme[target-element], but a link to the element goes to the +Like @racket[target-element], but a link to the element goes to the top of the containing page.} @defstruct[(redirect-target-element target-element) ([alt-path path-string?] [alt-anchor string?])]{ -Like @scheme[target-element], but a link to the element is redirected +Like @racket[target-element], but a link to the element is redirected to the given URL.} @defstruct[(toc-element element) ([toc-content content?])]{ -Similar to @scheme[toc-target-element], but with specific content for -the ``on this page'' table specified in the @scheme[toc-content] +Similar to @racket[toc-target-element], but with specific content for +the ``on this page'' table specified in the @racket[toc-content] field.} @defstruct[(link-element element) ([tag tag?])]{ -Hyperlinks the content to @scheme[tag]. +Hyperlinks the content to @racket[tag]. -When @scheme[tag] is a part tag and the content of the element is -@scheme[null], then the hyperlink uses the target part's number and/or +When @racket[tag] is a part tag and the content of the element is +@racket[null], then the hyperlink uses the target part's number and/or title as the content. In that case, if the section number is preceded by a word, the word starts in uppercase if the element's style includes a -@scheme['uppercase] property.} +@racket['uppercase] property.} @defstruct[(index-element element) ([tag tag?] @@ -711,57 +711,57 @@ by a word, the word starts in uppercase if the element's style includes a [entry-seq (listof content?)] [desc any/c])]{ -The @scheme[plain-seq] specifies the keys for sorting, where the first +The @racket[plain-seq] specifies the keys for sorting, where the first string is the main key, the second is a sub-key, etc. For example, an ``night'' portion of an index might have sub-entries for ``night, things that go bump in'' and ``night, defender of the''. The -former would be represented by @scheme[plain-seq] @scheme['("night" -"things that go bump in")], and the latter by @scheme['("night" +former would be represented by @racket[plain-seq] @racket['("night" +"things that go bump in")], and the latter by @racket['("night" "defender of the")]. Naturally, single-string -@scheme[plain-seq] lists are the common case, and at least one word is +@racket[plain-seq] lists are the common case, and at least one word is required, but there is no limit to the word-list length. The strings in -@scheme[plain-seq] must not contain a newline character. +@racket[plain-seq] must not contain a newline character. -The @scheme[entry-seq] list must have the same length as -@scheme[plain-seq]. It provides the form of each key to render in the +The @racket[entry-seq] list must have the same length as +@racket[plain-seq]. It provides the form of each key to render in the final document. -The @scheme[desc] field provides additional information about the +The @racket[desc] field provides additional information about the index entry as supplied by the entry creator. For example, a reference -to a procedure binding can be recognized when @scheme[desc] is an -instance of @scheme[procedure-index-desc]. See -@schememodname[scribble/manual-struct] for other typical types of -@scheme[desc] values. +to a procedure binding can be recognized when @racket[desc] is an +instance of @racket[procedure-index-desc]. See +@racketmodname[scribble/manual-struct] for other typical types of +@racket[desc] values. -See also @scheme[index].} +See also @racket[index].} @defstruct[multiarg-element ([style element-style?] [content (listof content?)])]{ -Like @scheme[element] with a list for content, except that for Latex -output, if the @tech{style name} in @scheme[style] is a string, then +Like @racket[element] with a list for content, except that for Latex +output, if the @tech{style name} in @racket[style] is a string, then it corresponds to a Latex command that accepts as many arguments (each -in curly braces) as elements of @scheme[content].} +in curly braces) as elements of @racket[content].} @defstruct[delayed-element ([resolve (any/c part? resolve-info? . -> . list?)] [sizer (-> any/c)] [plain (-> any/c)])]{ -The @scheme[render] procedure's arguments are the same as for -@scheme[delayed-block], but the result is @techlink{content}. -Unlike @scheme[delayed-block], the -result of the @scheme[render] procedure's argument is remembered on +The @racket[render] procedure's arguments are the same as for +@racket[delayed-block], but the result is @techlink{content}. +Unlike @racket[delayed-block], the +result of the @racket[render] procedure's argument is remembered on the first call for re-use for a particular resolve pass. -The @scheme[sizer] field is a procedure that produces a substitute +The @racket[sizer] field is a procedure that produces a substitute @techlink{content} for the delayed element for the purposes of -determining the delayed element's width (see @scheme[element-width]). +determining the delayed element's width (see @racket[element-width]). -The @scheme[plain] field is a procedure that produces a substitute +The @racket[plain] field is a procedure that produces a substitute @techlink{content} when needed before the @techlink{collect pass}, -such as when @scheme[element->string] is used before the @tech{collect +such as when @racket[element->string] is used before the @tech{collect pass}.} @@ -769,35 +769,35 @@ pass}.} [sizer (-> any/c)] [plain (-> any/c)])]{ -Similar to @scheme[delayed-block], but the replacement +Similar to @racket[delayed-block], but the replacement @techlink{content} is obtained in the @techlink{collect pass} by -calling the function in the @scheme[resolve] field. +calling the function in the @racket[resolve] field. -The @scheme[resolve] function can call @scheme[collect-info-parents] +The @racket[resolve] function can call @racket[collect-info-parents] to obtain a list of @techlink{parts} that enclose the element, starting with the nearest enclosing section. Functions like -@scheme[part-collected-info] and @scheme[collected-info-number] can +@racket[part-collected-info] and @racket[collected-info-number] can extract information like the part number.} @defstruct[(collect-element element) ([collect (collect-info . -> . any)])]{ -Like @scheme[element], but the @scheme[collect] procedure is called -during the @techlink{collect pass}. The @scheme[collect] procedure -normally calls @scheme[collect-put!]. +Like @racket[element], but the @racket[collect] procedure is called +during the @techlink{collect pass}. The @racket[collect] procedure +normally calls @racket[collect-put!]. -Unlike @scheme[delayed-element] or @scheme[part-relative-element], the +Unlike @racket[delayed-element] or @racket[part-relative-element], the element remains intact (i.e., it is not replaced) by either the @tech{collect pass} or @tech{resolve pass}.} @defstruct[(render-element element) ([render (any/c part? resolve-info? . -> . any)])]{ -Like @scheme[delayed-element], but the @scheme[render] procedure is called +Like @racket[delayed-element], but the @racket[render] procedure is called during the @techlink{render pass}. -If a @scheme[render-element] instance is serialized (such as when -saving collected info), it is reduced to a @scheme[element] instance.} +If a @racket[render-element] instance is serialized (such as when +saving collected info), it is reduced to a @racket[element] instance.} @defstruct[collected-info ([number (listof (or/c false/c integer?))] @@ -809,35 +809,35 @@ Computed for each part by the @techlink{collect pass}.} @defstruct[target-url ([addr path-string?])]{ -Used as a @tech{style property} for an @scheme[element]. A path is -allowed for @scheme[addr], but a string is interpreted as a URL rather +Used as a @tech{style property} for an @racket[element]. A path is +allowed for @racket[addr], but a string is interpreted as a URL rather than a file path.} @defstruct[document-version ([text (or/c string? false/c)])]{ -Used as a @tech{style property} for a @scheme[path] to indicate a +Used as a @tech{style property} for a @racket[path] to indicate a version number.} @defstruct[color-property ([color (or/c string? (list/c byte? byte? byte?))])]{ -Used as a @tech{style property} for an @scheme[element] to set its -color. Recognized string names for @scheme[color] depend on the +Used as a @tech{style property} for an @racket[element] to set its +color. Recognized string names for @racket[color] depend on the renderer, but at the recognized set includes at least -@scheme["white"], @scheme["black"], @scheme["red"], @scheme["green"], -@scheme["blue"], @scheme["cyan"], @scheme["magenta"], and -@scheme["yellow"]. When @scheme[color] is a list of bytes, the values +@racket["white"], @racket["black"], @racket["red"], @racket["green"], +@racket["blue"], @racket["cyan"], @racket["magenta"], and +@racket["yellow"]. When @racket[color] is a list of bytes, the values are used as RGB levels.} @defstruct[background-color-property ([color (or/c string? (list/c byte? byte? byte?))])]{ -Like @scheme[color-property], but sets the background color.} +Like @racket[color-property], but sets the background color.} @defstruct[table-cells ([styless (listof (listof style?))])]{ -Used as a @tech{style property} for a @scheme[table] to set its cells' +Used as a @tech{style property} for a @racket[table] to set its cells' styles. If a cell style has a string name, it is used as an HTML class for the @@ -847,44 +847,44 @@ The following symbols are recognized as cell-@tech{style properties}: @itemize[ - @item{@scheme['left] --- Left-align the cell content.} + @item{@racket['left] --- Left-align the cell content.} - @item{@scheme['right] --- Right-align the cell content top baselines.} + @item{@racket['right] --- Right-align the cell content top baselines.} - @item{@scheme['center] --- Center the cell content horizontally.} + @item{@racket['center] --- Center the cell content horizontally.} - @item{@scheme['top] --- Top-align the cell content.} + @item{@racket['top] --- Top-align the cell content.} - @item{@scheme['baseline] --- Align the cell content top baselines.} + @item{@racket['baseline] --- Align the cell content top baselines.} - @item{@scheme['bottom] --- bottom-align the cell content.} + @item{@racket['bottom] --- bottom-align the cell content.} - @item{@scheme['vcenter] --- Center the cell content vertically.} + @item{@racket['vcenter] --- Center the cell content vertically.} ] -In addition, for HTML output, @scheme[attributes] structures as +In addition, for HTML output, @racket[attributes] structures as @tech{style properties} can add arbitrary attributes to a cell's @tt{

} tag.} @defstruct[table-columns ([styles (listof style?)])]{ -Like @scheme[table-cells], but the @scheme[styles] list is duplicated +Like @racket[table-cells], but the @racket[styles] list is duplicated for each row in the table. This @tech{style property} is used only when a -@scheme[table-cells] is not present in a style's list of properties.} +@racket[table-cells] is not present in a style's list of properties.} @defproc[(block? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @scheme[paragraph], -@scheme[table], @scheme[itemization], @scheme[nested-flow], or -@scheme[delayed-block], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @racket[paragraph], +@racket[table], @racket[itemization], @racket[nested-flow], or +@racket[delayed-block], @racket[#f] otherwise.} @defproc[(content? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a string, symbol, -@scheme[element], @scheme[multiarg-element], @scheme[delayed-element], -@scheme[part-relative-element], or list of @tech{content}, @scheme[#f] +Returns @racket[#t] if @racket[v] is a string, symbol, +@racket[element], @racket[multiarg-element], @racket[delayed-element], +@racket[part-relative-element], or list of @tech{content}, @racket[#f] otherwise.} @@ -896,28 +896,28 @@ Represents a @techlink{style}.} @defthing[plain style?]{ -A style @scheme[(make-style #f null)].} +A style @racket[(make-style #f null)].} @defproc[(element-style? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a string, symbol, @scheme[#f], -or @scheme[style] structure.} +Returns @racket[#t] if @racket[v] is a string, symbol, @racket[#f], +or @racket[style] structure.} @defproc[(tag? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is acceptable as a link +Returns @racket[#t] if @racket[v] is acceptable as a link @techlink{tag}, which is a list containing a symbol and either a -string, a @scheme[generated-tag] instance, or a list (of arbitrary +string, a @racket[generated-tag] instance, or a list (of arbitrary values).} @defstruct[generated-tag ()]{ A placeholder for a tag to be generated during the @techlink{collect - pass}. Use @scheme[tag-key] to convert a tag containing a - @scheme[generated-tag] instance to one containing a string. + pass}. Use @racket[tag-key] to convert a tag containing a + @racket[generated-tag] instance to one containing a string. } @@ -928,7 +928,7 @@ A placeholder for a tag to be generated during the @techlink{collect Converts @tech{content} to a single string (essentially rendering the content as ``plain text''). -If @scheme[p] and @scheme[info] arguments are not supplied, then a +If @racket[p] and @racket[info] arguments are not supplied, then a pre-``collect'' substitute is obtained for @tech{delayed elements}. Otherwise, the two arguments are used to force the @tech{delayed element} (if it has not been forced already).} @@ -952,7 +952,7 @@ Returns the width in characters of the given @tech{block}.} Encapsulates information accumulated (or being accumulated) from the @techlink{collect pass}. The fields are exposed, but not currently -intended for external use, except that @scheme[collect-info-parents] +intended for external use, except that @racket[collect-info-parents] is intended for external use. } @@ -967,13 +967,13 @@ intended for external use. @defproc[(info-key? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is an @deftech{info key}: a list of +Returns @racket[#t] if @racket[v] is an @deftech{info key}: a list of at least two elements whose first element is a symbol. The result is -@scheme[#f] otherwise. +@racket[#f] otherwise. For a list that is an info tag, the interpretation of the second element of the list is effectively determined by the leading symbol, -which classifies the key. However, a @scheme[#f] value as the second +which classifies the key. However, a @racket[#f] value as the second element has an extra meaning: collected information mapped by such info keys is not propagated out of the part where it is collected; that is, the information is available within the part and its @@ -986,7 +986,7 @@ Note that every @techlink{tag} is an info key. @defproc[(collect-put! [ci collect-info?] [key info-key?] [val any/c]) void?]{ -Registers information in @scheme[ci]. This procedure should be called +Registers information in @racket[ci]. This procedure should be called only during the @techlink{collect pass}. } @@ -995,13 +995,13 @@ only during the @techlink{collect pass}. any/c]{ Extract information during the @techlink{resolve pass} or -@techlink{render pass} for @scheme[p] from @scheme[ri], where the +@techlink{render pass} for @racket[p] from @racket[ri], where the information was previously registered during the @techlink{collect pass}. See also @secref["passes"]. -The result is @scheme[#f] if the no value for the given key is found. +The result is @racket[#f] if the no value for the given key is found. Furthermore, the search failure is recorded for potential consistency -reporting, such as when @exec{setup-plt} is used to build +reporting, such as when @exec{racket setup} is used to build documentation. } @@ -1010,7 +1010,7 @@ documentation. @defproc[(resolve-get/ext? [p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) (values any/c boolean?)]{ -Like @scheme[render-get], but returns a second value to indicate +Like @racket[render-get], but returns a second value to indicate whether the resulting information originated from an external source (i.e., a different document).} @@ -1018,12 +1018,12 @@ whether the resulting information originated from an external source @defproc[(resolve-search [dep-key any/c][p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) void?]{ -Like @scheme[resolve-get], but a shared @scheme[dep-key] groups +Like @racket[resolve-get], but a shared @racket[dep-key] groups multiple searches as a single request for the purposes of consistency reporting and dependency tracking. That is, a single success for the -same @scheme[dep-key] means that all of the failed attempts for the -same @scheme[dep-key] have been satisfied. However, for dependency -checking, such as when using @exec{setup-plt} to re-build +same @racket[dep-key] means that all of the failed attempts for the +same @racket[dep-key] have been satisfied. However, for dependency +checking, such as when using @exec{racket setup} to re-build documentation, all attempts are recorded (in case external changes mean that an earlier attempt would succeed next time). @@ -1032,9 +1032,9 @@ mean that an earlier attempt would succeed next time). @defproc[(resolve-get/tentative [p (or/c part? false/c)] [ri resolve-info?] [key info-key?]) any/c]{ -Like @scheme[resolve-search], but without dependency tracking. For +Like @racket[resolve-search], but without dependency tracking. For multi-document settings where dependencies are normally tracked, such -as when using @exec{setup-plt} to build documentation, this function +as when using @exec{racket setup} to build documentation, this function is suitable for use only for information within a single document. } @@ -1044,8 +1044,8 @@ is suitable for use only for information within a single document. [pred (info-key? . -> . any/c)]) list?]{ -Applies @scheme[pred] to each key mapped for @scheme[p] in -@scheme[ri], returning a list of all keys for which @scheme[pred] +Applies @racket[pred] to each key mapped for @racket[p] in +@racket[ri], returning a list of all keys for which @racket[pred] returns a true value. } @@ -1054,14 +1054,14 @@ returns a true value. [ri resolve-info?]) collected-info?]{ -Returns the information collected for @scheme[p] as recorded within -@scheme[ri]. +Returns the information collected for @racket[p] as recorded within +@racket[ri]. } @defproc[(tag-key [t tag?] [ri resolve-info?]) tag?]{ -Converts a @scheme[generated-tag] value with @scheme[t] to a string. +Converts a @racket[generated-tag] value with @racket[t] to a string. } @@ -1070,7 +1070,7 @@ Converts a @scheme[generated-tag] value with @scheme[t] to a string. @section{HTML Style Properties} @defmodule[scribble/html-properties]{ The -@scheme[scribble/html-properties] library provides datatypes used as +@racket[scribble/html-properties] library provides datatypes used as @tech{style properties} for HTML rendering.} @@ -1082,20 +1082,20 @@ tag.} @defstruct[url-anchor ([name string?])]{ -Used as a @tech{style property} with @scheme[element] to insert an +Used as a @tech{style property} with @racket[element] to insert an anchor before the element.} @defstruct[hover-property ([text string?])]{ -Used as a @tech{style property} with @scheme[element] to add text that +Used as a @tech{style property} with @racket[element] to add text that is shown when the mouse hovers over the element.} @defstruct[script-property ([type string?] [script (or/c path-string? (listof string?))])]{ -Used as a @tech{style property} with @scheme[element] to supply a +Used as a @tech{style property} with @racket[element] to supply a script alternative to the element content.} @@ -1106,8 +1106,8 @@ Used as a @tech{style property} to supply a CSS file to be referenced in the generated HTML. This property can be attached to any style, and all additions are collected to the top of the generated HTML page. -The @scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +The @racket[path] field can be a result of +@racket[path->main-collects-relative].} @defstruct[body-id ([value string?])]{ @@ -1123,7 +1123,7 @@ an HTML tag.} [extra-files (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Like @scheme[latex-defaults], but use for the +Like @racket[latex-defaults], but use for the @exec{scribble} command-line tool's @DFlag{html} and @DFlag{htmls} modes.} @@ -1133,7 +1133,7 @@ Like @scheme[latex-defaults], but use for the @section{Latex Style Properties} @defmodule[scribble/latex-properties]{ The -@scheme[scribble/latex-properties] library provides datatypes used as +@racket[scribble/latex-properties] library provides datatypes used as @tech{style properties} for Latex rendering.} @@ -1145,8 +1145,8 @@ included in the generated Latex. This property can be attached to any style, and all additions are collected to the top of the generated Latex file. -The @scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +The @racket[path] field can be a result of +@racket[path->main-collects-relative].} @defstruct[latex-defaults ([prefix (or/c bytes? path-string? @@ -1156,17 +1156,17 @@ The @scheme[path] field can be a result of [extra-files (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Used as a @tech{style property} on the main @scheme[part] of a document +Used as a @tech{style property} on the main @racket[part] of a document to set a default prefix file, style file, and extra files (see @secref["config-style"]). The defaults are used by the @exec{scribble} command-line tool for and @DFlag{latex} or @DFlag{pdf} mode if none are supplied via @DFlag{prefix} and @DFlag{style} (where -@scheme[extra-files] are used only when @scheme[prefix] is used). A +@racket[extra-files] are used only when @racket[prefix] is used). A byte-string value is used directly like file content, and a path can -be a result of @scheme[path->main-collects-relative]. +be a result of @racket[path->main-collects-relative]. Languages (used with @hash-lang[]) like -@schememodname[scribble/manual] and @schememodname[scribble/sigplan] +@racketmodname[scribble/manual] and @racketmodname[scribble/sigplan] add this property to a document to specify appropriate files for Latex rendering.} @@ -1174,11 +1174,11 @@ rendering.} @defstruct[latex-auto-extra-files ([paths (listof (or/c path-string? (cons/c 'collects (listof bytes?))))])]{ -Used as a @tech{style property} for the main @scheme[part] of a +Used as a @tech{style property} for the main @racket[part] of a document to supply extra files needed to build the document via the @exec{scribble} command-line tool (for @DFlag{latex} and @DFlag{pdf} mode). Languages (used with @hash-lang[]) like -@schememodname[scribble/sigplan] add this property to a document to specify +@racketmodname[scribble/sigplan] add this property to a document to specify appropriate extra files.} diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl index 292bc6a7..e5143e8f 100644 --- a/collects/scribblings/scribble/decode.scrbl +++ b/collects/scribblings/scribble/decode.scrbl @@ -4,11 +4,11 @@ @title[#:tag "decode"]{Decoding Text} -@defmodule[scribble/decode]{The @schememodname[scribble/decode] +@defmodule[scribble/decode]{The @racketmodname[scribble/decode] library helps you write document content in a natural way---more like plain text, except for @litchar["@"] escapes. Roughly, it processes a stream of strings to produces instances of the -@schememodname[scribble/struct] datatypes (see @secref["struct"]).} +@racketmodname[scribble/struct] datatypes (see @secref["struct"]).} At the @tech{flow} level, decoding recognizes a blank line as a @tech{paragraph} separator. Blocks and paragraphs without blank lines @@ -19,24 +19,24 @@ special text conversions: @itemize[ - @item{@litchar{---}: converted to @scheme['mdash], which the HTML render + @item{@litchar{---}: converted to @racket['mdash], which the HTML render outputs as an en-dash surrounded by space (so don't put spaces around @litchar{---} in a document)} - @item{@litchar{--}: converted to @scheme['ndash]} + @item{@litchar{--}: converted to @racket['ndash]} - @item{@litchar{``}: converted to @scheme['ldquo], which is fancy open quotes: ``} + @item{@litchar{``}: converted to @racket['ldquo], which is fancy open quotes: ``} - @item{@litchar{''}: converted to @scheme['rdquo], which is fancy closing quotes: ''} + @item{@litchar{''}: converted to @racket['rdquo], which is fancy closing quotes: ''} - @item{@litchar{'}: converted to @scheme['rsquo], which is a fancy apostrophe: '} + @item{@litchar{'}: converted to @racket['rsquo], which is a fancy apostrophe: '} ] -Some functions @deftech{decode} a sequence of @scheme[_pre-flow] or -@scheme[_pre-content] arguments using @scheme[decode-flow] or -@scheme[decode-content], respectively. For example, the @scheme[bold] -function accepts any number of @scheme[_pre-content] arguments, so +Some functions @deftech{decode} a sequence of @racket[_pre-flow] or +@racket[_pre-content] arguments using @racket[decode-flow] or +@racket[decode-content], respectively. For example, the @racket[bold] +function accepts any number of @racket[_pre-content] arguments, so that in @verbatim[#:indent 2]|{@bold{``apple''}}| @@ -47,52 +47,52 @@ then it is bolded. @defproc[(pre-content? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-content} value: a -string or other non-list @scheme[content], or a @scheme[splice] +Returns @racket[#t] if @racket[v] is a @deftech{pre-content} value: a +string or other non-list @racket[content], or a @racket[splice] containing a list of @tech{pre-content} values; otherwise returns -@scheme[#f]. +@racket[#f]. Pre-content is decoded into @tech{content} by functions like -@scheme[decode-content] and @scheme[decode-paragraph].} +@racket[decode-content] and @racket[decode-paragraph].} @defproc[(pre-flow? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-flow} value: a -string or other non-list @scheme[content], a @scheme[block], -@|void-const|, or a @scheme[splice] containing a list of -@tech{pre-flow} values; otherwise returns @scheme[#f]. +Returns @racket[#t] if @racket[v] is a @deftech{pre-flow} value: a +string or other non-list @racket[content], a @racket[block], +@|void-const|, or a @racket[splice] containing a list of +@tech{pre-flow} values; otherwise returns @racket[#f]. Pre-flow is decoded into a @tech{flow} (i.e., a list of @tech{blocks}) -by functions like @scheme[decode-flow].} +by functions like @racket[decode-flow].} @defproc[(pre-part? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{pre-part} value: a -string or other non-list @scheme[content], a @scheme[block], a -@scheme[part], a @scheme[title-decl], a @scheme[part-start], a -@scheme[part-index-decl], a @scheme[part-collect-decl], a -@scheme[part-tag-decl], @|void-const|, or a @scheme[splice] containing -a list of @tech{pre-part} values; otherwise returns @scheme[#f]. +Returns @racket[#t] if @racket[v] is a @deftech{pre-part} value: a +string or other non-list @tech{content}, a @tech{block}, a +@racket[part], a @racket[title-decl], a @racket[part-start], a +@racket[part-index-decl], a @racket[part-collect-decl], a +@racket[part-tag-decl], @|void-const|, or a @racket[splice] containing +a list of @tech{pre-part} values; otherwise returns @racket[#f]. -A pre-part sequences is decoded into a @scheme[part] by functions like -@scheme[decode] and @scheme[decode-part].} +A pre-part sequence is decoded into a @racket[part] by functions like +@racket[decode] and @racket[decode-part].} @defproc[(decode [lst (listof pre-part?)]) part?]{ -Decodes a document, producing a part. In @scheme[lst], instances of -@scheme[splice] are inlined into the list. An instance of -@scheme[title-decl] supplies the title for the part, plus tag, style -and version information. Instances of @scheme[part-index-decl] (that +Decodes a document, producing a part. In @racket[lst], instances of +@racket[splice] are inlined into the list. An instance of +@racket[title-decl] supplies the title for the part, plus tag, style +and version information. Instances of @racket[part-index-decl] (that precede any sub-part) add index entries that point to the -section. Instances of @scheme[part-collect-decl] add elements to the +section. Instances of @racket[part-collect-decl] add elements to the part that are used only during the @techlink{collect pass}. Instances -of @scheme[part-tag-decl] add hyperlink tags to the section -title. Instances of @scheme[part-start] at level 0 trigger sub-part -parsing. Instances of @scheme[section] trigger are used as-is as -subsections, and instances of @scheme[paragraph] and other +of @racket[part-tag-decl] add hyperlink tags to the section +title. Instances of @racket[part-start] at level 0 trigger sub-part +parsing. Instances of @racket[section] trigger are used as-is as +subsections, and instances of @racket[paragraph] and other flow-element datatypes are used as-is in the enclosing flow.} @@ -102,9 +102,9 @@ flow-element datatypes are used as-is in the enclosing flow.} [depth exact-nonnegative-integer?]) part?]{ -Like @scheme[decode], but given a list of tag string for the part, a -title (if @scheme[#f], then a @scheme[title-decl] instance is used if -found), and a depth for @scheme[part-start]s to trigger sub-part +Like @racket[decode], but given a list of tag string for the part, a +title (if @racket[#f], then a @racket[title-decl] instance is used if +found), and a depth for @racket[part-start]s to trigger sub-part parsing. } @@ -112,9 +112,9 @@ parsing. @defproc[(decode-flow [lst (listof pre-flow?)]) flow?]{ Decodes a flow. A sequence of two or more newlines separated only by -whitespace counts is parsed as a paragraph separator. In @scheme[lst], -instances of @scheme[splice] are inlined into the list. Instances of -@scheme[paragraph] and other flow-element datatypes are used as-is in +whitespace counts is parsed as a paragraph separator. In @racket[lst], +instances of @racket[splice] are inlined into the list. Instances of +@racket[paragraph] and other flow-element datatypes are used as-is in the enclosing flow. } @@ -123,7 +123,7 @@ the enclosing flow. Decodes a compound paragraph. If the compound paragraph contains a single block, the block is returned without a -@scheme[compound-paragraph] wrapper. +@racket[compound-paragraph] wrapper. } @@ -141,7 +141,7 @@ Decodes @tech{content}. @defproc[(decode-elements [lst (listof pre-content?)]) list?]{ -An alias for @scheme[decode-content]. +An alias for @racket[decode-content]. } @defproc[(decode-string [s string?]) (listof content?)]{ @@ -153,7 +153,7 @@ Decodes a single string to produce @tech{content}. @defproc[(whitespace? [s string?]) boolean?]{ -Returns @scheme[#t] if @scheme[s] contains only whitespace, @scheme[#f] +Returns @racket[#t] if @racket[s] contains only whitespace, @racket[#f] otherwise. } @@ -164,9 +164,9 @@ otherwise. [style any/c] [content content?])]{ -See @scheme[decode] and @scheme[decode-part]. The @scheme[tag-prefix] -and @scheme[style] fields are propagated to the resulting -@scheme[part]. +See @racket[decode] and @racket[decode-part]. The @racket[tag-prefix] +and @racket[style] fields are propagated to the resulting +@racket[part]. } @@ -176,33 +176,33 @@ and @scheme[style] fields are propagated to the resulting [style any/c] [title content?])]{ -Like @scheme[title-decl], but for a sub-part. See @scheme[decode] and -@scheme[decode-part]. +Like @racket[title-decl], but for a sub-part. See @racket[decode] and +@racket[decode-part]. } @defstruct[part-index-decl ([plain-seq (listof string?)] [entry-seq list?])]{ -See @scheme[decode]. The two fields are as for @scheme[index-element]. +See @racket[decode]. The two fields are as for @racket[index-element]. } @defstruct[part-collect-decl ([element element?])]{ -See @scheme[decode]. +See @racket[decode]. } @defstruct[part-tag-decl ([tag tag?])]{ -See @scheme[decode]. +See @racket[decode]. } @defstruct[splice ([run list?])]{ -See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow]. +See @racket[decode], @racket[decode-part], and @racket[decode-flow]. } diff --git a/collects/scribblings/scribble/doclang.scrbl b/collects/scribblings/scribble/doclang.scrbl index 080e7d70..062d7e3b 100644 --- a/collects/scribblings/scribble/doclang.scrbl +++ b/collects/scribblings/scribble/doclang.scrbl @@ -3,16 +3,16 @@ @title[#:tag "doclang"]{Document Language} -@defmodulelang[scribble/doclang]{The @schememodname[scribble/doclang] -language provides everything from @scheme[scheme/base], except that it -replaces the @scheme[#%module-begin] form.} +@defmodulelang[scribble/doclang]{The @racketmodname[scribble/doclang] +language provides everything from @racket[racket/base], except that it +replaces the @racket[#%module-begin] form.} -The @schememodname[scribble/doclang] @scheme[#%module-begin] +The @racketmodname[scribble/doclang] @racket[#%module-begin] essentially packages the body of the module into a call to -@scheme[decode], binds the result to @scheme[doc], and exports -@scheme[doc]. +@racket[decode], binds the result to @racket[doc], and exports +@racket[doc]. Any module-level form other than an expression (e.g., a -@scheme[require] or @scheme[define]) remains at the top level, and -the @scheme[doc] binding is put at the end of the module. As usual, a -module-top-level @scheme[begin] slices into the module top level. +@racket[require] or @racket[define]) remains at the top level, and +the @racket[doc] binding is put at the end of the module. As usual, a +module-top-level @racket[begin] slices into the module top level. diff --git a/collects/scribblings/scribble/docreader.scrbl b/collects/scribblings/scribble/docreader.scrbl index 00e77970..19f9acb8 100644 --- a/collects/scribblings/scribble/docreader.scrbl +++ b/collects/scribblings/scribble/docreader.scrbl @@ -5,8 +5,8 @@ @title[#:tag "docreader"]{Document Reader} -@defmodulelang[scribble/doc]{The @schememodname[scribble/doc] language is -the same as @schememodname[scribble/doclang], except that -@scheme[read-syntax-inside] is used to read the body of the module. In +@defmodulelang[scribble/doc]{The @racketmodname[scribble/doc] language is +the same as @racketmodname[scribble/doclang], except that +@racket[read-syntax-inside] is used to read the body of the module. In other words, the module body starts in Scribble ``text'' mode instead of S-expression mode.} diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl index ab93e2af..4c50f071 100644 --- a/collects/scribblings/scribble/eval.scrbl +++ b/collects/scribblings/scribble/eval.scrbl @@ -1,11 +1,11 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-label scheme/sandbox)) + (for-label racket/sandbox)) @title[#:tag "eval"]{Evaluation and Examples} -@defmodule[scribble/eval]{The @scheme[scribble/eval] library provides +@defmodule[scribble/eval]{The @racket[scribble/eval] library provides utilities for evaluating code at document-build time and incorporating the results in the document, especially to show example uses of defined procedures and syntax.} @@ -13,106 +13,106 @@ defined procedures and syntax.} @defform*[[(interaction datum ...) (interaction #:eval eval-expr datum ...)]]{ -Like @scheme[schemeinput], except that the result for each input -@scheme[datum] is shown on the next line. The result is determined by -evaluating the @scheme[quote]d form of the @scheme[datum] using the -evaluator produced by @scheme[eval-expr], if provided. +Like @racket[racketinput], except that the result for each input +@racket[datum] is shown on the next line. The result is determined by +evaluating the @racket[quote]d form of the @racket[datum] using the +evaluator produced by @racket[eval-expr], if provided. -The @scheme[eval-expr] must produce a sandbox evaluator via -@scheme[make-evaluator] or @scheme[make-module-evaluator] with the -@scheme[sandbox-output] and @scheme[sandbox-error-output] parameters -set to @scheme['string]. If @scheme[eval] is not provided, an -evaluator is created using @scheme[make-base-eval]. See also -@scheme[make-eval-factory]. +The @racket[eval-expr] must produce a sandbox evaluator via +@racket[make-evaluator] or @racket[make-module-evaluator] with the +@racket[sandbox-output] and @racket[sandbox-error-output] parameters +set to @racket['string]. If @racket[eval] is not provided, an +evaluator is created using @racket[make-base-eval]. See also +@racket[make-eval-factory]. -Uses of @scheme[code:comment] and @schemeidfont{code:blank} are -stipped from each @scheme[datum] before evaluation. +Uses of @racket[code:comment] and @racketidfont{code:blank} are +stipped from each @racket[datum] before evaluation. -If a @scheme[datum] has the form @scheme[(eval:alts #,(svar -show-datum) #,(svar eval-datum))], then @svar[show-datum] is typeset, -while @svar[eval-datum] is evaluated.} +If a @racket[datum] has the form @racket[(@#,indexed-racket[eval:alts] +#,(svar show-datum) #,(svar eval-datum))], then @svar[show-datum] is +typeset, while @svar[eval-datum] is evaluated.} @defform*[[(interaction-eval datum) (interaction-eval #:eval eval-expr datum)]]{ -Like @scheme[interaction], evaluates the @scheme[quote]d form of -@scheme[datum], but returns the empty string.} +Like @racket[interaction], evaluates the @racket[quote]d form of +@racket[datum], but returns the empty string.} @defform*[[(interaction-eval-show datum) (interaction-eval-show #:eval eval-expr datum)]]{ -Like @scheme[interaction-eval], but produces an element representing +Like @racket[interaction-eval], but produces an element representing the printed form of the evaluation result.} -@defform*[[(schemeblock+eval datum ...) - (schemeblock+eval #:eval eval-expr datum ...)]]{ +@defform*[[(racketblock+eval datum ...) + (racketblock+eval #:eval eval-expr datum ...)]]{ -Combines @scheme[schemeblock] and @scheme[interaction-eval].} +Combines @racket[racketblock] and @racket[interaction-eval].} -@defform*[[(schememod+eval name datum ...) - (schememod+eval #:eval eval-expr name datum ...)]]{ +@defform*[[(racketmod+eval name datum ...) + (racketmod+eval #:eval eval-expr name datum ...)]]{ -Combines @scheme[schememod] and @scheme[interaction-eval].} +Combines @racket[racketmod] and @racket[interaction-eval].} @defform*[[(def+int defn-datum expr-datum ...) (def+int #:eval eval-expr defn-datum expr-datum ...)]]{ -Like @scheme[interaction], except the @scheme[defn-datum] is -typeset as for @scheme[schemeblock] (i.e., no prompt) and a line of -space is inserted before the @scheme[expr-datum]s.} +Like @racket[interaction], except the @racket[defn-datum] is +typeset as for @racket[racketblock] (i.e., no prompt) and a line of +space is inserted before the @racket[expr-datum]s.} @defform*[[(defs+int (defn-datum ...) expr-datum ...) (defs+int #:eval eval-expr (defn-datum ...) expr-datum ...)]]{ -Like @scheme[def+int], but for multiple leading definitions.} +Like @racket[def+int], but for multiple leading definitions.} @defform*[[(examples datum ...) (examples #:eval eval-expr datum ...)]]{ -Like @scheme[interaction], but with an ``Examples:'' label prefixed.} +Like @racket[interaction], but with an ``Examples:'' label prefixed.} @defform*[[(defexamples datum ...) (defexamples #:eval eval-expr datum ...)]]{ -Like @scheme[examples], but each definition using @scheme[define] or -@scheme[define-struct] among the @scheme[datum]s is typeset without a +Like @racket[examples], but each definition using @racket[define] or +@racket[define-struct] among the @racket[datum]s is typeset without a prompt, and with line of space after it.} @defproc[(make-base-eval) (any/c . -> . any)]{ -Creates an evaluator using @scheme[(make-evaluator 'scheme/base)], +Creates an evaluator using @racket[(make-evaluator 'racket/base)], setting sandbox parameters to disable limits, set the outputs to -@scheme['string], and not add extra security guards.} +@racket['string], and not add extra security guards.} @defproc[(make-base-eval-factory [mod-paths (listof module-path?)]) (-> (any/c . -> . any))]{ -Produces a function that is like @scheme[make-base-eval], except that -each module in @scheme[mod-paths] is attached to the evaluator's +Produces a function that is like @racket[make-base-eval], except that +each module in @racket[mod-paths] is attached to the evaluator's namespace. The modules are loaded and instantiated once (when the -returned @scheme[make-base-eval]-like function is called the first +returned @racket[make-base-eval]-like function is called the first time) and then attached to each evaluator that is created.} @defproc[(make-eval-factory [mod-paths (listof module-path?)]) (-> (any/c . -> . any))]{ -Like @scheme[make-base-eval-factor], but each module in @scheme[mod-paths] is +Like @racket[make-base-eval-factor], but each module in @racket[mod-paths] is also required into the top-level environment for each generated evaluator.} @defproc[(close-eval [eval (any/c . -> . any)]) (one-of/c "")]{ -Shuts down an evaluator produced by @scheme[make-base-eval]. Use -@scheme[close-eval] when garbage collection cannot otherwise reclaim +Shuts down an evaluator produced by @racket[make-base-eval]. Use +@racket[close-eval] when garbage collection cannot otherwise reclaim an evaluator (e.g., because it is defined in a module body).} @@ -122,5 +122,5 @@ an evaluator (e.g., because it is defined in a module body).} A parameter that serves as a hook for evaluation. The evaluator to use is supplied as the first argument to the parameter's value, and the second argument is the form to evaluate. The last argument is -@scheme[#t] if exceptions are being captured (to display exception -results), @scheme[#f] otherwise.} +@racket[#t] if exceptions are being captured (to display exception +results), @racket[#f] otherwise.} diff --git a/collects/scribblings/scribble/how-to-paper.scrbl b/collects/scribblings/scribble/how-to-paper.scrbl index a4fe3391..3ee33d45 100644 --- a/collects/scribblings/scribble/how-to-paper.scrbl +++ b/collects/scribblings/scribble/how-to-paper.scrbl @@ -27,10 +27,10 @@ Create a file @filepath{mouse.scrbl} with this content: glass of milk. }| -The first line's @scheme[#, @hash-lang[] #, -@schememodname[scribble/base]] indicates that the file implements a +The first line's @racket[#, @hash-lang[] #, +@racketmodname[scribble/base]] indicates that the file implements a Scribble document. The document starts in ``text mode,'' and the -@litchar["@"] character escapes to operators like @scheme[title], +@litchar["@"] character escapes to operators like @racket[title], where the curly braces return to text mode for the arguments to the operator. The rest is document content. @@ -89,10 +89,10 @@ Add more text to @filepath{mouse.scrbl} so that it looks like this: }| Now, after the first paragraph of the paper, we have two - sub-sections, each created by calling @scheme[section] to + sub-sections, each created by calling @racket[section] to generate a sub-section declaration. The first sub-section has two paragraphs. The second section, as initiated by the result - of the second @scheme[section] call, has a single paragraph. + of the second @racket[section] call, has a single paragraph. Run the @exec{scribble} command(s) from @secref["first-example"] again. You may notice the curly double-quotes in the output; in PDF @@ -104,7 +104,7 @@ for em-dashes in HTML. @section{Splitting the Document Source} As a document grows larger, it's better to split sections into -separate source files. The @scheme[include-section] operation +separate source files. The @racket[include-section] operation incorporates a document defined by a @filepath{.scrbl} file into a larger document. @@ -145,8 +145,8 @@ and in @filepath{straw.scbl}, put }| Notice that the new files both start with @hash-lang[], like the -original document, and the @scheme[section]s from the original -document become @scheme[title]s in the new documents. Both +original document, and the @racket[section]s from the original +document become @racket[title]s in the new documents. Both @filepath{milk.scrbl} and @filepath{straw.scrbl} are documents in their own right with their own titles, and they can be individually rendered using @exec{scribble}. Running @exec{scribble} on @@ -171,7 +171,7 @@ content look right by changing the first line to #lang scribble/sigplan }| -If you're instead working toward PLT Scheme library documentation, +If you're instead working toward Racket library documentation, try changing the first line to @sample|{ @@ -184,11 +184,11 @@ top-level sections turned into chapters that each start on a new page. If you have split the document into multiple files, the first line of the main document file determines the output format. -Using @schememodname[scribble/sigplan] or -@schememodname[scribble/manual] does not change the rendered HTML for -a document---aside from @schememodname[scribble/manual] adding a +Using @racketmodname[scribble/sigplan] or +@racketmodname[scribble/manual] does not change the rendered HTML for +a document---aside from @racketmodname[scribble/manual] adding a version number---but it changes the set of bindings available in the -document body. For example, with @schememodname[scribble/sigplan], the +document body. For example, with @racketmodname[scribble/sigplan], the introductory text can be marked as an abstract: @sample|{ @@ -204,16 +204,16 @@ introductory text can be marked as an abstract: ....}| When rendered as HTML, the abstract shows up as an inset paragraph. If -you try to use @scheme[abstract] with the -@schememodname[scribble/base] or @schememodname[scribble/manual] -language, then you get an error, because @scheme[abstract] is not +you try to use @racket[abstract] with the +@racketmodname[scribble/base] or @racketmodname[scribble/manual] +language, then you get an error, because @racket[abstract] is not defined. When a document is implemented across multiple files, changing the language of the main document can set the style for all of the parts, but it does not introduce bindings into the other part files. For example, if you change the language of @filepath{mouse.scrbl} to -@schememodname[scribble/sigplan], then @scheme[abstract] becomes +@racketmodname[scribble/sigplan], then @racket[abstract] becomes available in @filepath{mouse.scrbl} but not in @filepath{milk.scrbl} or @filepath{straw.scrbl}. In other words, operator names are lexically scoped. @@ -221,9 +221,9 @@ lexically scoped. @; ---------------------------------------- @section{More Functions} -The @schememodname[scribble/sigplan] and -@schememodname[scribble/manual] languages are supersets of the -@schememodname[scribble/base] language, which provides a collection of +The @racketmodname[scribble/sigplan] and +@racketmodname[scribble/manual] languages are supersets of the +@racketmodname[scribble/base] language, which provides a collection of basic operations. Many of the operations are style variations that you can apply to text: @@ -241,15 +241,15 @@ which renders as @italic{probably} ask you for a straw. } -As you would expect, calls to functions like @scheme[smaller], -@scheme[larger], and @scheme[bold] can be nested in other calls. They -can also be nested within calls to @scheme[title] or @scheme[section]: +As you would expect, calls to functions like @racket[smaller], +@racket[larger], and @racket[bold] can be nested in other calls. They +can also be nested within calls to @racket[title] or @racket[section]: @sample|{ @section{@italic{Not} the Last Straw} }| -The @scheme[centered] operation centers a flow of text: +The @racket[centered] operation centers a flow of text: @sample|{ If a mouse eats all your cookies, put up a sign that says @@ -273,19 +273,19 @@ which renders as and see if anyone brings you more. } -The @scheme[margin-note] operation is used in a similar way, but the +The @racket[margin-note] operation is used in a similar way, but the rendered text is moved to the margins. -@margin-note{If you use @scheme[margin-note], then the content shows +@margin-note{If you use @racket[margin-note], then the content shows up over here.} -The @scheme[itemlist] operation creates a sequence of bulleted text, -where the @scheme[item] operation groups text to appear in a single -bullet. The @scheme[itemlist] operation is different from the others +The @racket[itemlist] operation creates a sequence of bulleted text, +where the @racket[item] operation groups text to appear in a single +bullet. The @racket[itemlist] operation is different from the others that we have seen before, because it only accepts values produced by -@scheme[item] instead of arbitrary text. This difference is reflected +@racket[item] instead of arbitrary text. This difference is reflected in the use of @litchar{[}...@litchar{]} for the arguments to -@scheme[itemlist] instead of @litchar["{"]...@litchar["}"]: +@racket[itemlist] instead of @litchar["{"]...@litchar["}"]: @sample|{ @centered{@bold{Notice to Mice}} @@ -306,21 +306,21 @@ which renders as } @; ---------------------------------------- -@section{Text Mode vs. Scheme Mode for Arguments} +@section{Text Mode vs. Racket Mode for Arguments} When @litchar{[}...@litchar{]} surrounds the arguments of an -operation, the argument expressions are in Scheme mode rather than -text mode. Even in Scheme mode, @litchar["@"] can be used to apply +operation, the argument expressions are in Racket mode rather than +text mode. Even in Racket mode, @litchar["@"] can be used to apply operations; once the @"@" syntax is enabled through a -language like @schememodname[scribble/base] (as opposed to -@schememodname[scheme]), it behaves the same in both Scheme mode and +language like @racketmodname[scribble/base] (as opposed to +@racketmodname[racket]), it behaves the same in both Racket mode and text mode. -One advantage of using Scheme mode for the arguments to -@scheme[itemlist] is that we can pass a keyword-tagged optional -argument to @scheme[itemlist]. In particular, if you want a list with -numbers instead of bullets, supply the @scheme['ordered] style to -@scheme[itemlist] using the @scheme[#:style] keyword: +One advantage of using Racket mode for the arguments to +@racket[itemlist] is that we can pass a keyword-tagged optional +argument to @racket[itemlist]. In particular, if you want a list with +numbers instead of bullets, supply the @racket['ordered] style to +@racket[itemlist] using the @racket[#:style] keyword: @sample|{ @itemlist[#:style 'ordered @@ -347,15 +347,15 @@ is equivalent to @italic["Yummy!"] }| -which is equivalent to the Scheme expression +which is equivalent to the Racket expression - @schemeblock[ + @racketblock[ (italic "Yummy!") ] These equivalences explain why Scribble functions are documented in -Scheme notation. If you're reading this in HTML format, you can click -@scheme[italic] above to access its documentation. The documentation +Racket notation. If you're reading this in HTML format, you can click +@racket[italic] above to access its documentation. The documentation won't completely make sense, yet, but it will by the end of this chapter. @@ -364,15 +364,15 @@ to supply other optional arguments? You can use both @litchar{[}...@litchar{]} and @litchar["{"]...@litchar["}"] for an operation, as long as the @litchar{[}...@litchar{]} is first, and as long as no character separate the closing @litchar{]} from the -opening @litchar["{"]. For example, calling @scheme[italic] is the -same as using @scheme[elem] with the @scheme['italic] style: +opening @litchar["{"]. For example, calling @racket[italic] is the +same as using @racket[elem] with the @racket['italic] style: @sample|{ @elem[#:style 'italic]{Yummy!} }| You can also @emph{omit} both @litchar{[}...@litchar{]} and -@litchar["{"]...@litchar["}"]. In that case, the Scheme expression +@litchar["{"]...@litchar["}"]. In that case, the Racket expression after @litchar["@"] is used directly instead of applied as an operation. For example, @@ -386,22 +386,22 @@ renders as 1 plus 2 is @(number->string (+ 1 2)). } -The call to @scheme[number->string] is needed because a naked number +The call to @racket[number->string] is needed because a naked number is not valid as document content. @; ---------------------------------------- @section[#:tag "how-to:reader"]{@"@" Syntax Basics} The @"@" notation provided by Scribble is just another way of -writing Scheme expressions. Scribble documents could be constructed -using normal Scheme notation, without using @"@" at all, but +writing Racket expressions. Scribble documents could be constructed +using normal Racket notation, without using @"@" at all, but that would be inconvenient for most purposes. The @"@" notation makes dealing with textual content much easier. -Whether in text mode or Scheme mode, @litchar["@"] in a document -provides an escape to Scheme mode. The basic syntax of @litchar["@"] is +Whether in text mode or Racket mode, @litchar["@"] in a document +provides an escape to Racket mode. The basic syntax of @litchar["@"] is -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@"] @nonterm{cmd} @litchar{[} @kleenestar{@nonterm{datum}} @litchar{]} @@ -421,42 +421,42 @@ one must be present. No spaces are allowed between ] -A @nonterm{cmd} or @nonterm{datum} is normal Scheme notation, while a +A @nonterm{cmd} or @nonterm{datum} is normal Racket notation, while a @nonterm{text-body} is itself in text mode. A @nonterm{cmd} obviously -must not start with @litchar{[} or @litchar["{"], even though Scheme +must not start with @litchar{[} or @litchar["{"], even though Racket forms could otherwise start with those characters. -The expansion of just @litchar["@"]@nonterm{cmd} into Scheme code is +The expansion of just @litchar["@"]@nonterm{cmd} into Racket code is -@schemeblock[ +@racketblock[ @#,nonterm{cmd} ] When either @litchar{[} @litchar{]} or @litchar["{"] @litchar["}"] are used, the expansion is -@schemeblock[ +@racketblock[ (@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}}) ] where @kleenestar{@nonterm{parsed-body}} is the parse result of the @nonterm{text-body}. The @kleenestar{@nonterm{parsed-body}} part often -turns out to be a sequence of Scheme strings. +turns out to be a sequence of Racket strings. -In practice, the @nonterm{cmd} is normally a Scheme identifier that is +In practice, the @nonterm{cmd} is normally a Racket identifier that is bound to a procedure or syntactic form. If the procedure or form expects further text to typeset, then @litchar["{"]...@litchar["}"] supplies the text. If the form expects other data, typically -@litchar{[}...@litchar{]} is used to surround Scheme arguments, +@litchar{[}...@litchar{]} is used to surround Racket arguments, instead. Even if an operation's argument is a string, if the string is not used as content text (but instead used as, say, a hyperlink label), then the string is typically provided through @litchar{[}...@litchar{]} instead of @litchar["{"]...@litchar["}"]. Sometimes, both @litchar{[}...@litchar{]} and @litchar["{"]...@litchar["}"] are used, where the former surround -Scheme arguments that precede text to typeset. Finally, if a form is a -purely Scheme-level form with not typeset result, such as a -@scheme[require] to import more operations, then typically just +Racket arguments that precede text to typeset. Finally, if a form is a +purely Racket-level form with not typeset result, such as a +@racket[require] to import more operations, then typically just @litchar["@"] is used. For example the text-mode stream @@ -471,9 +471,9 @@ For example the text-mode stream @figure["straw" @elem{A straw}]{@image["straw.png"]} }| -is equivalent to the Scheme-mode sequence +is equivalent to the Racket-mode sequence -@schemeblock[ +@racketblock[ (require scriblib/figure) "\n" "\n" (section #:tag "poetry" "Of Mice and Cookies") "\n" @@ -485,12 +485,12 @@ is equivalent to the Scheme-mode sequence Besides showing how different argument conventions are used for different operations, the above example illustrates how whitespace is -preserved in the Scheme form of a text-mode stream---including +preserved in the Racket form of a text-mode stream---including newlines preserved as their own strings. Notice how the second -@scheme[section] gets two arguments for its content, since the -argument content for @scheme[section] in the source stream includes +@racket[section] gets two arguments for its content, since the +argument content for @racket[section] in the source stream includes both the use of an operator and additional text. When an operation -like @scheme[section] or @scheme[italic] accepts content to typeset, +like @racket[section] or @racket[italic] accepts content to typeset, it normally accepts an arbitrary number of arguments that together form the content. @@ -502,21 +502,21 @@ arguments while disabling @litchar["@"] between the brackets. @; ---------------------------------------- @section{Decoding Sequences} -In a document that starts @scheme[#, @hash-lang[] #, -@schememodname[scribble/base]], the top level is a text-mode stream, +In a document that starts @racket[#, @hash-lang[] #, +@racketmodname[scribble/base]], the top level is a text-mode stream, just like the @nonterm{text-body} in a @litchar["@"] form. As illustrated in the previous section, such a top-level sequence -corresponds to a mixture of Scheme-mode strings and operation -applications. There's an implicit operation, @scheme[decode], that +corresponds to a mixture of Racket-mode strings and operation +applications. There's an implicit operation, @racket[decode], that wraps the whole document to consume this mixture of strings and other values and turn them into a document description. -The @scheme[decode] operation implements @defterm{flow decoding}, +The @racket[decode] operation implements @defterm{flow decoding}, which takes a document stream and breaks it up into sections and paragraphs. Blank lines delimit paragraphs, and the results of -operations like @scheme[title] and @scheme[section] generate ``here's +operations like @racket[title] and @racket[section] generate ``here's the title'' or ``a new section starts here'' declarations that are -recognized by @scheme[decode]. +recognized by @racket[decode]. A different but related @defterm{content decoding} takes place within a paragraph or section title. Content decoding is responsible for @@ -524,16 +524,16 @@ converting @litchar{---} to an em-dash or for converting @litchar{"} and @litchar{'} to suitable curly quotes. The decoding process for document's stream is ultimately determined by -the @hash-lang[] line that starts the document. The @schememodname[scribble/base], -@schememodname[scribble/manual], and @schememodname[scribble/sigplan] -languages all use the same @scheme[decode] operation. The -@schememodname[scribble/text] language, however, acts more like a +the @hash-lang[] line that starts the document. The @racketmodname[scribble/base], +@racketmodname[scribble/manual], and @racketmodname[scribble/sigplan] +languages all use the same @racket[decode] operation. The +@racketmodname[scribble/text] language, however, acts more like a plain-text preprocessor and it does not perform any such decoding -rules. (For more on @schememodname[scribble/text], see +rules. (For more on @racketmodname[scribble/text], see @secref["preprocessor"].) @margin-note{More precisely, languages like - @schememodname[scribble/base] apply @scheme[decode] only after + @racketmodname[scribble/base] apply @racket[decode] only after lifting out all definitions and imports from the document stream.} @@ -542,10 +542,10 @@ paragraphs, it applies content decoding to strings within the paragraph. When content is wrapped with an operation, however, content decoding does not apply automatically. An operation is responsible for calling a content or flow decoder as it sees fit. Most operations call -the decoder; for example, @scheme[italic], @scheme[bold], -@scheme[smaller], etc., all decode their arguments. Similarly, -@scheme[title] and @scheme[section] decode the given content for the -title or section name. The @scheme[literal] and @scheme[verbatim] +the decoder; for example, @racket[italic], @racket[bold], +@racket[smaller], etc., all decode their arguments. Similarly, +@racket[title] and @racket[section] decode the given content for the +title or section name. The @racket[literal] and @racket[verbatim] operators, however, do not decode the given strings. For example, @sample|{ @@ -577,9 +577,9 @@ because the source is equivalent to (verbatim (number->string (+ 1 2))) }| -where @scheme[(number->string (+ 1 2))] is evaluated to produce the -argument to @scheme[verbatim]. The @litchar["|{"]...@litchar["}|"] -style of brackets is often used with @scheme[verbatim], because +where @racket[(number->string (+ 1 2))] is evaluated to produce the +argument to @racket[verbatim]. The @litchar["|{"]...@litchar["}|"] +style of brackets is often used with @racket[verbatim], because @litchar["|{"]...@litchar["}|"] disables @"@" notation for arguments. For example, @@ -596,12 +596,12 @@ renders as @; ---------------------------------------- @section[#:tag "roadmap"]{Next Steps} -If your immediate goal is to document a PLT Scheme library or write +If your immediate goal is to document a Racket library or write literate programs, skip to @secref["how-to-doc"], and then go back to @secref["reader"] and other chapters. -If you are more interested in producing documents unrelated to PLT -Scheme, continue with @secref["reader"] and then +If you are more interested in producing documents unrelated to +Racket, continue with @secref["reader"] and then @secref["generic-prose"]. Move on to @secref["internals"] when you need more power. diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl index 16667302..de61a924 100644 --- a/collects/scribblings/scribble/how-to.scrbl +++ b/collects/scribblings/scribble/how-to.scrbl @@ -6,9 +6,9 @@ @title[#:tag "how-to-doc"]{Getting Started with Documentation} Although the @exec{scribble} command-line utility generates output -from a Scribble document, 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 +from a Scribble document, documentation of Racket libraries is +normally built by @exec{raco setup}. This chapter emphasizes the +@exec{raco setup} approach, which more automatically supports links across documents. @margin-note{See @secref["getting-started"] for information on using the @@ -33,36 +33,36 @@ To document a collection or @|PLaneT| package: @title{My Library} - Welcome to my documentation: @scheme[(list 'testing 1 2 3)]. + Welcome to my documentation: @racket[(list 'testing 1 2 3)]. }| The first line starts the file in ``text'' mode and selects - the PLT Scheme manual output format. - It also introduces bindings like @scheme[title] and - @scheme[scheme] for writing PLT Scheme documentation.} + the Racket manual output format. + It also introduces bindings like @racket[title] and + @racket[racket] for writing Racket documentation.} @item{Add the following entry to your collect or package's - @filepath{info.ss}: + @filepath{info.rkt}: - @schemeblock[ + @racketblock[ (define scribblings '(("manual.scrbl" ()))) ] - The @scheme[()] above is a list of options. When your document + The @racket[()] above is a list of options. When your document gets large enough that you want it split into multiple pages, - add the @scheme['multi-page] option (omitting the quote, since + add the @racket['multi-page] option (omitting the quote, since the whole right-hand side of the definition is already quoted). - If you do not already have an @filepath{info.ss} module, + If you do not already have an @filepath{info.rkt} module, here's a suitable complete module: - @schememod[ + @racketmod[ setup/infotab (define scribblings '(("manual.scrbl" ()))) ]} - @item{Run @exec{setup-plt} to build your documentation. For a + @item{Run @exec{raco setup} to build your documentation. For a collection, optionally supply @Flag{l} followed by the collection name to limit the build process to that collection. For a @|PLaneT| package, optionally supply @@ -71,64 +71,64 @@ To document a collection or @|PLaneT| package: @item{The generated documentation is normally @filepath{doc/manual/index.html} within the collection or - @|PLaneT| package directory. If the collection is in PLT - Scheme's main @filepath{collects} directory, however, then the + @|PLaneT| package directory. If the collection is in + Racket's main @filepath{collects} directory, however, then the documentation is generated as @filepath{manual/index.html} in the installation's main @filepath{doc} directory.} ] @; ---------------------------------------- -@section[#:tag "scheme-hyperlinks"]{Scheme Typesetting and Hyperlinks} +@section[#:tag "racket-hyperlinks"]{Racket Typesetting and Hyperlinks} In the document source at the start of this chapter -(@secref["setting-up"]), the Scheme expression -@scheme[(#,(schemeidfont "list") 'testing 1 2 3)] is typeset properly, -but the @schemeidfont{list} identifier is not hyperlinked to the usual -definition. To cause @schemeidfont{list} to be hyperlinked, add a -@scheme[require] form like this: +(@secref["setting-up"]), the Racket expression +@racket[(#,(racketidfont "list") 'testing 1 2 3)] is typeset properly, +but the @racketidfont{list} identifier is not hyperlinked to the usual +definition. To cause @racketidfont{list} to be hyperlinked, add a +@racket[require] form like this: @verbatim[#:indent 2]|{ - @(require (for-label scheme)) + @(require (for-label racket)) }| -This @scheme[require] with @scheme[for-label] declaration introduces a -document-time binding for each export of the @schememodname[scheme] -module. When the document is built, the @scheme[scheme] form detects -the binding for @scheme[list], and so it generates a reference to the -specification of @scheme[list]. The setup process detects the +This @racket[require] with @racket[for-label] declaration introduces a +document-time binding for each export of the @racketmodname[racket] +module. When the document is built, the @racket[racket] form detects +the binding for @racket[list], and so it generates a reference to the +specification of @racket[list]. The setup process detects the reference, and it finds the matching specification in the existing documentation, and ultimately directs the hyperlink to that specification. -Hyperlinks based on @scheme[for-label] and @scheme[scheme] are the +Hyperlinks based on @racket[for-label] and @racket[racket] are the preferred mechanism for linking to information outside of a single document. Such links require no information about where and how a binding is documented elsewhere: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - See also @scheme[list]. + See also @racket[list]. }| -The @scheme[scheme] form typesets a Scheme expression for inline text, +The @racket[racket] form typesets a Racket expression for inline text, so it ignores the source formatting of the expression. The -@scheme[schemeblock] form, in contrast, typesets inset Scheme code, +@racket[racketblock] form, in contrast, typesets inset Racket code, and it preserves the expression's formatting from the document source. @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - Some example Scheme code: + Some example Racket code: - @schemeblock[ + @racketblock[ (define (nobody-understands-me what) (list "When I think of all the" what @@ -141,22 +141,22 @@ and it preserves the expression's formatting from the document source. @; ---------------------------------------- @section[#:tag "section-hyperlinks"]{Section Hyperlinks} -A @scheme[section] declaration in a document can include a -@scheme[#:tag] argument that declares a hyperlink-target tag. The -@scheme[secref] function generates a hyperlink, using the section name -as the text of the hyperlink. Use @scheme[seclink] to create a +A @racket[section] declaration in a document can include a +@racket[#:tag] argument that declares a hyperlink-target tag. The +@racket[secref] function generates a hyperlink, using the section name +as the text of the hyperlink. Use @racket[seclink] to create a hyperlink with text other than the section title. The following example illustrates section hyperlinks: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @title{My Library} - Welcome to my documentation: @scheme[(list 'testing 1 2 3)]. + Welcome to my documentation: @racket[(list 'testing 1 2 3)]. @table-of-contents[] @@ -172,24 +172,24 @@ The following example illustrates section hyperlinks: }| Since the page is so short, the hyperlinks in the above example are - more effective if you change the @filepath{info.ss} file to add the - @scheme['multi-file] flag: + more effective if you change the @filepath{info.rkt} file to add the + @racket['multi-file] flag: -@schemeblock[ +@racketblock[ (define scribblings '(("manual.scrbl" (multi-page)))) ] A section can have a @techlink{tag prefix} that applies to all tags as seen from outside the section. Such a prefix is automatically given to -each top-level document as processed by @exec{setup-plt}. Thus, +each top-level document as processed by @exec{raco setup}. Thus, referencing a section tag in a different document requires using a prefix, which is based on the target document's main source file. The -following example links to a section in the PLT Scheme reference +following example links to a section in the Racket reference manual: @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme)) + @(require (for-label racket)) @(define ref-src '(lib "scribblings/reference/reference.scrbl")) @@ -198,41 +198,41 @@ manual: See also @italic{@secref[#:doc ref-src]{pairs}}. }| -As mentioned in @secref{scheme-hyperlinks}, however, cross-document -references based on @scheme[(require (for-label ....))] and -@scheme[scheme] are usually better than cross-document references -using @scheme[secref]. +As mentioned in @secref{racket-hyperlinks}, however, cross-document +references based on @racket[(require (for-label ....))] and +@racket[racket] are usually better than cross-document references +using @racket[secref]. @; ---------------------------------------- -@section{Defining Scheme Bindings} +@section{Defining Racket Bindings} -Use @scheme[defproc] to document a procedure, @scheme[defform] to -document a syntactic form, @scheme[defstruct] to document a structure +Use @racket[defproc] to document a procedure, @racket[defform] to +document a syntactic form, @racket[defstruct] to document a structure type, etc. These forms provide consistent formatting of definitions, -and they declare hyperlink targets for @scheme[scheme]-based +and they declare hyperlink targets for @racket[racket]-based hyperlinks. -To document a @scheme[my-helper] procedure that is exported by -@filepath{helper.ss} in the @filepath{my-lib} collection that contains +To document a @racket[my-helper] procedure that is exported by +@filepath{helper.rkt} in the @filepath{my-lib} collection that contains @filepath{manual.scrbl}: @itemize[ - @item{Use @scheme[(require (for-label "helper.ss"))] to import the - binding information about the bindings of @filepath{helper.ss} + @item{Use @racket[(require (for-label "helper.rkt"))] to import the + binding information about the bindings of @filepath{helper.rkt} for use when typesetting identifiers. A relative reference - @scheme["helper.ss"] works since it is relative to the + @racket["helper.rkt"] works since it is relative to the documentation source.} @item{Add a @tt|{@defmodule[my-lib/helper]}| declaration, which specifies the library that is being documented within the - section. The @scheme[defmodule] form needs an absolute module - name @scheme[mylib/helper], instead of a relative reference - @scheme["helper.ss"], since the module path given to - @scheme[defmodule] appears verbatim in the generated + section. The @racket[defmodule] form needs an absolute module + name @racket[mylib/helper], instead of a relative reference + @racket["helper.rkt"], since the module path given to + @racket[defmodule] appears verbatim in the generated documentation.} - @item{Use @scheme[defproc] to document the procedure.} + @item{Use @racket[defproc] to document the procedure.} ] @@ -243,8 +243,8 @@ following: @; planet libraries @verbatim[#:indent 2]|{ #lang scribble/manual - @(require (for-label scheme - "helper.ss")) + @(require (for-label racket + "helper.rkt")) @title{My Library} @@ -254,24 +254,24 @@ following: (listof (not/c (one-of/c 'cow)))]{ - Replaces each @scheme['cow] in @scheme[lst] with - @scheme['aardvark].} + Replaces each @racket['cow] in @racket[lst] with + @racket['aardvark].} }| -In @scheme[defproc], a contract is specified with each argument to the -procedure. In this example, the contract for the @scheme[_lst] -argument is @scheme[list?], which is the contract for a list. After +In @racket[defproc], a contract is specified with each argument to the +procedure. In this example, the contract for the @racket[_lst] +argument is @racket[list?], which is the contract for a list. After the closing parenthesis that ends the argument sequence, the contract -of the result must be given; in this case, @scheme[my-helper] +of the result must be given; in this case, @racket[my-helper] guarantees a result that is a list where none of the elements are -@scheme['cow]. +@racket['cow]. Some things to notice in this example and the documentation that it generates: @itemize[ - @item{The @scheme[list?], @scheme[listof], @|etc| elements of + @item{The @racket[list?], @racket[listof], @|etc| elements of contracts are hyperlinked to their documentation.} @item{The result contract is formatted in the generated documentation @@ -279,56 +279,56 @@ generates: contracts is preserved. (In this case, putting the contract all on one line would be better.)} - @item{In the prose that documents @scheme[my-helper], @scheme[_lst] + @item{In the prose that documents @racket[my-helper], @racket[_lst] is automatically typeset in italic, matching the typesetting in - the blue box. The @scheme[scheme] form essentially knows that + the blue box. The @racket[racket] form essentially knows that it's used in the scope of a procedure with argument - @scheme[_lst].} + @racket[_lst].} - @item{If you hover the mouse pointer over @scheme[my-helper], a popup - reports that it is provided from @schemeidfont{my-lib/helper}.} + @item{If you hover the mouse pointer over @racket[my-helper], a popup + reports that it is provided from @racketidfont{my-lib/helper}.} - @item{If you use @scheme[my-helper] in any documentation now, as long - as that documentation source also has a @scheme[(require - (for-label ....))] of @filepath{helper.ss}, then the + @item{If you use @racket[my-helper] in any documentation now, as long + as that documentation source also has a @racket[(require + (for-label ....))] of @filepath{helper.rkt}, then the reference is hyperlinked to the definition above.} ] -See @scheme[defproc*], @scheme[defform], @|etc| for more information -on forms to document Scheme bindings. +See @racket[defproc*], @racket[defform], @|etc| for more information +on forms to document Racket bindings. @; ---------------------------------------- -@section{Showing Scheme Examples} +@section{Showing Racket Examples} -The @scheme[examples] form from @scheme[scribble/eval] +The @racket[examples] form from @racket[scribble/eval] helps you generate examples in your documentation. @bold{Warning:} the -@scheme[examples] form is especially likely to change or be replaced. +@racket[examples] form is especially likely to change or be replaced. -To use @scheme[examples], the procedures to document must be suitable -for use at documentation time; in fact, @scheme[examples] uses +To use @racket[examples], the procedures to document must be suitable +for use at documentation time; in fact, @racket[examples] uses bindings introduced into the document source by -@scheme[require]. Thus, to generate examples using @scheme[my-helper] -from the previous section, @filepath{helper.ss} must be imported both -via @scheme[require-for-label] and @scheme[require]: +@racket[require]. Thus, to generate examples using @racket[my-helper] +from the previous section, @filepath{helper.rkt} must be imported both +via @racket[require-for-label] and @racket[require]: @verbatim[#:indent 2]|{ #lang scribble/manual @(require scribble/eval ; <--- added - "helper.ss" ; <--- added - (for-label scheme - "helper.ss")) + "helper.rkt" ; <--- added + (for-label racket + "helper.rkt")) @title{My Library} - @defmodule[my-lib/helper]{The @schememodname[my-lib/helper] + @defmodule[my-lib/helper]{The @racketmodname[my-lib/helper] module---now with extra cows!} @defproc[(my-helper [lst list?]) (listof (not/c (one-of/c 'cow)))]{ - Replaces each @scheme['cow] in @scheme[lst] with - @scheme['aardvark]. + Replaces each @racket['cow] in @racket[lst] with + @racket['aardvark]. @examples[ (my-helper '()) @@ -339,14 +339,14 @@ via @scheme[require-for-label] and @scheme[require]: @;---------------------------------------- @section{Multi-Page Sections} -Setting the @scheme['multi-page] option (see +Setting the @racket['multi-page] option (see @secref["section-hyperlinks"]) causes each top-level section of a document to be rendered as a separate HTML page. -To push sub-sections onto separate pages, use the @scheme['toc] style -for the enclosing section (as started by @scheme[title], -@scheme[section], @scheme[subsection], etc.) and use -@scheme[local-table-of-contents] to generate hyperlinks to the +To push sub-sections onto separate pages, use the @racket['toc] style +for the enclosing section (as started by @racket[title], +@racket[section], @racket[subsection], etc.) and use +@racket[local-table-of-contents] to generate hyperlinks to the sub-sections. Revising @filepath{cows.scrbl} from the previous section: @@ -365,19 +365,19 @@ Revising @filepath{cows.scrbl} from the previous section: See @secref["singing"]. }| -To run this example, remember to change @filepath{info.ss} to add the -@scheme['multi-page] style. You may also want to add a call to -@scheme[table-of-contents] in @filepath{manual.scrbl}. +To run this example, remember to change @filepath{info.rkt} to add the +@racket['multi-page] style. You may also want to add a call to +@racket[table-of-contents] in @filepath{manual.scrbl}. -The difference between @scheme[table-of-contents] and -@scheme[local-table-of-contents] is that the latter is ignored for +The difference between @racket[table-of-contents] and +@racket[local-table-of-contents] is that the latter is ignored for Latex output. -When using @scheme[local-table-of-contents], it often makes sense to +When using @racket[local-table-of-contents], it often makes sense to include introductory text before the call of -@scheme[local-table-of-contents]. When the introductory text is less +@racket[local-table-of-contents]. When the introductory text is less important and when when local table of contents is short, putting the -introductory text after the call of @scheme[local-table-of-contents] +introductory text after the call of @racket[local-table-of-contents] may be appropriate. @;---------------------------------------- diff --git a/collects/scribblings/scribble/info.ss b/collects/scribblings/scribble/info.rkt similarity index 100% rename from collects/scribblings/scribble/info.ss rename to collects/scribblings/scribble/info.rkt diff --git a/collects/scribblings/scribble/jfp.scrbl b/collects/scribblings/scribble/jfp.scrbl index 15424cd4..06e89fa7 100644 --- a/collects/scribblings/scribble/jfp.scrbl +++ b/collects/scribblings/scribble/jfp.scrbl @@ -5,18 +5,18 @@ @(define-syntax-rule (def base-author) (begin (require (for-label scribble/base)) - (define base-author @scheme[author]))) + (define base-author @racket[author]))) @(def base-author) @title{JFP Paper Format} -@defmodulelang[scribble/jfp]{The @schememodname[scribble/jfp] -language is like @schememodname[scribble/manual], but configured with +@defmodulelang[scribble/jfp]{The @racketmodname[scribble/jfp] +language is like @racketmodname[scribble/manual], but configured with Latex style defaults to use the @filepath{jfp.cls} class file that is included with Scribble.} -Latex output with @schememodname[scribble/jfp] uses a main-document -version supplied to @scheme[title] as the short-form document name (to +Latex output with @racketmodname[scribble/jfp] uses a main-document +version supplied to @racket[title] as the short-form document name (to be used in page headers). @defproc[(abstract [pre-content pre-content?] ...) block?]{ @@ -25,19 +25,19 @@ Generates a @tech{nested flow} for a paper abstract.} @defform[(include-abstract module-path)]{ -Similar to @scheme[include-section], but incorporates the document in the +Similar to @racket[include-section], but incorporates the document in the specified module as an abstract. The document must have no title or sub-parts.} @defproc[(author [name pre-content?] ...) block?]{ -A replacement for @base-author from @schememodname[scribble/base].} +A replacement for @base-author from @racketmodname[scribble/base].} @defproc[((author/short [short-name pre-content?] ...) [long-name pre-content?] ...) block?]{ -Like @scheme[author], but allows the short-form names (to be used in +Like @racket[author], but allows the short-form names (to be used in page headers) to be specified separately from the long-form name.} @deftogether[( @@ -46,10 +46,10 @@ page headers) to be specified separately from the long-form name.} @defproc[(affiliation-sep) element?] )]{ -Use @scheme[affiliation] within @scheme[author] or the long-name part -of @scheme[author/short] to specify affiliations after all authors. +Use @racket[affiliation] within @racket[author] or the long-name part +of @racket[author/short] to specify affiliations after all authors. If different authors have different affiliations, use -@scheme[affiliation-mark] with a number after each author, and then -use @scheme[affiliation-mark] before each different affiliation within -a single @scheme[affiliation], using @scheme[(affiliation-sep)] to +@racket[affiliation-mark] with a number after each author, and then +use @racket[affiliation-mark] before each different affiliation within +a single @racket[affiliation], using @racket[(affiliation-sep)] to separate affiliations.} diff --git a/collects/scribblings/scribble/layers.scrbl b/collects/scribblings/scribble/layers.scrbl index db1aea9f..5583ef34 100644 --- a/collects/scribblings/scribble/layers.scrbl +++ b/collects/scribblings/scribble/layers.scrbl @@ -16,31 +16,31 @@ and instead use the document-generation structure directly. A Scribble document normally starts -@schememod[ +@racketmod[ scribble/manual ] but it could also start -@schememod[ +@racketmod[ scribble/base ] or -@schememod[ +@racketmod[ scribble/doc ] The last one introduces the smallest number of typesetting bindings in -the document body. Using @schememodname[scribble/base] after -@hash-lang[] is the same as using @schememodname[scribble/doc] plus -@scheme[(require scribble/base)], and using -@schememodname[scribble/manual] after @hash-lang[] is the same as using -@schememodname[scribble/doc] plus @scheme[(require scribble/manual)]. +the document body. Using @racketmodname[scribble/base] after +@hash-lang[] is the same as using @racketmodname[scribble/doc] plus +@racket[(require scribble/base)], and using +@racketmodname[scribble/manual] after @hash-lang[] is the same as using +@racketmodname[scribble/doc] plus @racket[(require scribble/manual)]. Besides making the file a module, each of the @hash-lang[] -declarations selects the Scribble reader (instead of the usual Scheme +declarations selects the Scribble reader (instead of the usual Racket reader), and it starts the body of the file in ``text'' mode. The reader layer mostly leaves text alone, but @litchar["@"] forms escape to S-expression mode. @@ -61,7 +61,7 @@ A module written as reads as -@schemeblock[ +@racketblock[ (module #,(nonterm "name") scribble/doc (require scribble/manual) "\n" @@ -74,14 +74,14 @@ reads as ] As shown in this example, the read result is a module whose content -mingles text and definitions. The @schememodname[scribble/doc] -language lifts definitions, @scheme[require]s, and @scheme[provide]s +mingles text and definitions. The @racketmodname[scribble/doc] +language lifts definitions, @racket[require]s, and @racket[provide]s to the beginning of the module, while everything else is collected -into a document bound to the provided identifier @scheme[doc]. That +into a document bound to the provided identifier @racket[doc]. That is, the module is transformed to something like this: -@schemeblock[ -(module #,(nonterm "name") scheme/base +@racketblock[ +(module #,(nonterm "name") racket/base (require scribble/decode scribble/manual) (define to-be "To Be") @@ -95,23 +95,23 @@ is, the module is transformed to something like this: (provide doc)) ] -The @scheme[decode] function produces a @scheme[part] structure -instance that represents the document. To build the @scheme[part] -instance, it inspects its arguments to find a @scheme[title-decl] -value created by @scheme[title] to name the part, @scheme[part-start] -values created by @scheme[section] to designate sub-parts, etc. +The @racket[decode] function produces a @racket[part] structure +instance that represents the document. To build the @racket[part] +instance, it inspects its arguments to find a @racket[title-decl] +value created by @racket[title] to name the part, @racket[part-start] +values created by @racket[section] to designate sub-parts, etc. -A @scheme[part] is the input to a rendering back-end, such as the HTML +A @racket[part] is the input to a rendering back-end, such as the HTML renderer. All renderers recognize a fixed structure hierarchy: the content of a part is a @defterm{flow}, which is a sequence of @defterm{flow elements}, such as paragraphs and tables; a table, in turn, consists of a list of list of flows; a paragraph is a list of -@defterm{elements}, which can be instances of the @scheme[element] +@defterm{elements}, which can be instances of the @racket[element] structure type, plain strings, or certain special symbols. -The value bound to @scheme[doc] in the example above is something like +The value bound to @racket[doc] in the example above is something like -@schemeblock[ +@racketblock[ (make-part .... (list "To Be" " or Not " "To Be") (code:comment "title") .... @@ -125,38 +125,38 @@ The value bound to @scheme[doc] in the example above is something like ] Notice that the @litchar{'} in the input's @litchar{'tis} has turned -into @scheme['rsquo] (rendered as a curly apostrophe). The conversion to use -@scheme['rsquo] was performed by @scheme[decode] via -@scheme[decode-flow] via @scheme[decode-paragraph] via -@scheme[decode-content] via @scheme[decode-string]. +into @racket['rsquo] (rendered as a curly apostrophe). The conversion to use +@racket['rsquo] was performed by @racket[decode] via +@racket[decode-flow] via @racket[decode-paragraph] via +@racket[decode-content] via @racket[decode-string]. -In contrast, @scheme[(make-element 'bold (list "That"))] was produced -by the @scheme[bold] function. The @scheme[decode] operation is a -function, not a syntactic form, and so @scheme[bold] has control over -its argument before @scheme[decode] sees the result. Also, decoding +In contrast, @racket[(make-element 'bold (list "That"))] was produced +by the @racket[bold] function. The @racket[decode] operation is a +function, not a syntactic form, and so @racket[bold] has control over +its argument before @racket[decode] sees the result. Also, decoding traverses only immediate string arguments. -As it turns out, @scheme[bold] also decodes its argument, because the -@scheme[bold] function is implemented as +As it turns out, @racket[bold] also decodes its argument, because the +@racket[bold] function is implemented as -@schemeblock[ +@racketblock[ (define (bold . strs) (make-element 'bold (decode-content strs))) ] -The @scheme[verbatim] function, however, does not decode its content, +The @racket[verbatim] function, however, does not decode its content, and instead typesets its text arguments directly. A document module can construct elements directly using -@scheme[make-element], but normally functions like @scheme[bold] and -@scheme[verbatim] are used to construct them. In particular, the -@schememodname[scribble/manual] library provides many functions and +@racket[make-element], but normally functions like @racket[bold] and +@racket[verbatim] are used to construct them. In particular, the +@racketmodname[scribble/manual] library provides many functions and forms to typeset elements and flow elements. -The @scheme[part] structure hierarchy includes built-in element types +The @racket[part] structure hierarchy includes built-in element types for setting hyperlink targets and references. Again, this machinery is normally packaged into higher-level functions and forms, such as -@scheme[secref], @scheme[defproc], and @scheme[scheme]. +@racket[secref], @racket[defproc], and @racket[racket]. @; ---------------------------------------------------------------------- @@ -166,76 +166,76 @@ Working roughly from the bottom up, the Scribble layers are: @itemize[ - @item{@schememodname[scribble/reader]: A reader that extends the - syntax of Scheme with @"@"-forms for conveniently embedding a + @item{@racketmodname[scribble/reader]: A reader that extends the + syntax of Racket with @"@"-forms for conveniently embedding a mixin of text and escapes. See @secref["reader"].} - @item{@schememodname[scribble/core]: A set of document datatypes + @item{@racketmodname[scribble/core]: A set of document datatypes and utilities that define the basic layout and processing of a - document. For example, the @scheme[part] datatype is defined in + document. For example, the @racket[part] datatype is defined in this layer. See @secref["core"].} - @item{@schememodname[scribble/base-render] with - @schememodname[scribble/html-render], - @schememodname[scribble/latex-render], or - @schememodname[scribble/text-render]: A base renderer and + @item{@racketmodname[scribble/base-render] with + @racketmodname[scribble/html-render], + @racketmodname[scribble/latex-render], or + @racketmodname[scribble/text-render]: A base renderer and mixins that generate documents in various formats from - instances of the @schememodname[scribble/struct] datatypes. See + instances of the @racketmodname[scribble/struct] datatypes. See @secref["renderer"].} - @item{@schememodname[scribble/decode]: Processes a stream of text, + @item{@racketmodname[scribble/decode]: Processes a stream of text, section-start markers, etc. to produce instances of the - @schememodname[scribble/core] datatypes. See + @racketmodname[scribble/core] datatypes. See @secref["decode"].} - @item{@schememodname[scribble/doclang]: A language to be used for the + @item{@racketmodname[scribble/doclang]: A language to be used for the initial import of a module; processes the module top level - through @schememodname[scribble/decode], and otherwise provides - all of @schememodname[scheme/base]. See @secref["doclang"].} + through @racketmodname[scribble/decode], and otherwise provides + all of @racketmodname[racket/base]. See @secref["doclang"].} - @item{@schememodname[scribble/doc]: A language that combines - @schememodname[scribble/reader] with - @schememodname[scribble/doclang]. See @secref["docreader"].} + @item{@racketmodname[scribble/doc]: A language that combines + @racketmodname[scribble/reader] with + @racketmodname[scribble/doclang]. See @secref["docreader"].} - @item{@schememodname[scribble/base]: A library of basic document - operators---such as @scheme[title], @scheme[section], and - @scheme[secref]---for use with @schememodname[scribble/decode] + @item{@racketmodname[scribble/base]: A library of basic document + operators---such as @racket[title], @racket[section], and + @racket[secref]---for use with @racketmodname[scribble/decode] and a renderer. This library name also can be used as a - language, where it combines @schememodname[scribble/doc] with - the exports of @schememodname[scribble/base]. See + language, where it combines @racketmodname[scribble/doc] with + the exports of @racketmodname[scribble/base]. See @secref["base"].} - @item{@schememodname[scribble/scheme]: A library of functions for - typesetting Scheme code. See @secref["scheme"]. These functions + @item{@racketmodname[scribble/racket]: A library of functions for + typesetting Racket code. See @secref["scheme"]. These functions are not normally used directly, but instead used through - @schememodname[scribble/manual].} + @racketmodname[scribble/manual].} - @item{@schememodname[scribble/manual]: A library of functions for - writing PLT Scheme documentation; re-exports - @schememodname[scribble/base]. Also, the - @schememodname[scribble/manual-struct] library provides types + @item{@racketmodname[scribble/manual]: A library of functions for + writing Racket documentation; re-exports + @racketmodname[scribble/base]. Also, the + @racketmodname[scribble/manual-struct] library provides types for index-entry descriptions created by functions in - @schememodname[scribble/manual]. See @secref["manual"].} + @racketmodname[scribble/manual]. See @secref["manual"].} - @item{@schememodname[scribble/eval]: A library of functions for + @item{@racketmodname[scribble/eval]: A library of functions for evaluating code at document-build time, especially for showing examples. See @secref["eval"].} - @item{@schememodname[scribble/bnf]: A library of support functions + @item{@racketmodname[scribble/bnf]: A library of support functions for writing grammars. See @secref["bnf"].} - @item{@schememodname[scribble/xref]: A library of support functions + @item{@racketmodname[scribble/xref]: A library of support functions for using cross-reference information, typically after a document is rendered (e.g., to search). See @secref["xref"].} - @item{@schememodname[scribble/text]: A language that uses - @schememodname[scribble/reader] preprocessing text files.} + @item{@racketmodname[scribble/text]: A language that uses + @racketmodname[scribble/reader] preprocessing text files.} ] The @exec{scribble} command-line utility generates output with a specified renderer. More specifically, the executable installs a renderer, loads the modules specified on the command line, extracts -the @scheme[doc] export of each module (which must be an instance of -@scheme[part]), and renders each---potentially with links that span +the @racket[doc] export of each module (which must be an instance of +@racket[part]), and renders each---potentially with links that span documents. diff --git a/collects/scribblings/scribble/lp-ex-doc.scrbl b/collects/scribblings/scribble/lp-ex-doc.scrbl index 2d3bd6ae..c23d6e8e 100644 --- a/collects/scribblings/scribble/lp-ex-doc.scrbl +++ b/collects/scribblings/scribble/lp-ex-doc.scrbl @@ -1,4 +1,4 @@ #lang scribble/doc @(require scribble/lp-include) -@lp-include["lp-ex.ss"] +@lp-include["lp-ex.rkt"] diff --git a/collects/scribblings/scribble/lp-ex.ss b/collects/scribblings/scribble/lp-ex.rkt similarity index 100% rename from collects/scribblings/scribble/lp-ex.ss rename to collects/scribblings/scribble/lp-ex.rkt diff --git a/collects/scribblings/scribble/lp.scrbl b/collects/scribblings/scribble/lp.scrbl index 051aa335..a876995b 100644 --- a/collects/scribblings/scribble/lp.scrbl +++ b/collects/scribblings/scribble/lp.scrbl @@ -3,7 +3,7 @@ scribble/core scribble/html-properties scribble/latex-properties - scheme/runtime-path + racket/runtime-path (prefix-in lp-ex: "lp-ex-doc.scrbl") "utils.ss" (for-label scribble/lp-include scribble/lp)) @@ -14,19 +14,19 @@ (make-tex-addition "lp.tex"))) ]{Literate Programming} -Programs written using @schememodname[scribble/lp] are simultaneously +Programs written using @racketmodname[scribble/lp] are simultaneously two things: a program and a document describing the program. -Programs in @schememodname[scribble/lp] are viewed in two different +Programs in @racketmodname[scribble/lp] are viewed in two different ways, either by running the program directly or by including it with -@scheme[lp-include]. When running the program, all of the -@scheme[chunk] expressions are collected and stitched together into a +@racket[lp-include]. When running the program, all of the +@racket[chunk] expressions are collected and stitched together into a program, and the rest of the module is discarded. When using -@scheme[lp-include], the entire contents of the module are preserved +@racket[lp-include], the entire contents of the module are preserved and are treated like an ordinary Scribble document, where -@scheme[chunk]s are typeset in a manner similar to @scheme[codeblock]. +@racket[chunk]s are typeset in a manner similar to @racket[codeblock]. -@(define-runtime-path lp-ex "lp-ex.ss") +@(define-runtime-path lp-ex "lp-ex.rkt") For example, consider this program: @@ -44,31 +44,31 @@ For example, consider this program: [else (list* line "\n" (loop))]))))))) -When this file is @scheme[require]d in the normal manner, it defines a -function @scheme[f] that squares its argument, and the documentation -is ignored. When it is included with @scheme[lp-include], it looks +When this file is @racket[require]d in the normal manner, it defines a +function @racket[f] that squares its argument, and the documentation +is ignored. When it is included with @racket[lp-include], it looks like this: @(make-nested-flow (make-style "LPBoxed" null) (part-blocks lp-ex:doc)) -@section{@schememodname[scribble/lp] Language} +@section{@racketmodname[scribble/lp] Language} -@defmodulelang[scribble/lp]{The @schememodname[scribble/lp] language +@defmodulelang[scribble/lp]{The @racketmodname[scribble/lp] language provides core support for literate programming.} @defform[(chunk id form ...)]{ - Introduces a chunk, binding @scheme[id] for use in other - chunks. Normally, @scheme[id] starts with @litchar{<} and ends with + Introduces a chunk, binding @racket[id] for use in other + chunks. Normally, @racket[id] starts with @litchar{<} and ends with @litchar{>}. When running a scribble program only the code inside the chunks is run; the rest is ignored. - If @scheme[id] is @schemeidfont{<*>}, then this chunk is - used as the main chunk in the file. If @schemeidfont{<*>} + If @racket[id] is @racketidfont{<*>}, then this chunk is + used as the main chunk in the file. If @racketidfont{<*>} is never used, then the first chunk in the file is treated as the main chunk. If some chunk is not referenced from the main chunk (possibly indirectly via other chunks that @@ -77,15 +77,15 @@ provides core support for literate programming.} } -@section{@schememodname[scribble/lp-include] Module} +@section{@racketmodname[scribble/lp-include] Module} @defmodule[scribble/lp-include]{The -@schememodname[scribble/lp-include] library is normally used within a +@racketmodname[scribble/lp-include] library is normally used within a Scribble document---that is, a module that starts with something like -@scheme[#, @hash-lang[] scribble/base] or @scheme[#, @hash-lang[] -scribble/manual], instead of @scheme[#, @hash-lang[] scheme].} +@racket[#, @hash-lang[] scribble/base] or @racket[#, @hash-lang[] +scribble/manual], instead of @racket[#, @hash-lang[] racket].} @defform[(lp-include filename)]{ -Includes the source of @scheme[filename] as the typeset version of the literate +Includes the source of @racket[filename] as the typeset version of the literate program. } diff --git a/collects/scribblings/scribble/manual-stub.scrbl b/collects/scribblings/scribble/manual-stub.scrbl index 68cbb8b1..b373d528 100644 --- a/collects/scribblings/scribble/manual-stub.scrbl +++ b/collects/scribblings/scribble/manual-stub.scrbl @@ -2,7 +2,7 @@ @(require "utils.ss" (for-label scribble/sigplan)) -@title{PLT Scheme Manual Format} +@title{Racket Manual Format} The @schememodname[scribble/manual] language is a major component of Scribble, and it is documented in its own chapter: diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index a62f9b34..773fd9f7 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -1,248 +1,285 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label scribble/manual-struct)) -@(define lit-ellipses (scheme ...)) -@(define lit-ellipses+ (scheme ...+)) +@(define lit-ellipses (racket ...)) +@(define lit-ellipses+ (racket ...+)) @title[#:tag "manual" #:style 'toc]{Manual Forms} -@defmodulelang[scribble/manual]{The @schememodname[scribble/manual] -language provides all of @schememodname[scribble/base] plus many -additional functions that are specific to writing PLT Scheme +@defmodulelang[scribble/manual]{The @racketmodname[scribble/manual] +language provides all of @racketmodname[scribble/base] plus many +additional functions that are specific to writing Racket documentation. -The @schememodname[scribble/manual] name can also be used as a library -with @scheme[require], in which case it provides all of the same +The @racketmodname[scribble/manual] name can also be used as a library +with @racket[require], in which case it provides all of the same bindings, but without setting the reader or setting the default -rendering format to the PLT Scheme manual format.} +rendering format to the Racket manual format.} -With @hash-lang[], @schememodname[scribble/manual] associates a -@scheme[latex-defaults] @tech{style property} with its @scheme[doc] -export to select the default PLT Scheme manual style for Latex -rendering---unless a style is supplied to @scheme[title] that already -includes a @scheme[latex-defaults] @tech{style property}. +With @hash-lang[], @racketmodname[scribble/manual] associates a +@racket[latex-defaults] @tech{style property} with its @racket[doc] +export to select the default Racket manual style for Latex +rendering---unless a style is supplied to @racket[title] that already +includes a @racket[latex-defaults] @tech{style property}. @local-table-of-contents[] @; ------------------------------------------------------------------------ @section[#:tag "scribble:manual:code"]{Typesetting Code} -@defform[(schemeblock datum ...)]{ +@defform[(racketblock datum ...)]{ -Typesets the @scheme[datum] sequence as a table of Scheme code inset -by two spaces. The source locations of the @scheme[datum]s determine +Typesets the @racket[datum] sequence as a table of Racket code inset +by two spaces. The source locations of the @racket[datum]s determine the generated layout. For example, -@schemeblock[ -(schemeblock +@racketblock[ +(racketblock (define (loop x) (loop (not x)))) ] produces the output -@schemeblock[ +@racketblock[ (define (loop x) (loop (not x))) ] -with the @scheme[(loop (not x))] indented under @scheme[define], -because that's the way it is idented the use of @scheme[schemeblock]. +with the @racket[(loop (not x))] indented under @racket[define], +because that's the way it is idented the use of @racket[racketblock]. -Furthermore, @scheme[define] is typeset as a keyword (bold and black) -and as a hyperlink to @scheme[define]'s definition in the reference +Furthermore, @racket[define] is typeset as a keyword (bold and black) +and as a hyperlink to @racket[define]'s definition in the reference manual, because this document was built using a for-label binding of -@scheme[define] (in the source) that matches a definition in the -reference manual. Similarly, @scheme[not] is a hyperlink to the its +@racket[define] (in the source) that matches a definition in the +reference manual. Similarly, @racket[not] is a hyperlink to the its definition in the reference manual. -Use @scheme[unsyntax] to escape back to an expression that produces an -@scheme[element]. For example, +Use @racket[unsyntax] to escape back to an expression that produces an +@racket[element]. For example, @let[([unsyntax #f]) -(schemeblock - (schemeblock - (+ 1 (unsyntax (elem (scheme x) (subscript "2")))))) +(racketblock + (racketblock + (+ 1 (unsyntax (elem (racket x) (subscript "2")))))) ] produces -@schemeblock[ -(+ 1 (unsyntax (elem (scheme x) (subscript "2")))) +@racketblock[ +(+ 1 (unsyntax (elem (racket x) (subscript "2")))) ] -The @scheme[unsyntax] form is regonized via -@scheme[free-identifier=?], so if you want to typeset code that -includes @scheme[unsyntax], you can simply hide the usual binding: +The @racket[unsyntax] form is regonized via +@racket[free-identifier=?], so if you want to typeset code that +includes @racket[unsyntax], you can simply hide the usual binding: -@SCHEMEBLOCK[ -(schemeblock - (let ([(UNSYNTAX (scheme unsyntax)) #f]) - (schemeblock +@RACKETBLOCK[ +(racketblock + (let ([(UNSYNTAX (racket unsyntax)) #f]) + (racketblock (syntax (+ 1 (unsyntax x)))))) ] -Or use @scheme[SCHEMEBLOCK], whose escape form is @scheme[UNSYNTAX] -instead of @scheme[unsyntax]. +Or use @racket[RACKETBLOCK], whose escape form is @racket[UNSYNTAX] +instead of @racket[unsyntax]. A few other escapes are recognized symbolically: @itemize[ - @item{@scheme[(#,(scheme code:line) _datum ...)] typesets as the - sequence of @scheme[_datum]s (i.e., without the - @scheme[code:line] wrapper).} + @item{@racket[(#,(indexed-racket code:line) _datum ...)] typesets as the + sequence of @racket[_datum]s (i.e., without the + @racket[code:line] wrapper).} - @item{@scheme[(#,(scheme code:comment) _datum)] typesets like - @scheme[_datum], but colored as a comment and prefixed with a - semi-colon. A typical @scheme[_datum] escapes from - Scheme-typesetting mode using @scheme[unsyntax] and - produces a paragraph using @scheme[t]: + @item{@racket[(#,(indexed-racket code:comment) _datum)] typesets like + @racket[_datum], but colored as a comment and prefixed with a + semi-colon. A typical @racket[_datum] escapes from + Racket-typesetting mode using @racket[unsyntax] and + produces a paragraph using @racket[t]: @verbatim[#:indent 2]|{ (code:comment @#,t{this is a comment}) }| (Note that @litchar|{@#,foo{...}}| reads as - @SCHEME[(unsyntax (foo "..."))].) + @RACKET[(unsyntax (foo "..."))].) } - @item{@schemeidfont{code:blank} typesets as a blank space.} + @item{@indexed-racket[code:blank] typesets as a blank space.} - @item{@schemeidfont{_}@scheme[_id] typesets as @scheme[id], but - colored as a variable (like @scheme[schemevarfont]); this - escape applies only if @schemeidfont{_}@scheme[_id] has no + @item{@racket[(#,(indexed-racket code:hilite) _datum)] typesets like + @racket[_datum], but with a background highlight.} + + @item{@racket[(#,(indexed-racket code:quote) _datum)] typesets like + @racket[(@#,racketidfont{quote} _datum)], but without rendering the + @racketidfont{quote} as @litchar{'}.} + + @item{@racketidfont{_}@racket[_id] typesets as @racket[id], but + colored as a variable (like @racket[racketvarfont]); this + escape applies only if @racketidfont{_}@racket[_id] has no for-label binding and is not specifically colored as a subform - non-terminal via @scheme[defform], a variable via - @scheme[defproc], etc.} + non-terminal via @racket[defform], a variable via + @racket[defproc], etc.} ] -See also @schememodname[scribble/comment-reader]. +See also @racketmodname[scribble/comment-reader]. } -@defform[(SCHEMEBLOCK datum ...)]{Like @scheme[schemeblock], but with -the expression escape @scheme[UNSYNTAX] instead of @scheme[unsyntax].} +@defform[(RACKETBLOCK datum ...)]{Like @racket[racketblock], but with +the expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].} -@defform[(schemeblock0 datum ...)]{Like @scheme[schemeblock], but +@defform[(racketblock0 datum ...)]{Like @racket[racketblock], but without insetting the code.} -@defform[(SCHEMEBLOCK0 datum ...)]{Like @scheme[SCHEMEBLOCK], but +@defform[(RACKETBLOCK0 datum ...)]{Like @racket[RACKETBLOCK], but without insetting the code.} -@defform[(schemeinput datum ...)]{Like @scheme[schemeblock], but the -@scheme[datum] are typeset after a prompt representing a REPL.} +@defform[(racketinput datum ...)]{Like @racket[racketblock], but the +@racket[datum] are typeset after a prompt representing a REPL.} -@defform[(schememod lang datum ...)]{Like @scheme[schemeblock], but -the @scheme[datum] are typeset inside a @schememodfont{#lang}-form -module whose language is @scheme[lang]. The source location of -@scheme[lang] (relative to the body @scheme[datum]s) determines the -relative positioning of the @schememodfont{#lang} line in the typeset +@defform[(racketmod lang datum ...)]{Like @racket[racketblock], but +the @racket[datum] are typeset inside a @racketmodfont{#lang}-form +module whose language is @racket[lang]. The source location of +@racket[lang] (relative to the body @racket[datum]s) determines the +relative positioning of the @racketmodfont{#lang} line in the typeset output.} -@defform[(scheme datum ...)]{Like @scheme[schemeblock], but typeset on +@defform[(racket datum ...)]{Like @racket[racketblock], but typeset on a single line and wrapped with its enclosing paragraph, independent of -the formatting of @scheme[datum].} +the formatting of @racket[datum].} -@defform[(SCHEME datum ...)]{Like @scheme[scheme], but with the -@scheme[UNSYNTAX] escape like @scheme[schemeblock].} +@defform[(RACKET datum ...)]{Like @racket[racket], but with the +@racket[UNSYNTAX] escape like @racket[racketblock].} -@defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset +@defform[(racketresult datum ...)]{Like @racket[racket], but typeset as a REPL value (i.e., a single color with no hyperlinks).} -@defform[(schemeid datum ...)]{Like @scheme[scheme], but typeset +@defform[(racketid datum ...)]{Like @racket[racket], but typeset as an unbound identifier (i.e., no coloring or hyperlinks).} -@defform*[((schememodname datum) - (schememodname ((unsyntax (scheme unsyntax)) expr)))]{ -Like @scheme[scheme], but typeset as a module path. If @scheme[datum] -is an identifier or @scheme[expr] produces a symbol, then it is +@defform*[((racketmodname datum) + (racketmodname ((unsyntax (racket unsyntax)) expr)))]{ +Like @racket[racket], but typeset as a module path. If @racket[datum] +is an identifier or @racket[expr] produces a symbol, then it is hyperlinked to the module path's definition as created by -@scheme[defmodule].} +@racket[defmodule].} -@defform[(schememodlink datum pre-content-expr ...)]{ -Like @scheme[schememod], but separating the module path to link -from the content to be linked. The @scheme[datum] module path is always +@defform[(racketmodlink datum pre-content-expr ...)]{ +Like @racket[racketmod], but separating the module path to link +from the content to be linked. The @racket[datum] module path is always linked, even if it is not an identifier.} -@defproc[(litchar [str string?] ...) element?]{Typesets @scheme[str]s as a +@defproc[(litchar [str string?] ...) element?]{Typesets @racket[str]s as a representation of literal text. Use this when you have to talk about the individual characters in a stream of text, as as when documenting a reader extension.} -@defproc[(schemefont [pre-content pre-content?] ...) element?]{Typesets -@tech{decode}d @scheme[pre-content] as uncolored, unhyperlinked -Scheme. This procedure is useful for typesetting things like -@schemefont{#lang}, which are not @scheme[read]able by themselves.} +@defproc[(racketfont [pre-content pre-content?] ...) element?]{Typesets +@tech{decode}d @racket[pre-content] as uncolored, unhyperlinked +Racket. This procedure is useful for typesetting things like +@racketfont{#lang}, which are not @racket[read]able by themselves.} -@defproc[(schemevalfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a value.} +@defproc[(racketvalfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a value.} -@defproc[(schemeresultfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a REPL result.} +@defproc[(racketresultfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a REPL result.} -@defproc[(schemeidfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as an identifier.} +@defproc[(racketidfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as an identifier.} -@defproc[(schemevarfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a variable (i.e., an argument or +@defproc[(racketvarfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a variable (i.e., an argument or sub-form in a procedure being documented).} -@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as a syntactic form name.} +@defproc[(racketkeywordfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as a syntactic form name.} -@defproc[(schemeparenfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored like parentheses.} +@defproc[(racketparenfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored like parentheses.} -@defproc[(schememetafont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as meta-syntax, such as backquote or +@defproc[(racketmetafont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as meta-syntax, such as backquote or unquote.} -@defproc[(schemeerror [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as error-message text.} +@defproc[(racketerror [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as error-message text.} -@defproc[(schememodfont [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as module name.} +@defproc[(racketmodfont [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as module name.} -@defproc[(schemeoutput [pre-content pre-content?] ...) element?]{Like -@scheme[schemefont], but colored as output.} +@defproc[(racketoutput [pre-content pre-content?] ...) element?]{Like +@racket[racketfont], but colored as output.} @defproc[(procedure [pre-content pre-content?] ...) element?]{Typesets -@tech{decode}d @scheme[pre-content] as a procedure name in a REPL +@tech{decode}d @racket[pre-content] as a procedure name in a REPL result (e.g., in typewriter font with a @litchar{#} suffix.).} -@defform[(var datum)]{Typesets @scheme[datum] as an identifier that is +@defform[(var datum)]{Typesets @racket[datum] as an identifier that is an argument or sub-form in a procedure being documented. Normally, the -@scheme[defproc] and @scheme[defform] arrange for @scheme[scheme] to +@racket[defproc] and @racket[defform] arrange for @racket[racket] to format such identifiers automatically in the description of the -procedure, but use @scheme[var] if that cannot work for some reason.} +procedure, but use @racket[var] if that cannot work for some reason.} -@defform[(svar datum)]{Like @scheme[var], but for subform non-terminals +@defform[(svar datum)]{Like @racket[var], but for subform non-terminals in a form definition.} +@deftogether[( +@defform[(schemeblock datum ...)] +@defform[(SCHEMEBLOCK datum ...)] +@defform[(schemeblock0 datum ...)] +@defform[(SCHEMEBLOCK0 datum ...)] +@defform[(schemeinput datum ...)] +@defform[(schememod lang datum ...)] +@defform[(scheme datum ...)] +@defform[(SCHEME datum ...)] +@defform[(schemeresult datum ...)] +@defform[(schemeid datum ...)] +@defform*[((schememodname datum) + (schememodname ((unsyntax (scheme unsyntax)) expr)))] +@defform[(schememodlink datum pre-content-expr ...)] +@defproc[(schemefont [pre-content pre-content?] ...) element?] +@defproc[(schemevalfont [pre-content pre-content?] ...) element?] +@defproc[(schemeresultfont [pre-content pre-content?] ...) element?] +@defproc[(schemeidfont [pre-content pre-content?] ...) element?] +@defproc[(schemevarfont [pre-content pre-content?] ...) element?] +@defproc[(schemekeywordfont [pre-content pre-content?] ...) element?] +@defproc[(schemeparenfont [pre-content pre-content?] ...) element?] +@defproc[(schememetafont [pre-content pre-content?] ...) element?] +@defproc[(schemeerror [pre-content pre-content?] ...) element?] +@defproc[(schememodfont [pre-content pre-content?] ...) element?] +@defproc[(schemeoutput [pre-content pre-content?] ...) element?] +)]{ + +Compatibility aliases. Each @racketidfont{scheme...} name is an alias for the +corresponding @racketidfont{racket...} binding.} + @; ------------------------------------------------------------------------ @subsection{Typesetting Comments} @defmodulereader[scribble/comment-reader] -As a reader module, @schememodname[scribble/comment-reader] reads a +As a reader module, @racketmodname[scribble/comment-reader] reads a single S-expression that contains @litchar{;}-based comment lines, and -it wraps the comments with @scheme[code:comment] for use with forms -like @scheme[schemeblock]. More precisely, -@schememodname[scribble/comment-reader] extends the current reader to +it wraps the comments with @racket[code:comment] for use with forms +like @racket[racketblock]. More precisely, +@racketmodname[scribble/comment-reader] extends the current reader to adjust the parsing of @litchar{;}. For example, within a Scribble document that imports -@schememodname[scribble/manual], +@racketmodname[scribble/manual], @verbatim[#:indent 2]|{ @#reader scribble/comment-reader - (schemeblock + (racketblock ;; This is not a pipe (make-pipe) ) @@ -251,19 +288,19 @@ For example, within a Scribble document that imports generates @#reader scribble/comment-reader - (schemeblock + (racketblock ;; This is not a pipe (make-pipe) ) The initial @litchar["@"] is needed above to shift into S-expression -mode, so that @schememetafont{#reader} is recognized as a reader +mode, so that @racketmetafont{#reader} is recognized as a reader declaration instead of literal text. Also, the example uses -@scheme[(schemeblock ....)] instead of -@schememetafont["@"]@scheme[schemeblock]@schememetafont["["]@scheme[....]@schememetafont["]"] +@racket[(racketblock ....)] instead of +@racketmetafont["@"]@racket[racketblock]@racketmetafont["["]@racket[....]@racketmetafont["]"] because the @"@"-reader would drop comments within the -@scheme[schemeblock] before giving -@schememodname[scribble/comment-reader] a chance to convert them. +@racket[racketblock] before giving +@racketmodname[scribble/comment-reader] a chance to convert them. @; ------------------------------------------------------------------------ @section[#:tag "doc-modules"]{Documenting Modules} @@ -274,41 +311,41 @@ because the @"@"-reader would drop comments within the [maybe-sources code:blank (code:line #:use-sources (mod-path ...))])]{ -Produces a sequence of flow elements (encaptured in a @scheme[splice]) -to start the documentation for a module that can be @scheme[require]d -using the path @scheme[id]. The @tech{decode}d @scheme[pre-flow]s +Produces a sequence of flow elements (encaptured in a @racket[splice]) +to start the documentation for a module that can be @racket[require]d +using the path @racket[id]. The @tech{decode}d @racket[pre-flow]s introduce the module, but need not include all of the module content. Besides generating text, this form expands to a use of -@scheme[declare-exporting] with @scheme[id]; the -@scheme[#:use-sources] clause, if provided, is propagated to -@scheme[declare-exporting]. Consequently, @scheme[defmodule] should be +@racket[declare-exporting] with @racket[id]; the +@racket[#:use-sources] clause, if provided, is propagated to +@racket[declare-exporting]. Consequently, @racket[defmodule] should be used at most once in a section, though it can be shadowed with -@scheme[defmodule]s in sub-sections. +@racket[defmodule]s in sub-sections. -If a @scheme[#:require-form] clause is provided, the given expression -produces an element to use instead of @scheme[(scheme require)] for +If a @racket[#:require-form] clause is provided, the given expression +produces an element to use instead of @racket[(racket require)] for the declaration of the module. This is useful to suggest a different -way of accessing the module instead of through @scheme[require]. +way of accessing the module instead of through @racket[require]. -Hyperlinks created by @scheme[schememodname] are associated with the -enclosing section, rather than the local @scheme[id] text.} +Hyperlinks created by @racket[racketmodname] are associated with the +enclosing section, rather than the local @racket[id] text.} @defform*[[(defmodulelang id maybe-sources pre-flow ...) (defmodulelang content-expr #:module-paths (mod-path ...) maybe-sources pre-flow ...)]]{ -Like @scheme[defmodule], but documents @scheme[id] as a module path -suitable for use by either @scheme[require] or @hash-lang[]. If the -module path for @scheme[require] is syntactically different from the -@hash-lang[] form, use the @scheme[#:module-paths] to provide them +Like @racket[defmodule], but documents @racket[id] as a module path +suitable for use by either @racket[require] or @hash-lang[]. If the +module path for @racket[require] is syntactically different from the +@hash-lang[] form, use the @racket[#:module-paths] to provide them separately.} @defform[(defmodulereader id maybe-sources pre-flow ...)]{ -Like @scheme[defmodule], but documents @scheme[id] as a module path -suitable for use with @schememetafont{#reader}.} +Like @racket[defmodule], but documents @racket[id] as a module path +suitable for use with @racketmetafont{#reader}.} @deftogether[( @@ -319,7 +356,7 @@ suitable for use with @schememetafont{#reader}.} @defform[(defmodulereader* (id ...+) maybe-sources pre-flow ...)] )]{ -Like @scheme[defmodule], etc., but introduces multiple module paths instead +Like @racket[defmodule], etc., but introduces multiple module paths instead of just one.} @deftogether[( @@ -330,54 +367,54 @@ of just one.} @defform[(defmodulereader*/no-declare (id ...) pre-flow ...)] )]{ -Like @scheme[defmodule*], etc., but without expanding to -@scheme[declare-exporting]. Use this form when you want to provide a +Like @racket[defmodule*], etc., but without expanding to +@racket[declare-exporting]. Use this form when you want to provide a more specific list of modules (e.g., to name both a specific module and one that combines several modules) via your own -@scheme[declare-exporting] declaration.} +@racket[declare-exporting] declaration.} @defform/subs[(declare-exporting mod-path ... maybe-sources) ([maybe-sources code:blank (code:line #:use-sources (mod-path ...))])]{ -Associates the @scheme[mod-path]s to all bindings defined within the +Associates the @racket[mod-path]s to all bindings defined within the enclosing section, except as overridden by other -@scheme[declare-exporting] declarations in nested sub-sections. The -list of @scheme[mod-path]s is shown, for example, when the user hovers +@racket[declare-exporting] declarations in nested sub-sections. The +list of @racket[mod-path]s is shown, for example, when the user hovers the mouse over one of the bindings defined within the section. -More significantly, the first @scheme[mod-path] plus the -@scheme[#:use-sources] @scheme[mod-path]s determine the binding that -is documented by each @scheme[defform], @scheme[defproc], or similar -form within the section that contains the @scheme[declare-exporting] +More significantly, the first @racket[mod-path] plus the +@racket[#:use-sources] @racket[mod-path]s determine the binding that +is documented by each @racket[defform], @racket[defproc], or similar +form within the section that contains the @racket[declare-exporting] declaration: @itemize[ - @item{If no @scheme[#:use-sources] clause is supplied, then the + @item{If no @racket[#:use-sources] clause is supplied, then the documentation applies to the given name as exported by the first - @scheme[mod-path].} + @racket[mod-path].} - @item{If @scheme[#:use-sources] @scheme[mod-path]s are supplied, then + @item{If @racket[#:use-sources] @racket[mod-path]s are supplied, then they are tried in order. The first one to provide an export with the same symbolic name and - @scheme[free-label-identifier=?] to the given name is used as + @racket[free-label-identifier=?] to the given name is used as the documented binding. This binding is assumed to be the same - as the identifier as exported by the first @scheme[mod-path] in - the @scheme[declare-exporting] declaration.} + as the identifier as exported by the first @racket[mod-path] in + the @racket[declare-exporting] declaration.} ] -The initial @scheme[mod-path]s sequence can be empty if -@scheme[mod-path]s are given with @scheme[#:use-sources]. In that +The initial @racket[mod-path]s sequence can be empty if +@racket[mod-path]s are given with @racket[#:use-sources]. In that case, the rendered documentation never reports an exporting module for identifiers that are documented within the section, but the -@scheme[mod-path]s in @scheme[#:use-sources] provide a binding context +@racket[mod-path]s in @racket[#:use-sources] provide a binding context for connecting (via hyperlinks) definitions and uses of identifiers. -The @scheme[declare-exporting] form should be used no more than once +The @racket[declare-exporting] form should be used no more than once per section, since the declaration applies to the entire section, -although overriding @scheme[declare-exporting] forms can appear in +although overriding @racket[declare-exporting] forms can appear in sub-sections.} @; ------------------------------------------------------------------------ @@ -398,25 +435,25 @@ sub-sections.} [ellipses+ @#,lit-ellipses+])]{ Produces a sequence of flow elements (encapsulated in a -@scheme[splice]) to document a procedure named @scheme[id]. Nesting -@scheme[prototype]s corresponds to a curried function, as in -@scheme[define]. The @scheme[id] is indexed, and it also registered so -that @scheme[scheme]-typeset uses of the identifier (with the same +@racket[splice]) to document a procedure named @racket[id]. Nesting +@racket[prototype]s corresponds to a curried function, as in +@racket[define]. The @racket[id] is indexed, and it also registered so +that @racket[racket]-typeset uses of the identifier (with the same for-label binding) are hyperlinked to this documentation. -A @scheme[defmodule] or @scheme[declare-exporting] form (or one of the -variants) in an enclosing section determines the @scheme[id] binding -that is being defined. The @scheme[id] should also have a for-label -binding (as introduced by @scheme[(require (for-label ....))]) that -matches the definition binding; otherwise, the defined @scheme[id] +A @racket[defmodule] or @racket[declare-exporting] form (or one of the +variants) in an enclosing section determines the @racket[id] binding +that is being defined. The @racket[id] should also have a for-label +binding (as introduced by @racket[(require (for-label ....))]) that +matches the definition binding; otherwise, the defined @racket[id] will not typeset correctly within the definition. -Each @scheme[arg-spec] must have one of the following forms: +Each @racket[arg-spec] must have one of the following forms: @specsubform[(arg-id contract-expr-datum)]{ An argument whose contract is specified by - @scheme[contract-expr-datum] which is typeset via - @scheme[schemeblock0].} + @racket[contract-expr-datum] which is typeset via + @racket[racketblock0].} @specsubform[(arg-id contract-expr-datum default-expr)]{ Like the previous case, but with a default value. All arguments @@ -433,21 +470,21 @@ Each @scheme[arg-spec] must have one of the following forms: @specsubform[@#,lit-ellipses]{Any number of the preceding argument. This form is normally used at the end, but keyword-based arguments can sensibly appear afterward. See also the documentation for - @scheme[append] for a use of @lit-ellipses before the last + @racket[append] for a use of @lit-ellipses before the last argument.} @specsubform[@#,lit-ellipses+]{One or more of the preceding argument (normally at the end, like @lit-ellipses).} -The @scheme[result-contract-expr-datum] is typeset via -@scheme[schemeblock0], and it represents a contract on the procedure's +The @racket[result-contract-expr-datum] is typeset via +@racket[racketblock0], and it represents a contract on the procedure's result. -The @tech{decode}d @scheme[pre-flow] documents the procedure. In this -description, references to @svar[arg-id]s using @scheme[scheme], -@scheme[schemeblock], @|etc| are typeset as procedure arguments. +The @tech{decode}d @racket[pre-flow] documents the procedure. In this +description, references to @svar[arg-id]s using @racket[racket], +@racket[racketblock], @|etc| are typeset as procedure arguments. -The typesetting of all information before the @scheme[pre-flow]s +The typesetting of all information before the @racket[pre-flow]s ignores the source layout, except that the local formatting is preserved for contracts and default-values expressions.} @@ -456,13 +493,13 @@ preserved for contracts and default-values expressions.} result-contract-expr-datum] ...) pre-flow ...)]{ -Like @scheme[defproc], but for multiple cases with the same -@scheme[id]. +Like @racket[defproc], but for multiple cases with the same +@racket[id]. -When an @scheme[id] has multiple calling cases, they must be defined -with a single @scheme[defproc*], so that a single definition point -exists for the @scheme[id]. However, multiple distinct @scheme[id]s -can also be defined by a single @scheme[defproc*], for the case that +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.} @@ -477,92 +514,99 @@ it's best to document a related group of procedures at once.} ...))])]{ Produces a sequence of flow elements (encapsulated in a -@scheme[splice]) to document a syntatic form named by @scheme[id] -whose syntax is described by @scheme[form-datum]. If no @scheme[#:id] is used -to specify @scheme[id], then @scheme[form-datum] must have the form -@scheme[(id . _datum)]. +@racket[splice]) to document a syntatic form named by @racket[id] +whose syntax is described by @racket[form-datum]. If no @racket[#:id] is used +to specify @racket[id], then @racket[form-datum] must have the form +@racket[(id . _datum)]. -The @scheme[id] is indexed, and it is also registered so that -@scheme[scheme]-typeset uses of the identifier (with the same +The @racket[id] is indexed, and it is also registered so that +@racket[racket]-typeset uses of the identifier (with the same for-label binding) are hyperlinked to this documentation. -The @scheme[defmodule] or @scheme[declare-exporting] requirements, as -well as the binding requirements for @scheme[id], are the same as for -@scheme[defproc]. +The @racket[defmodule] or @racket[declare-exporting] requirements, as +well as the binding requirements for @racket[id], are the same as for +@racket[defproc]. -The @tech{decode}d @scheme[pre-flow] documents the form. In this -description, a reference to any identifier in @scheme[form-datum] via -@scheme[scheme], @scheme[schemeblock], @|etc| is typeset as a sub-form -non-terminal. If @scheme[#:literals] clause is provided, however, -instances of the @scheme[literal-id]s are typeset normally (i.e., as +The @tech{decode}d @racket[pre-flow] documents the form. In this +description, a reference to any identifier in @racket[form-datum] via +@racket[racket], @racket[racketblock], @|etc| is typeset as a sub-form +non-terminal. If @racket[#:literals] clause is provided, however, +instances of the @racket[literal-id]s are typeset normally (i.e., as determined by the enclosing context). -If a @scheme[#:contracts] clause is provided, each -@scheme[subform-datum] (typically an identifier that serves as a -meta-variable in @scheme[form-datum]) is shown as producing a value -that must satisfy the contract described by @scheme[contract-expr-datum]. +If a @racket[#:contracts] clause is provided, each +@racket[subform-datum] (typically an identifier that serves as a +meta-variable in @racket[form-datum]) is shown as producing a value +that must satisfy the contract described by @racket[contract-expr-datum]. -The typesetting of @scheme[form-datum], @scheme[subform-datum], and -@scheme[contract-expr-datum] preserves the source layout, like -@scheme[schemeblock].} +The typesetting of @racket[form-datum], @racket[subform-datum], and +@racket[contract-expr-datum] preserves the source layout, like +@racket[racketblock].} @defform[(defform* maybe-id maybe-literals [form-datum ...+] maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but for multiple forms using the same -@scheme[_id].} +Like @racket[defform], but for multiple forms using the same +@racket[_id].} @defform[(defform/subs maybe-id maybe-literals form-datum ([nonterm-id clause-datum ...+] ...) maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but including an auxiliary grammar of -non-terminals shown with the @scheme[_id] form. Each -@scheme[nonterm-id] is specified as being any of the corresponding -@scheme[clause-datum]s, where the formatting of each -@scheme[clause-datum] is preserved.} +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.} @defform[(defform*/subs maybe-id maybe-literals [form-datum ...] maybe-contracts pre-flow ...)]{ -Like @scheme[defform/subs], but for multiple forms for @scheme[_id].} +Like @racket[defform/subs], but for multiple forms for @racket[_id].} @defform[(defform/none maybe-literal form-datum maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but without registering a definition.} +Like @racket[defform], but without registering a definition.} @defform[(defidform id pre-flow ...)]{ -Like @scheme[defform], but with a plain @scheme[id] as the form.} +Like @racket[defform], but with a plain @racket[id] as the form.} + + +@defform[(defidform/inline id)]{ + +Like @racket[defidform], but @racket[id] is typeset as an inline +element. Use this form sparingly, because the typeset form does not +stand out to the reader as a specification of @racket[id].} @defform[(specform maybe-literals datum maybe-contracts pre-flow ...)]{ -Like @scheme[defform], but without indexing or registering a +Like @racket[defform], but without indexing or registering a definition, and with indenting on the left for both the specification -and the @scheme[pre-flow]s.} +and the @racket[pre-flow]s.} @defform[(specsubform maybe-literals datum maybe-contracts pre-flow ...)]{ -Similar to @scheme[defform], but without any specific identifier being +Similar to @racket[defform], but without any specific identifier being defined, and the table and flow are typeset indented. This form is intended for use when refining the syntax of a non-terminal used in a -@scheme[defform] or other @scheme[specsubform]. For example, it is -used in the documentation for @scheme[defproc] in the itemization of +@racket[defform] or other @racket[specsubform]. For example, it is +used in the documentation for @racket[defproc] in the itemization of possible shapes for @svar[arg-spec]. -The @scheme[pre-flow]s list is parsed as a flow that documents the +The @racket[pre-flow]s list is parsed as a flow that documents the procedure. In this description, a reference to any identifier in -@scheme[datum] is typeset as a sub-form non-terminal.} +@racket[datum] is typeset as a sub-form non-terminal.} @defform[(specsubform/subs maybe-literals datum @@ -570,16 +614,16 @@ procedure. In this description, a reference to any identifier in maybe-contracts pre-flow ...)]{ -Like @scheme[specsubform], but with a grammar like -@scheme[defform/subs].} +Like @racket[specsubform], but with a grammar like +@racket[defform/subs].} @defform[(specspecsubform maybe-literals datum maybe-contracts pre-flow ...)]{ -Like @scheme[specsubform], but indented an extra level. Since using -@scheme[specsubform] within the body of @scheme[specsubform] already -nests indentation, @scheme[specspecsubform] is for extra indentation +Like @racket[specsubform], but indented an extra level. Since using +@racket[specsubform] within the body of @racket[specsubform] already +nests indentation, @racket[specspecsubform] is for extra indentation without nesting a description.} @@ -588,66 +632,75 @@ without nesting a description.} maybe-contracts pre-flow ...)]{ -Like @scheme[specspecsubform], but with a grammar like -@scheme[defform/subs].} +Like @racket[specspecsubform], but with a grammar like +@racket[defform/subs].} @defform[(defparam id arg-id contract-expr-datum pre-flow ...)]{ -Like @scheme[defproc], but for a parameter. The -@scheme[contract-expr-datum] serves as both the result contract on the +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 -@scheme[arg-id] refers to the parameter argument in the latter case.} +@racket[arg-id] refers to the parameter argument in the latter case.} @defform[(defboolparam id arg-id pre-flow ...)]{ -Like @scheme[defparam], but the contract on a parameter argument is -@scheme[any/c], and the contract on the parameter result is -@scheme[boolean?].} +Like @racket[defparam], but the contract on a parameter argument is +@racket[any/c], and the contract on the parameter result is +@racket[boolean?].} @defform[(defthing id contract-expr-datum pre-flow ...)]{ -Like @scheme[defproc], but for a non-procedure binding.} +Like @racket[defproc], but for a non-procedure binding.} +@deftogether[( +@defform[ (defstruct* struct-name ([field-name contract-expr-datum] ...) + maybe-mutable maybe-non-opaque maybe-constructor + pre-flow ...)] +@defform/subs[ (defstruct struct-name ([field-name contract-expr-datum] ...) + maybe-mutable maybe-non-opaque maybe-constructor + pre-flow ...) + ([struct-name id + (id super-id)] + [maybe-mutable code:blank + #:mutable] + [maybe-non-opaque code:blank + #:prefab + #:transparent] + [maybe-constructor code:blank + (code:line #:constructor-name constructor-id) + (code:line #:extra-constructor-name constructor-id)])] +)]{ -@defform/subs[(defstruct struct-name ([field-name contract-expr-datum] ...) - flag-keywords - pre-flow ...) - ([struct-name id - (id super-id)] - [flag-keywords code:blank - #:mutable - (code:line #:inspector #f) - (code:line #:mutable #:inspector #f)])]{ - -Similar to @scheme[defform] or @scheme[defproc], but for a structure -definition.} +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].} @defform[(deftogether [def-expr ...] pre-flow ...)]{ -Combines the definitions created by the @scheme[def-expr]s into a -single definition box. Each @scheme[def-expr] should produce a -definition point via @scheme[defproc], @scheme[defform], etc. Each -@scheme[def-expr] should have an empty @scheme[pre-flow]; the -@tech{decode}d @scheme[pre-flow] sequence for the @scheme[deftogether] +Combines the definitions created by the @racket[def-expr]s into a +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.} -@defform/subs[(schemegrammar maybe-literals id clause-datum ...+) +@defform/subs[(racketgrammar maybe-literals id clause-datum ...+) ([maybe-literals code:blank (code:line #:literals (literal-id ...))])]{ -Creates a table to define the grammar of @scheme[id]. Each identifier -mentioned in a @scheme[clause-datum] is typeset as a non-terminal, -except for the identifiers listed as @scheme[literal-id]s, which are -typeset as with @scheme[scheme].} +Creates a table to define the grammar of @racket[id]. Each identifier +mentioned in a @racket[clause-datum] is typeset as a non-terminal, +except for the identifiers listed as @racket[literal-id]s, which are +typeset as with @racket[racket].} -@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)]{ +@defform[(racketgrammar* maybe-literals [id clause-datum ...+] ...)]{ -Like @scheme[schemegrammar], but for typesetting multiple productions +Like @racket[racketgrammar], but for typesetting multiple productions at once, aligned around the @litchar{=} and @litchar{|}.} @defproc[(defidentifier [id identifier?] @@ -656,23 +709,31 @@ at once, aligned around the @litchar{=} and @litchar{|}.} [#:show-libs? show-libs? boolean? #t]) element?]{ -Typesets @scheme[id] as a Scheme identifier, and also establishes the +Typesets @racket[id] as a Racket identifier, and also establishes the identifier as the definition of a binding in the same way as -@scheme[defproc], @scheme[defform], etc. As always, the library that -provides the identifier must be declared via @scheme[defmodule] or -@scheme[declare-exporting] for an enclosing section. +@racket[defproc], @racket[defform], etc. As always, the library that +provides the identifier must be declared via @racket[defmodule] or +@racket[declare-exporting] for an enclosing section. -If @scheme[form?] is a true value, then the identifier is documented +If @racket[form?] is a true value, then the identifier is documented as a syntactic form, so that uses of the identifier (normally -including @scheme[id] itself) are typeset as a syntactic form. +including @racket[id] itself) are typeset as a syntactic form. -If @scheme[index?] is a true value, then the identifier is registered +If @racket[index?] is a true value, then the identifier is registered in the index. -If @scheme[show-libs?] is a true value, then the identifier's defining +If @racket[show-libs?] is a true value, then the identifier's defining module may be exposed in the typeset form (e.g., when viewing HTML and the mouse hovers over the identifier).} +@deftogether[( +@defform[(schemegrammar maybe-literals id clause-datum ...+)] +@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)] +)]{ + +Compatibility aliases for @racket[racketgrammar] and @racket[racketgrammar*].} + + @; ------------------------------------------------------------------------ @section[#:tag "doc-classes"]{Documenting Classes and Interfaces} @@ -680,75 +741,75 @@ the mouse hovers over the identifier).} ([super super-id (mixin-id super)])]{ -Creates documentation for a class @scheme[id] that is a subclass of -@scheme[super] and implements each interface @scheme[intf-id]. Each -identifier in @scheme[super] (except @scheme[object%]) and -@scheme[intf-id] must be documented somewhere via @scheme[defclass] or -@scheme[definterface]. +Creates documentation for a class @racket[id] that is a subclass of +@racket[super] and implements each interface @racket[intf-id]. Each +identifier in @racket[super] (except @racket[object%]) and +@racket[intf-id] must be documented somewhere via @racket[defclass] or +@racket[definterface]. -The decoding of the @scheme[pre-flow] sequence should start with +The decoding of the @racket[pre-flow] sequence should start with general documentation about the class, followed by constructor -definition (see @scheme[defconstructor]), and then field and method -definitions (see @scheme[defmethod]). In rendered form, the +definition (see @racket[defconstructor]), and then field and method +definitions (see @racket[defmethod]). In rendered form, the constructor and method specification are indented to visually group them under the class definition.} @defform[(defclass/title id super (intf-id ...) pre-flow ...)]{ -Like @scheme[defclass], also includes a @scheme[title] declaration -with the style @scheme['hidden]. In addition, the constructor and +Like @racket[defclass], also includes a @racket[title] declaration +with the style @racket['hidden]. In addition, the constructor and methods are not left-indented. This form is normally used to create a section to be rendered on its -own HTML. The @scheme['hidden] style is used because the definition +own HTML. The @racket['hidden] style is used because the definition box serves as a title.} @defform[(definterface id (intf-id ...) pre-flow ...)]{ -Like @scheme[defclass], but for an interfaces. Naturally, -@scheme[pre-flow] should not generate a constructor declaration.} +Like @racket[defclass], but for an interfaces. Naturally, +@racket[pre-flow] should not generate a constructor declaration.} @defform[(definterface/title id (intf-id ...) pre-flow ...)]{ -Like @scheme[definterface], but for single-page rendering as in -@scheme[defclass/title].} +Like @racket[definterface], but for single-page rendering as in +@racket[defclass/title].} @defform[(defmixin id (domain-id ...) (range-id ...) pre-flow ...)]{ -Like @scheme[defclass], but for a mixin. Any number of -@scheme[domain-id] classes and interfaces are specified for the +Like @racket[defclass], but for a mixin. Any number of +@racket[domain-id] classes and interfaces are specified for the mixin's input requires, and any number of result classes and (more -likely) interfaces are specified for the @scheme[range-id]. The -@scheme[domain-id]s supply inherited methods.} +likely) interfaces are specified for the @racket[range-id]. The +@racket[domain-id]s supply inherited methods.} @defform[(defmixin/title id (domain-id ...) (range-id ...) pre-flow ...)]{ -Like @scheme[defmixin], but for single-page rendering as in -@scheme[defclass/title].} +Like @racket[defmixin], but for single-page rendering as in +@racket[defclass/title].} @defform/subs[(defconstructor (arg-spec ...) pre-flow ...) ([arg-spec (arg-id contract-expr-datum) (arg-id contract-expr-datum default-expr)])]{ -Like @scheme[defproc], but for a constructor declaration in the body -of @scheme[defclass], so no return contract is specified. Also, the -@scheme[new]-style keyword for each @scheme[arg-spec] is implicit from -the @scheme[arg-id].} +Like @racket[defproc], but for a constructor declaration in the body +of @racket[defclass], so no return contract is specified. Also, the +@racket[new]-style keyword for each @racket[arg-spec] is implicit from +the @racket[arg-id].} @defform[(defconstructor/make (arg-spec ...) pre-flow ...)]{ -Like @scheme[defconstructor], but specifying by-position -initialization arguments (for use with @scheme[make-object]) instead -of by-name arguments (for use with @scheme[new]).} +Like @racket[defconstructor], but specifying by-position +initialization arguments (for use with @racket[make-object]) instead +of by-name arguments (for use with @racket[new]).} @defform[(defconstructor*/make [(arg-spec ...) ...] pre-flow ...)]{ -Like @scheme[defconstructor/make], but with multiple constructor -patterns analogous @scheme[defproc*].} +Like @racket[defconstructor/make], but with multiple constructor +patterns analogous @racket[defproc*].} @defform[(defconstructor/auto-super [(arg-spec ...) ...] pre-flow ...)]{ -Like @scheme[defconstructor], but the constructor is +Like @racket[defconstructor], but the constructor is annotated to indicate that additional initialization arguments are accepted and propagated to the superclass.} @@ -767,13 +828,13 @@ accepted and propagated to the superclass.} (code:line #:mode extend) (code:line #:mode extend-final)])]{ -Like @scheme[defproc], but for a method within a @scheme[defclass] or -@scheme[definterface] body. +Like @racket[defproc], but for a method within a @racket[defclass] or +@racket[definterface] body. -The @scheme[maybe-mode] specifies whether the method overrides a +The @racket[maybe-mode] specifies whether the method overrides a method from a superclass, and so on. (For these purposes, use -@scheme[#:mode override] when refining a method of an implemented -interface.) The @scheme[extend] mode is like @scheme[override], but +@racket[#:mode override] when refining a method of an implemented +interface.) The @racket[extend] mode is like @racket[override], but the description of the method should describe only extensions to the superclass implementation.} @@ -782,23 +843,23 @@ superclass implementation.} result-contract-expr-datum] ...) pre-flow ...)]{ -Like @scheme[defproc*], but for a method within a @scheme[defclass] or -@scheme[definterface] body. The @scheme[maybe-mode] specification is as in -@scheme[defmethod].} +Like @racket[defproc*], but for a method within a @racket[defclass] or +@racket[definterface] body. The @racket[maybe-mode] specification is as in +@racket[defmethod].} @defform[(method class/intf-id method-id)]{ -Creates a hyperlink to the method named by @scheme[method-id] in the -class or interface named by @scheme[class/intf-id]. The hyperlink -names the method, only; see also @scheme[xmethod]. +Creates a hyperlink to the method named by @racket[method-id] in the +class or interface named by @racket[class/intf-id]. The hyperlink +names the method, only; see also @racket[xmethod]. -For-label binding information is used with @scheme[class/intf-id], but -not @scheme[method-id].} +For-label binding information is used with @racket[class/intf-id], but +not @racket[method-id].} @defform[(xmethod class/intf-id method-id)]{ -Like @scheme[method], but the hyperlink shows both the method name and +Like @racket[method], but the hyperlink shows both the method name and the containing class/interface.} @; ------------------------------------------------------------------------ @@ -806,78 +867,78 @@ the containing class/interface.} @defform[(defsignature id (super-id ...) pre-flow ...)]{ -Defines a signature @scheme[id] that extends the @scheme[super-id] +Defines a signature @racket[id] that extends the @racket[super-id] signatures. Any elements defined in @tech{decode}d -@scheme[pre-flow]s---including forms, procedures, structure types, +@racket[pre-flow]s---including forms, procedures, structure types, classes, interfaces, and mixins---are defined as members of the signature instead of direct bindings. These definitions can be -referenced through @scheme[sigelem] instead of @scheme[scheme]. +referenced through @racket[sigelem] instead of @racket[racket]. -The @tech{decode}d @scheme[pre-flow]s inset under the signature +The @tech{decode}d @racket[pre-flow]s inset under the signature declaration in the typeset output, so no new sections, @|etc| can be started.} @defform[(defsignature/splice id (super-id ...) pre-flow ...)]{ -Like @scheme[defsignature], but the @tech{decode}d @scheme[pre-flow]s +Like @racket[defsignature], but the @tech{decode}d @racket[pre-flow]s are not typeset under the signature declaration, and new sections, -@|etc| can be started in the @scheme[pre-flow]s.} +@|etc| can be started in the @racket[pre-flow]s.} @defproc[(signature-desc [pre-flow pre-flow?] ...) any/c]{ -Produces an opaque value that @scheme[defsignature] recognizes to +Produces an opaque value that @racket[defsignature] recognizes to outdent in the typeset form. This is useful for text describing the signature as a whole to appear right after the signature declaration.} @defform[(sigelem sig-id id)]{ -Typesets the identifier @scheme[id] with a hyperlink to its definition -as a member of the signature named by @scheme[sig-id].} +Typesets the identifier @racket[id] with a hyperlink to its definition +as a member of the signature named by @racket[sig-id].} @; ------------------------------------------------------------------------ @section[#:tag "doc-strings"]{Various String Forms} @defproc[(aux-elem [pre-content pre-content?] ...) element?]{ -Like @scheme[elem], but adds an @scheme['aux] @tech{style property}.} +Like @racket[elem], but adds an @racket['aux] @tech{style property}.} @defproc[(defterm [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a defined term (e.g., in -italic). Consider using @scheme[deftech] instead, though, so that uses -of @scheme[tech] can hyper-link to the definition.} +@tech{decode}d @racket[pre-content] as a defined term (e.g., in +italic). Consider using @racket[deftech] instead, though, so that uses +of @racket[tech] can hyper-link to the definition.} @defproc[(onscreen [pre-content pre-content?] ...) element?]{ Typesets the -@tech{decode}d @scheme[pre-content] as a string that appears in a GUI, +@tech{decode}d @racket[pre-content] as a string that appears in a GUI, such as the name of a button.} @defproc[(menuitem [menu-name string?] [item-name string?]) element?]{ Typesets the given combination of a GUI's menu and item name.} @defproc[(filepath [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a file name (e.g., in +@tech{decode}d @racket[pre-content] as a file name (e.g., in typewriter font and in in quotes).} @defproc[(exec [pre-content pre-content?] ...) element?]{Typesets the -@tech{decode}d @scheme[pre-content] as a command line (e.g., in +@tech{decode}d @racket[pre-content] as a command line (e.g., in typewriter font).} @defproc[(envvar [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as an environment variable (e.g., +@tech{decode}d @racket[pre-content] as an environment variable (e.g., in typewriter font).} @defproc[(Flag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as a flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] as a flag (e.g., in typewriter font with a leading @litchar{-}).} @defproc[(DFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] a long flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] a long flag (e.g., in typewriter font with two leading @litchar{-}s).} @defproc[(PFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] as a @litchar{+} flag (e.g., in typewriter +@tech{decode}d @racket[pre-content] as a @litchar{+} flag (e.g., in typewriter font with a leading @litchar{+}).} @defproc[(DPFlag [pre-content pre-content?] ...) element?]{Typesets the given -@tech{decode}d @scheme[pre-content] a long @litchar{+} flag (e.g., in +@tech{decode}d @racket[pre-content] a long @litchar{+} flag (e.g., in typewriter font with two leading @litchar{+}s).} @; ------------------------------------------------------------------------ @@ -885,35 +946,39 @@ typewriter font with two leading @litchar{+}s).} See also @secref["base-links"]. -@defform[(schemelink id pre-content ...) +@defform[(racketlink id pre-content ...) #:contracts ([id identifier?] [pre-content pre-content?])]{ -An element where the @tech{decode}d @scheme[pre-content] is hyperlinked to the definition -of @scheme[id].} +An element where the @tech{decode}d @racket[pre-content] is hyperlinked to the definition +of @racket[id].} + +@defform[(schemelink id pre-content ...)]{ + +Compatibility alias for @racket[racketlink].} @defproc[(link [url string?] [pre-content any/c] ... [#:underline? underline? any/c #t] [#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")]) element?]{ -An alias of @scheme[hyperlink] for backward compatibility.} +Alias of @racket[hyperlink] for backward compatibility.} @defproc[(other-manual [module-path module-path?] [#:underline? underline? any/c #t]) element?]{ -An alias of @scheme[other-doc] for backward compatibility.} +Alias of @racket[other-doc] for backward compatibility.} @defproc[(deftech [pre-content pre-content?] ... [#:style? style? boolean? #t]) element?]{ -Produces an element for the @tech{decode}d @scheme[pre-content], and +Produces an element for the @tech{decode}d @racket[pre-content], and also defines a term that can be referenced elsewhere using -@scheme[tech]. +@racket[tech]. -The @scheme[content->string] result of the @tech{decode}d -@scheme[pre-content] is used as a key for references, but normalized +The @racket[content->string] result of the @tech{decode}d +@racket[pre-content] is used as a key for references, but normalized as follows: @itemize[ @@ -931,22 +996,22 @@ These normalization steps help support natural-language references that differ slightly from a defined form. For example, a definition of ``bananas'' can be referenced with a use of ``banana''. -If @scheme[style?] is true, then @scheme[defterm] is used on -@scheme[pre-content].} +If @racket[style?] is true, then @racket[defterm] is used on +@racket[pre-content].} @defproc[(tech [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ -Produces an element for the @tech{decode}d @scheme[pre-content], and +Produces an element for the @tech{decode}d @racket[pre-content], and hyperlinks it to the definition of the content as established by -@scheme[deftech]. The content's string form is normalized in the same -way as for @scheme[deftech]. The @scheme[#:doc] and -@scheme[#:tag-prefixes] arguments support cross-document and -section-specific references, like in @scheme[secref]. +@racket[deftech]. The content's string form is normalized in the same +way as for @racket[deftech]. The @racket[#:doc] and +@racket[#:tag-prefixes] arguments support cross-document and +section-specific references, like in @racket[secref]. -With the default style files, the hyperlink created by @scheme[tech] +With the default style files, the hyperlink created by @racket[tech] is somewhat quieter than most hyperlinks: the underline in HTML output is gray, instead of blue, and the term and underline turn blue only when the mouse is moved over the term. @@ -955,14 +1020,14 @@ In some cases, combining both natural-language uses of a term and proper linking can require some creativity, even with the normalization performed on the term. For example, if ``bind'' is defined, but a sentence uses the term ``binding,'' the latter can be -linked to the former using @schemefont["@tech{bind}ing"].} +linked to the former using @racketfont["@tech{bind}ing"].} @defproc[(techlink [pre-content pre-content?] ... [#:doc module-path (or/c module-path? false/c) #f] [#:tag-prefixes prefixes (or/c (listof string?) false/c) #f]) element?]{ -Like @scheme[tech], but the link is not a quiet. For example, in HTML +Like @racket[tech], but the link is not a quiet. For example, in HTML output, a hyperlink underline appears even when the mouse is not over the link.} @@ -971,37 +1036,41 @@ the link.} See also @secref["base-indexing"]. -@defform[(indexed-scheme datum ...)]{ +@defform[(indexed-racket datum ...)]{ -A combination of @scheme[scheme] and @scheme[as-index], with the -following special cases when a single @scheme[datum] is provided: +A combination of @racket[racket] and @racket[as-index], with the +following special cases when a single @racket[datum] is provided: @itemize[ - @item{If @scheme[datum] is a @scheme[quote] form, then the quote is + @item{If @racket[datum] is a @racket[quote] form, then the quote is removed from the key (so that it's sorted using its unquoted form).} - @item{If @scheme[datum] is a string, then quotes are removed from the + @item{If @racket[datum] is a string, then quotes are removed from the key (so that it's sorted using the string content).} ]} +@defform[(indexed-scheme datum ...)]{ + +Compatibility alias for @racket[indexed-racket].} + @defproc[(idefterm [pre-content pre-content?] ...) element?]{Combines -@scheme[as-index] and @scheme[defterm]. The content normally should be -plural, rather than singular. Consider using @scheme[deftech], +@racket[as-index] and @racket[defterm]. The content normally should be +plural, rather than singular. Consider using @racket[deftech], instead, which always indexes.} @defproc[(pidefterm [pre-content pre-content?] ...) element?]{Like -@scheme[idefterm], but plural: adds an ``s'' on the end of the content -for the index entry. Consider using @scheme[deftech], instead.} +@racket[idefterm], but plural: adds an ``s'' on the end of the content +for the index entry. Consider using @racket[deftech], instead.} @defproc[(indexed-file [pre-content pre-content?] ...) element?]{A -combination of @scheme[file] and @scheme[as-index], but where the sort +combination of @racket[file] and @racket[as-index], but where the sort key for the index iterm does not include quotes.} @defproc[(indexed-envvar [pre-content pre-content?] ...) element?]{A -combination of @scheme[envvar] and @scheme[as-index].} +combination of @racket[envvar] and @racket[as-index].} @; ------------------------------------------------------------------------ @section[#:tag "manual-images"]{Images} @@ -1010,16 +1079,16 @@ combination of @scheme[envvar] and @scheme[as-index].} [pre-element any/c] ...) element?]{ - An alias for @scheme[image] for backward compatibility.} + An alias for @racket[image] for backward compatibility.} @; ------------------------------------------------------------------------ @section{Bibliography} -@margin-note{See also @schememodname[scriblib/autobib].} +@margin-note{See also @racketmodname[scriblib/autobib].} @defproc[(cite [key string?] ...+) element?]{ -Links to a bibliography entry, using the @scheme[key]s both to indicate the +Links to a bibliography entry, using the @racket[key]s both to indicate the bibliography entry and, in square brackets, as the link text.} @defproc[(bibliography [#:tag tag string? "doc-bibliography"] @@ -1027,7 +1096,7 @@ bibliography entry and, in square brackets, as the link text.} part?]{ Creates a bibliography part containing the given entries, each of -which is created with @scheme[bib-entry]. The entries are typeset in +which is created with @racket[bib-entry]. The entries are typeset in order as given.} @defproc[(bib-entry [#:key key string?] @@ -1039,52 +1108,52 @@ order as given.} [#:url url (or/c false/c pre-content?) #f]) bib-entry?]{ -Creates a bibliography entry. The @scheme[key] is used to refer to the -entry via @scheme[cite]. The other arguments are used as elements in +Creates a bibliography entry. The @racket[key] is used to refer to the +entry via @racket[cite]. The other arguments are used as elements in the entry: @itemize[ - @item{@scheme[title] is the title of the cited work. It will be - surrounded by quotes in typeset form if @scheme[is-book?] is - @scheme[#f], otherwise it is typeset via @scheme[italic].} + @item{@racket[title] is the title of the cited work. It will be + surrounded by quotes in typeset form if @racket[is-book?] is + @racket[#f], otherwise it is typeset via @racket[italic].} - @item{@scheme[author] lists the authors. Use names in their usual + @item{@racket[author] lists the authors. Use names in their usual order (as opposed to ``last, first''), and separate multiple names with commas using ``and'' before the last name (where - there are multiple names). The @scheme[author] is typeset in + there are multiple names). The @racket[author] is typeset in the bibliography as given, or it is omitted if given as - @scheme[#f].} + @racket[#f].} - @item{@scheme[location] names the publication venue, such as a + @item{@racket[location] names the publication venue, such as a conference name or a journal with volume, number, and - pages. The @scheme[location] is typeset in the bibliography as - given, or it is omitted if given as @scheme[#f].} + pages. The @racket[location] is typeset in the bibliography as + given, or it is omitted if given as @racket[#f].} - @item{@scheme[date] is a date, usually just a year (as a string). It + @item{@racket[date] is a date, usually just a year (as a string). It is typeset in the bibliography as given, or it is omitted if - given as @scheme[#f].} + given as @racket[#f].} - @item{@scheme[url] is an optional URL. It is typeset in the - bibliography using @scheme[tt] and hyperlinked, or it is - omitted if given as @scheme[#f].} + @item{@racket[url] is an optional URL. It is typeset in the + bibliography using @racket[tt] and hyperlinked, or it is + omitted if given as @racket[#f].} ]} @defproc[(bib-entry? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a bibliography entry created by -@scheme[bib-entry], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a bibliography entry created by +@racket[bib-entry], @racket[#f] otherwise.} @; ------------------------------------------------------------------------ @section{Miscellaneous} @defproc[(t [pre-content pre-content?] ...) paragraph?]{Wraps the -@tech{decode}d @scheme[pre-content] as a paragraph.} +@tech{decode}d @racket[pre-content] as a paragraph.} -@defthing[PLaneT element?]{@scheme["PLaneT"] (to help make sure you get +@defthing[PLaneT element?]{@racket["PLaneT"] (to help make sure you get the letters in the right case).} @defproc[(hash-lang) element?]{Returns an element for @hash-lang[] @@ -1099,14 +1168,14 @@ an inset command-line example (e.g., in typewriter font).} @defproc[(centerline [pre-flow pre-flow?] ...) nested-flow?]{ -An alias for @scheme[centered] for backward compatibility.} +An alias for @racket[centered] for backward compatibility.} @defproc[(math [pre-content any/c] ...) element?]{The @tech{decode}d -@scheme[pre-content] is further transformed: +@racket[pre-content] is further transformed: @itemize[ - @item{Any immediate @scheme['rsquo] is converted to @scheme['prime].} + @item{Any immediate @racket['rsquo] is converted to @racket['prime].} @item{Parentheses and sequences of decimal digits in immediate strings are left as-is, but any other immediate string is @@ -1124,24 +1193,24 @@ An alias for @scheme[centered] for backward compatibility.} @section[#:tag "index-entries"]{Index-Entry Descriptions} @defmodule[scribble/manual-struct]{The -@schememodname[scribble/manual-struct] library provides types used to -describe index entries created by @schememodname[scribble/manual] +@racketmodname[scribble/manual-struct] library provides types used to +describe index entries created by @racketmodname[scribble/manual] functions. These structure types are provided separate from -@schememodname[scribble/manual] so that -@schememodname[scribble/manual] need not be loaded when deserializing +@racketmodname[scribble/manual] so that +@racketmodname[scribble/manual] need not be loaded when deserializing cross-reference information that was generated by a previously rendered document.} @defstruct[module-path-index-desc ()]{ Indicates that the index entry corresponds to a module definition via -@scheme[defmodule] and company.} +@racket[defmodule] and company.} @defstruct[exported-index-desc ([name symbol?] [from-libs (listof module-path?)])]{ Indicates that the index entry corresponds to the definition of an -exported binding. The @scheme[name] field and @scheme[from-libs] list +exported binding. The @racket[name] field and @racket[from-libs] list correspond to the documented name of the binding and the primary modules that export the documented name (but this list is not exhaustive, because new modules can re-export the binding).} @@ -1149,44 +1218,44 @@ exhaustive, because new modules can re-export the binding).} @defstruct[(form-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -syntactic form via @scheme[defform] and company.} +syntactic form via @racket[defform] and company.} @defstruct[(procedure-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -procedure binding via @scheme[defproc] and company.} +procedure binding via @racket[defproc] and company.} @defstruct[(thing-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -binding via @scheme[defthing] and company.} +binding via @racket[defthing] and company.} @defstruct[(struct-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -structure type via @scheme[defstruct] and company.} +structure type via @racket[defstruct] and company.} @defstruct[(class-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -class via @scheme[defclass] and company.} +class via @racket[defclass] and company.} @defstruct[(interface-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of an -interface via @scheme[definterface] and company.} +interface via @racket[definterface] and company.} @defstruct[(mixin-index-desc exported-index-desc) ()]{ Indicates that the index entry corresponds to the definition of a -mixin via @scheme[defmixin] and company.} +mixin via @racket[defmixin] and company.} @defstruct[(method-index-desc exported-index-desc) ([method-name symbol?] [class-tag tag?])]{ Indicates that the index entry corresponds to the definition of an -method via @scheme[defmethod] and company. The @scheme[_name] field -from @scheme[exported-index-desc] names the class or interface that -contains the method. The @scheme[method-name] field names the method. -The @scheme[class-tag] field provides a pointer to the start of the +method via @racket[defmethod] and company. The @racket[_name] field +from @racket[exported-index-desc] names the class or interface that +contains the method. The @racket[method-name] field names the method. +The @racket[class-tag] field provides a pointer to the start of the documentation for the method's class or interface.} diff --git a/collects/scribblings/scribble/plt.scrbl b/collects/scribblings/scribble/plt.scrbl index b44754f6..89b1a04a 100644 --- a/collects/scribblings/scribble/plt.scrbl +++ b/collects/scribblings/scribble/plt.scrbl @@ -3,8 +3,8 @@ @title[#:tag "plt-manuals" #:style 'toc]{Scribbling Documentation} -The @schememodname[scribble/manual] language and associated libraries -provide extensive support for documenting PLT Scheme libraries. The +The @racketmodname[scribble/manual] language and associated libraries +provide extensive support for documenting Racket libraries. The most significant aspect of support for documentation is the way that source-code bindings are connected to documentation sites through the module namespace---a connection that is facilitated by the fact that diff --git a/collects/scribblings/scribble/preprocessor.scrbl b/collects/scribblings/scribble/preprocessor.scrbl index 1eefe135..187768cd 100644 --- a/collects/scribblings/scribble/preprocessor.scrbl +++ b/collects/scribblings/scribble/preprocessor.scrbl @@ -2,7 +2,7 @@ @(require scribble/manual scribble/core scribble/html-properties scribble/latex-properties "utils.ss" - (for-label scheme/base + (for-label racket/base ;; FIXME: need to get this in ;; scribble/text )) @@ -13,21 +13,21 @@ (make-css-addition "shaded.css"))) ]{Text Preprocessing} -@defmodulelang[scribble/text]{The @schememodname[scribble/text] -language provides everything from @scheme[scheme/base] with a few +@defmodulelang[scribble/text]{The @racketmodname[scribble/text] +language provides everything from @racket[racket/base] with a few changes that make it suitable as a preprocessor language: @itemize[ - @item{It uses @scheme[read-syntax-inside] to read the body of the + @item{It uses @racket[read-syntax-inside] to read the body of the module, similar to @secref["docreader"]. This means that by - default, all text is read in as Scheme strings; and - @seclink["reader"]|{@-forms}| can be used to use Scheme + default, all text is read in as Racket strings; and + @seclink["reader"]|{@-forms}| can be used to use Racket functions and expression escapes.} @item{Values of expressions are printed with a custom - @scheme[output] function. This function displays most values - in a similar way to @scheme[display], except that it is more + @racket[output] function. This function displays most values + in a similar way to @racket[display], except that it is more convenient for a preprocessor output.}] } @@ -35,16 +35,16 @@ changes that make it suitable as a preprocessor language: @; TODO: @; * make all example sections be subsections, @; * add a reference section, -@; * a section on "scribble/text.ss" +@; * a section on "scribble/text.rkt" @; * maybe a section on additional utilities: begin/text @;-------------------------------------------------------------------- @section{Writing Preprocessor Files} The combination of the two features makes text in files in the -@scheme[scribble/text] language be read as strings, which get printed -out when the module is @scheme[require]d, for example, when a file is -given as an argument to @exec{mzscheme}. (In these example the left +@racket[scribble/text] language be read as strings, which get printed +out when the module is @racket[require]d, for example, when a file is +given as an argument to @exec{racket}. (In these example the left part shows the source input, and the right part the printed result.) @example|-{#lang scribble/text @@ -58,14 +58,14 @@ part shows the source input, and the right part the printed result.) feature on top of feature, but blah blah blah.}-| -Using @seclink["reader"]|{@-forms}|, we can define and use Scheme +Using @seclink["reader"]|{@-forms}|, we can define and use Racket functions. @example|-{#lang scribble/text - @(require scheme/list) + @(require racket/list) @(define Foo "Preprocessing") @(define (3x . x) - ;; scheme syntax here + ;; racket syntax here (add-between (list x x x) " ")) @Foo languages should be designed not by piling @@ -77,10 +77,10 @@ functions. feature on top of feature, but blah blah blah.}-| -As demonstrated in this case, the @scheme[output] function simply +As demonstrated in this case, the @racket[output] function simply scans nested list structures recursively, which makes them convenient -for function results. In addition, @scheme[output] prints most values -similarly to @scheme[display] --- notable exceptions are void and +for function results. In addition, @racket[output] prints most values +similarly to @racket[display] --- notable exceptions are void and false values which cause no output to appear. This can be used for convenient conditional output. @@ -184,7 +184,7 @@ what looks like erroneous indentation. More about this below.) A better approach is to generate newlines only when needed. @example|-{#lang scribble/text - @(require scheme/list) + @(require racket/list) @(define (counts n str) (add-between (for/list ([i (in-range 1 (+ n 1))]) @@ -200,9 +200,9 @@ A better approach is to generate newlines only when needed. 3 Mississippi, ... and I'm done.}-| -In fact, this is common enough that the @scheme[scribble/text] -language provides a convenient facility: @scheme[add-newlines] is a -function that is similar to @scheme[add-between] using a newline +In fact, this is common enough that the @racket[scribble/text] +language provides a convenient facility: @racket[add-newlines] is a +function that is similar to @racket[add-between] using a newline string as the default separator, except that false and void values are filtered out before doing so. @@ -262,9 +262,9 @@ that uses the Scribble @"@"-form syntax.) Because the Scribble reader is uniform, you can use it in place of any expression where it is more convenient. (By convention, we use a -plain S-expression syntax when we want a Scheme expression escape, and +plain S-expression syntax when we want a Racket expression escape, and an @"@"-form for expressions that render as text, which, in the -@scheme[scribble/text] language, is any value-producing expression.) +@racket[scribble/text] language, is any value-producing expression.) For example, you can use an @"@"-form for a function that you define. @example|-{#lang scribble/text @@ -291,7 +291,7 @@ separate text arguments in the S-expression part of an @"@"-form. Either you're with us, or against us. }-| -You can even use @"@"-forms with a Scheme quote or quasiquote as the +You can even use @"@"-forms with a Racket quote or quasiquote as the ``head'' part to make it shorter, or use a macro to get grouping of sub-parts without dealing with quotes. @@ -317,11 +317,11 @@ sub-parts without dealing with quotes. }-| Yet another solution is to look at the text values and split the input -arguments based on a specific token. Using @scheme[match] can make it +arguments based on a specific token. Using @racket[match] can make it convenient --- you can even specify the patterns with @"@"-forms. @example|-{#lang scribble/text - @(require scheme/match) + @(require racket/match) @(define (features . text) (match text [@list{@|1st|@... @@ -346,11 +346,11 @@ convenient --- you can even specify the patterns with @"@"-forms. }-| In particular, it is often convenient to split the input by lines, -identified by delimiting @scheme["\n"] strings. Since this can be -useful, a @scheme[split-lines] function is provided. +identified by delimiting @racket["\n"] strings. Since this can be +useful, a @racket[split-lines] function is provided. @example|-{#lang scribble/text - @(require scheme/list) + @(require racket/list) @(define (features . text) (add-between (split-lines text) ", ")) @@ -437,9 +437,9 @@ printouts, as the results are rarely desirable. two1 3}-| Note that you don't need side-effects if you want infinite output. -The @scheme[output] function iterates thunks and (composable) +The @racket[output] function iterates thunks and (composable) promises, so you can create a loop that is delayed in either form. -@; Note: there is some sfs-related problem in mzscheme that makes it not +@; Note: there is some sfs-related problem in racket that makes it not @; run in bounded space, so don't show it for nowx. @example|-{#lang scribble/text @@ -483,12 +483,12 @@ The Scribble reader ignores indentation spaces in its body. This is an intentional feature, since you usually do not want an expression to depend on its position in the source. But the question is how @emph{can} we render some output text with proper indentation. The -@scheme[output] function achieves that by assigning a special meaning +@racket[output] function achieves that by assigning a special meaning to lists: when a newline is part of a list's contents, it causes the following text to appear with indentation that corresponds to the column position at the beginning of the list. In most cases, this makes the output appear ``as intended'' when lists are used for nested -pieces of text --- either from a literal @scheme[list] expression, or +pieces of text --- either from a literal @racket[list] expression, or an expression that evaluates to a list, or when a list is passed on as a value; either as a toplevel expression, or as a nested value; either appearing after spaces, or after other output. @@ -530,11 +530,11 @@ appearing after spaces, or after other output. (for/list ([i (in-naturals 1)] [item (in-list items)]) @list{@|i|. @item}))) - Todo: @enumerate[@list{Install PLT Scheme} + Todo: @enumerate[@list{Install Racket} @list{Hack, hack, hack} @list{Profit}]. ---***--- - Todo: 1. Install PLT Scheme; + Todo: 1. Install Racket; 2. Hack, hack, hack; 3. Profit.}-| @@ -697,8 +697,8 @@ appearing after spaces, or after other output. }-| There are, however, cases when you need more refined control over the -output. The @scheme[scribble/text] provides a few functions for such -cases. The @scheme[splice] function is used to group together a +output. The @racket[scribble/text] provides a few functions for such +cases. The @racket[splice] function is used to group together a number of values but avoid introducing a new indentation context. @example|-{#lang scribble/text @@ -723,9 +723,9 @@ number of values but avoid introducing a new indentation context. end }-| -The @scheme[disable-prefix] function disables all indentation +The @racket[disable-prefix] function disables all indentation printouts in its contents, including the indentation before the body -of the @scheme[disable-prefix] value itself. It is useful, for +of the @racket[disable-prefix] value itself. It is useful, for example, to print out CPP directives. @example|-{#lang scribble/text @@ -758,7 +758,7 @@ example, to print out CPP directives. } }-| -If there are values after a @scheme[disable-prefix] value on the same +If there are values after a @racket[disable-prefix] value on the same line, they will get indented to the goal column (unless the output is already beyond it). @@ -807,7 +807,7 @@ already beyond it). }-| There are cases where each line should be prefixed with some string -other than a plain indentation. The @scheme[add-prefix] function +other than a plain indentation. The @racket[add-prefix] function causes its contents to be printed using some given string prefix for every line. The prefix gets accumulated to an existing indentation, and indentation in the contents gets added to the prefix. @@ -840,11 +840,11 @@ and indentation in the contents gets added to the prefix. } }-| -When combining @scheme[add-prefix] and @scheme[disable-prefix] there -is an additional value that can be useful: @scheme[flush]. This is a -value that causes @scheme[output] to print the current indentation and +When combining @racket[add-prefix] and @racket[disable-prefix] there +is an additional value that can be useful: @racket[flush]. This is a +value that causes @racket[output] to print the current indentation and prefix. This makes it possible to get the ``ignored as a prefix'' -property of @scheme[disable-prefix] but only for a nested prefix. +property of @racket[disable-prefix] but only for a nested prefix. @example|-{#lang scribble/text @(define (comment . text) @@ -923,17 +923,17 @@ property of @scheme[disable-prefix] but only for a nested prefix. Using additional files that contain code for your preprocessing is trivial: the preprocessor source is still source code in a module, so -you can @scheme[require] additional files with utility functions. +you can @racket[require] additional files with utility functions. @example|-{#lang scribble/text - @(require "itemize.ss") + @(require "itemize.rkt") Todo: @itemize[@list{Hack some} @list{Sleep some} @list{Hack some more}] - ---***--- itemize.ss - #lang scheme + ---***--- itemize.rkt + #lang racket (provide itemize) (define (itemize . items) (add-between (map (lambda (item) @@ -948,21 +948,21 @@ you can @scheme[require] additional files with utility functions. more }-| -Note that the @seclink["at-exp-lang"]{@scheme[at-exp] language} can +Note that the @seclink["at-exp-lang"]{@racket[at-exp] language} can often be useful here, since such files need to deal with texts. Using it, it is easy to include a lot of textual content. @example|-{#lang scribble/text - @(require "stuff.ss") + @(require "stuff.rkt") Todo: @itemize[@list{Hack some} @list{Sleep some} @list{Hack some more}] @summary - ---***--- stuff.ss - #lang at-exp scheme/base - (require scheme/list) + ---***--- stuff.rkt + #lang at-exp racket/base + (require racket/list) (provide (all-defined-out)) (define (itemize . items) (add-between (map (lambda (item) @@ -983,17 +983,17 @@ it, it is easy to include a lot of textual content. }-| Of course, the extreme side of this will be to put all of your content -in a plain Scheme module, using @"@"-forms for convenience. However, +in a plain Racket module, using @"@"-forms for convenience. However, there is no need to use the preprocessor language in this case; -instead, you can @scheme[(require scribble/text)], which will get all -of the bindings that are available in the @scheme[scribble/text] -language. Using @scheme[output], switching from a preprocessed files -to a Scheme file is very easy ---- choosing one or the other depends +instead, you can @racket[(require scribble/text)], which will get all +of the bindings that are available in the @racket[scribble/text] +language. Using @racket[output], switching from a preprocessed files +to a Racket file is very easy ---- choosing one or the other depends on whether it is more convenient to write a text file with occasional -Scheme expressions or the other way. +Racket expressions or the other way. -@example|-{#lang at-exp scheme/base - (require scribble/text scheme/list) +@example|-{#lang at-exp racket/base + (require scribble/text racket/list) (define (itemize . items) (add-between (map (lambda (item) @list{* @item}) @@ -1026,12 +1026,12 @@ mostly-text file from a preprocessor file. It might be because you prefer to split the source text to several files, or because you need to preprocess a file without even a @litchar{#lang} header (for example, an HTML template file that is the result of an external -editor). For these cases, the @scheme[scribble/text] language -provides an @scheme[include] form that includes a file in the +editor). For these cases, the @racket[scribble/text] language +provides an @racket[include] form that includes a file in the preprocessor syntax (where the default parsing mode is text). @example|-{#lang scribble/text - @(require scheme/list) + @(require racket/list) @(define (itemize . items) (list "
    " @@ -1074,12 +1074,12 @@ preprocessor syntax (where the default parsing mode is text). }-| -(Using @scheme[require] with a text file in the @scheme[scribble/text] +(Using @racket[require] with a text file in the @racket[scribble/text] language will not work as intended: using the preprocessor language means that the text is displayed when the module is invoked, so the required file's contents will be printed before any of the requiring module's text does. If you find yourself in such a situation, it is -better to switch to a Scheme-with-@"@"-expressions file as shown +better to switch to a Racket-with-@"@"-expressions file as shown above.) @;FIXME: add more text on `restore-prefix', `set-prefix', `with-writer' @@ -1087,20 +1087,20 @@ above.) @;FIXME: add this to the reference section @;@defform[(include filename)]{ @; -@;Preprocess the @scheme[filename] using the same syntax as -@;@scheme[scribble/text]. This is similar to using @scheme[load] in a +@;Preprocess the @racket[filename] using the same syntax as +@;@racket[scribble/text]. This is similar to using @racket[load] in a @;namespace that can access names bound in the current file so included @;code can refer to bindings from the including module. Note, however, @;that the including module cannot refer to names that are bound the -@;included file because it is still a plain scheme module---for such -@;uses you should still use @scheme[require] as usual.} +@;included file because it is still a plain racket module---for such +@;uses you should still use @racket[require] as usual.} @; Two random tests @example[#:hidden]|-{ #lang scribble/text - @define[name]{PLT Scheme} + @define[name]{Racket} Suggested price list for "@name" @@ -1124,11 +1124,11 @@ above.) Total: @items-num items Average price: $@|average|.99 ---***--- - Suggested price list for "PLT Scheme" + Suggested price list for "Racket" - 0. PLT Scheme Home edition: $99.99 - 1. PLT Scheme Professional edition: $149.99 - 2. PLT Scheme Enterprize edition: $349.99 + 0. Racket Home edition: $99.99 + 1. Racket Professional edition: $149.99 + 2. Racket Enterprize edition: $349.99 Total: 3 items Average price: $199.99 diff --git a/collects/scribblings/scribble/reader-internals.scrbl b/collects/scribblings/scribble/reader-internals.scrbl index 9e0240e1..8ad09806 100644 --- a/collects/scribblings/scribble/reader-internals.scrbl +++ b/collects/scribblings/scribble/reader-internals.scrbl @@ -3,53 +3,53 @@ scribble/bnf scribble/eval "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label (only-in scribble/reader use-at-readtable))) @(define read-eval (make-base-eval)) -@(interaction-eval #:eval read-eval (require (for-syntax scheme/base))) +@(interaction-eval #:eval read-eval (require (for-syntax racket/base))) @title[#:tag "reader-internals"]{@"@" Reader Internals} @;-------------------------------------------------------------------- @section{Using the @"@" Reader} -You can use the reader via Scheme's @schemefont{#reader} form: +You can use the reader via Racket's @racketfont{#reader} form: -@schemeblock[ - @#,schemefont|{ +@racketblock[ + @#,racketfont|{ #reader scribble/reader @foo{This is free-form text!} }|] -or use the @scheme[at-exp] meta-language as described in +or use the @racket[at-exp] meta-language as described in @secref["at-exp-lang"]. Note that the Scribble reader reads @"@"-forms as S-expressions. This means that it is up to you to give meanings for these expressions in -the usual way: use Scheme functions, define your functions, or require -functions. For example, typing the above into @exec{mzscheme} is likely +the usual way: use Racket functions, define your functions, or require +functions. For example, typing the above into @exec{racket} is likely going to produce a ``reference to undefined identifier'' error, unless -@scheme[foo] is defined. You can use @scheme[string-append] instead, -or you can define @scheme[foo] as a function (with variable arity). +@racket[foo] is defined. You can use @racket[string-append] instead, +or you can define @racket[foo] as a function (with variable arity). A common use of the Scribble @"@"-reader is when using Scribble as a documentation system for producing manuals. In this case, the manual text is likely to start with -@schememod[scribble/doc] +@racketmod[scribble/doc] which installs the @"@" reader starting in ``text mode,'' wraps the -file content afterward into a Scheme module where many useful Scheme +file content afterward into a Racket module where many useful Racket and documentation related functions are available, and parses the body -into a document using @schememodname[scribble/decode]. See +into a document using @racketmodname[scribble/decode]. See @secref["docreader"] for more information. -Another way to use the reader is to use the @scheme[use-at-readtable] +Another way to use the reader is to use the @racket[use-at-readtable] function to switch the current readtable to a readtable that parses @"@"-forms. You can do this in a single command line: -@commandline{mzscheme -ile scribble/reader "(use-at-readtable)"} +@commandline{racket -ile scribble/reader "(use-at-readtable)"} @;-------------------------------------------------------------------- @section{Syntax Properties} @@ -57,12 +57,12 @@ function to switch the current readtable to a readtable that parses The Scribble reader attaches properties to syntax objects. These properties might be useful in some rare situations. -Forms that Scribble reads are marked with a @scheme['scribble] +Forms that Scribble reads are marked with a @racket['scribble] property, and a value of a list of three elements: the first is -@scheme['form], the second is the number of items that were read from +@racket['form], the second is the number of items that were read from the datum part, and the third is the number of items in the body part -(strings, sub-forms, and escapes). In both cases, a @scheme[0] means -an empty datum/body part, and @scheme[#f] means that the corresponding +(strings, sub-forms, and escapes). In both cases, a @racket[0] means +an empty datum/body part, and @racket[#f] means that the corresponding part was omitted. If the form has neither parts, the property is not attached to the result. This property can be used to give different meanings to expressions from the datum and the body parts, for @@ -102,10 +102,10 @@ example, implicitly quoted keywords: In addition, the Scribble parser uses syntax properties to mark syntax items that are not physically in the original source --- indentation -spaces and newlines. Both of these will have a @scheme['scribble] +spaces and newlines. Both of these will have a @racket['scribble] property; an indentation string of spaces will have -@scheme['indentation] as the value of the property, and a newline will -have a @scheme['(newline S)] value where @scheme[S] is the original +@racket['indentation] as the value of the property, and a newline will +have a @racket['(newline S)] value where @racket[S] is the original newline string including spaces that precede and follow it (which includes the indentation for the following item). This can be used to implement a verbatim environment: drop indentation strings, and use @@ -147,26 +147,26 @@ is an example of this. @;-------------------------------------------------------------------- @section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language} -@defmodulelang[at-exp]{The @schememodname[at-exp] language installs +@defmodulelang[at-exp]{The @racketmodname[at-exp] language installs @"@"-reader support in the readtable, and then chains to the reader of -another language that is specified immediate after -@schememodname[at-exp].} +another language that is specified immediately after +@racketmodname[at-exp].} -For example, @scheme[@#,hash-lang[] at-exp scheme/base] adds @"@"-reader -support to @scheme[scheme/base], so that +For example, @racket[@#,hash-lang[] at-exp racket/base] adds @"@"-reader +support to @racket[racket/base], so that -@schememod[ -at-exp scheme/base +@racketmod[ +at-exp racket/base -(define (greet who) @#,elem{@tt["@"]@scheme[string-append]@schemeparenfont["{"]@schemevalfont{Hello, }@tt["@|"]@scheme[who]@tt["|"]@schemevalfont{.}@schemeparenfont["}"]}) +(define (greet who) @#,elem{@tt["@"]@racket[string-append]@racketparenfont["{"]@racketvalfont{Hello, }@tt["@|"]@racket[who]@tt["|"]@racketvalfont{.}@racketparenfont["}"]}) (greet "friend")] -reports @scheme["Hello, friend."]. +reports @racket["Hello, friend."]. @;-------------------------------------------------------------------- @section{Interface} -@defmodule[scribble/reader]{The @schememodname[scribble/reader] module +@defmodule[scribble/reader]{The @racketmodname[scribble/reader] module provides direct Scribble reader functionality for advanced needs.} @; The `with-scribble-read' trick below shadows `read' and @@ -193,7 +193,7 @@ for reading. @defproc[(read-syntax-inside [source-name any/c (object-name in)] [in input-port? (current-input-port)]) (or/c syntax? eof-object?)]{ -These @schemeid[-inside] variants parse as if starting inside a +These @racketid[-inside] variants parse as if starting inside a @litchar["@{"]...@litchar["}"], and they return a (syntactic) list. Useful for implementing languages that are textual by default (see @filepath{docreader.ss} for example). @@ -216,26 +216,26 @@ resulting reader in several ways: @itemize[ -@item{@scheme[readtable] --- a readtable to base the @"@"-readtable +@item{@racket[readtable] --- a readtable to base the @"@"-readtable on.} -@item{@scheme[command-char] --- the character used for @"@"-forms.} +@item{@racket[command-char] --- the character used for @"@"-forms.} -@item{@scheme[datum-readtable] --- determines the readtable used for - reading the datum part. A @scheme[#t] values uses the +@item{@racket[datum-readtable] --- determines the readtable used for + reading the datum part. A @racket[#t] values uses the @"@"-readtable, otherwise it can be a readtable, or a readtable-to-readtable function that will construct one from the @"@"-readtable. The idea is that you may want to have completely different uses for the datum part, for example, introducing a convenient @litchar{key=val} syntax for attributes.} -@item{@scheme[syntax-post-proc] --- function that is applied on +@item{@racket[syntax-post-proc] --- function that is applied on each resulting syntax value after it has been parsed (but before it is wrapped quoting punctuations). You can use this to further control uses of @"@"-forms, for example, making the command be the head of a list: - @schemeblock[ + @racketblock[ (use-at-readtable #:syntax-post-processor (lambda (stx) @@ -249,31 +249,31 @@ resulting reader in several ways: @defproc[(make-at-reader [#:syntax? syntax? #t] [#:inside? inside? #f] ...) procedure?]{ Constructs a variant of a @"@"-readtable. The arguments are the same -as in @scheme[make-at-readtable], with two more that determine the -kind of reader function that will be created: @scheme[syntax?] chooses -between a @scheme[read]- or @scheme[read-syntax]-like function, and -@scheme[inside?] chooses a plain reader or an @schemeid[-inside] +as in @racket[make-at-readtable], with two more that determine the +kind of reader function that will be created: @racket[syntax?] chooses +between a @racket[read]- or @racket[read-syntax]-like function, and +@racket[inside?] chooses a plain reader or an @racketid[-inside] variant. The resulting function has a different contract and action based on -these inputs. The expected inputs are as in @scheme[read] or -@scheme[read-syntax] depending on @scheme[syntax?]; the function will -read a single expression or, if @scheme[inside?] is true, the whole +these inputs. The expected inputs are as in @racket[read] or +@racket[read-syntax] depending on @racket[syntax?]; the function will +read a single expression or, if @racket[inside?] is true, the whole input; it will return a syntactic list of expressions rather than a single one in this case. -Note that @scheme[syntax?] defaults to @scheme[#t], as this is the +Note that @racket[syntax?] defaults to @racket[#t], as this is the more expected common case when you're dealing with concrete-syntax reading. -Note that if @scheme[syntax?] is true, the @scheme[read]-like function +Note that if @racket[syntax?] is true, the @racket[read]-like function is constructed by simply converting a syntax result back into a datum.} @defproc[(use-at-readtable ...) void?]{ -Passes all arguments to @scheme[make-at-readtable], and installs the -resulting readtable using @scheme[current-readtable]. It also enables -line counting for the current input-port via @scheme[port-count-lines!]. +Passes all arguments to @racket[make-at-readtable], and installs the +resulting readtable using @racket[current-readtable]. It also enables +line counting for the current input-port via @racket[port-count-lines!]. This is mostly useful for playing with the Scribble syntax on the REPL.} diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl index e04ca036..da1901ce 100644 --- a/collects/scribblings/scribble/reader.scrbl +++ b/collects/scribblings/scribble/reader.scrbl @@ -3,41 +3,41 @@ scribble/bnf scribble/eval "utils.ss" - (for-syntax scheme/base) + (for-syntax racket/base) (for-label (only-in scribble/reader use-at-readtable))) @(define read-eval (make-base-eval)) -@(interaction-eval #:eval read-eval (require (for-syntax scheme/base))) +@(interaction-eval #:eval read-eval (require (for-syntax racket/base))) -@(define (at-exp-scheme) - @scheme[#, @hash-lang[] #, @schememodname[at-exp] #, @schemeidfont{scheme}]) +@(define (at-exp-racket) + @racket[#, @hash-lang[] #, @racketmodname[at-exp] #, @racketidfont{racket}]) @title[#:tag "reader"]{@"@" Syntax} The Scribble @"@" notation is designed to be a convenient facility for -free-form text in Scheme code, where ``@"@"'' was chosen as one of the -least-used characters in existing Scheme code. An @"@"-expression is +free-form text in Racket code, where ``@"@"'' was chosen as one of the +least-used characters in existing Racket code. An @"@"-expression is simply an S-expression in disguise. Typically, @"@" notation is enabled through -@schememodname[scribble/base] or similar languages, but you can also +@racketmodname[scribble/base] or similar languages, but you can also add @"@" notation to an S-expression-based language using the -@schememodname[at-exp] meta-language. For example, +@racketmodname[at-exp] meta-language. For example, @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket (define v '@op{str}) }| is equivalent to -@schememod[ -scheme +@racketmod[ +racket (define v '(op "str")) ] -Using @at-exp-scheme[] is probably the easiest way to try the examples +Using @at-exp-racket[] is probably the easiest way to try the examples in this chapter. @;-------------------------------------------------------------------- @@ -46,7 +46,7 @@ in this chapter. To review @secref["how-to:reader"], the concrete syntax of @"@"-forms is roughly -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@"] @nonterm{cmd} @litchar{[} @kleenestar{@nonterm{datum}} @litchar{]} @@ -57,15 +57,15 @@ where all three parts after @litchar["@"] are optional, but at least one should be present. (Spaces are not allowed between the three parts.) Roughly, a form matching the above grammar is read as -@schemeblock[ +@racketblock[ (@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}}) ] where @nonterm{parsed-body} is the translation of each @nonterm{text-body} in the input. Thus, the initial @nonterm{cmd} -determines the Scheme code that the input is translated into. The -common case is when @nonterm{cmd} is a Scheme identifier, which reads -as a plain Scheme form, with datum arguments and/or string arguments. +determines the Racket code that the input is translated into. The +common case is when @nonterm{cmd} is a Racket identifier, which reads +as a plain Racket form, with datum arguments and/or string arguments. Here is one example: @@ -73,38 +73,38 @@ Here is one example: @foo{blah blah blah} }===| -The example shows how an input syntax is read as Scheme syntax, not +The example shows how an input syntax is read as Racket syntax, not what it evaluates to. If you want to see the translation of an example into S-expression form, add a quote in front of it in a -@at-exp-scheme[] module. For example, running +@at-exp-racket[] module. For example, running @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket '@foo{blah blah blah} }| -in DrScheme prints the output +in DrRacket prints the output -@nested[#:style 'inset]{@schemeresult[(foo "blah blah blah")]} +@nested[#:style 'inset]{@racketresult[(foo "blah blah blah")]} while omitting the quote @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket @foo{blah blah blah} }| -triggers a syntax error because @scheme[foo] is not bound, and +triggers a syntax error because @racket[foo] is not bound, and @verbatim[#:indent 2]|{ - #lang at-exp scheme + #lang at-exp racket (define (foo str) (printf "He wrote ~s.\n" str)) @foo{blah blah blah} }| prints the output -@nested[#:style 'inset]{@schemeoutput{He wrote "blah blah blah".}} +@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}} Here are more examples of @"@"-forms: @@ -122,13 +122,13 @@ Here are more examples of @"@"-forms: }===| As seen in the last example, multiple lines and the newlines that -separate them are parsed to multiple Scheme strings. More generally, +separate them are parsed to multiple Racket strings. More generally, a @nonterm{text-body} is made of text, newlines, and nested @"@"-forms, where the syntax for @"@"-forms is the same whether it's -in a @nonterm{text-body} context as in a Scheme context. A +in a @nonterm{text-body} context as in a Racket context. A @nonterm{text-body} that isn't an @"@"-form is converted to a string expression for its @nonterm{parsed-body}; newlines and following -indentations are converted to @scheme["\n"] and all-space string +indentations are converted to @racket["\n"] and all-space string expressions. @scribble-examples|==={ @@ -142,8 +142,8 @@ expressions. The command part of an @"@"-form is optional as well. In that case, the @"@" forms is read as a list, which usually counts as a function -application, but it also useful when quoted with the usual Scheme -@scheme[quote]: +application, but it also useful when quoted with the usual Racket +@racket[quote]: @scribble-examples|==={ @{blah blah} @@ -155,8 +155,8 @@ application, but it also useful when quoted with the usual Scheme Finally, we can also drop the datum and text parts, which leaves us with only the command---which is read as is, not within a parenthesized -form. This is not useful when reading Scheme code, but it can be used -inside a text block to escape a Scheme identifier. A vertical bar +form. This is not useful when reading Racket code, but it can be used +inside a text block to escape a Racket identifier. A vertical bar (@litchar{|}) can be used to delimit the escaped identifier when needed. @@ -167,7 +167,7 @@ needed. @{blah @|foo|: blah} }===| -Actually, the command part can be any Scheme expression (that does not +Actually, the command part can be any Racket expression (that does not start with @litchar["["], @litchar["{"], or @litchar["|"]), which is particularly useful with such escapes since they can be used with any expression. @@ -177,7 +177,7 @@ expression. @foo{A @"string" escape} }===| -Note that an escaped Scheme string is merged with the surrounding text +Note that an escaped Racket string is merged with the surrounding text as a special case. This is useful if you want to use the special characters in your string, but escaping braces are not necessary if they are balanced. @@ -214,10 +214,10 @@ and @litchar{<>}s.) With this extension, Scribble syntax can be used as a @foo|<<{bar}@|{baz}>>| }===| -On the flip side of this is, how can an @"@" sign be used in Scheme -code? This is almost never an issue, because Scheme strings and +On the flip side of this is, how can an @"@" sign be used in Racket +code? This is almost never an issue, because Racket strings and characters are still read the same, and @litchar["@"] is set as a -non-terminating reader macro so it can be used in Scheme identifiers +non-terminating reader macro so it can be used in Racket identifiers anywhere except in the first character of an identifier. When @litchar["@"] must appear as the first character of an identifier, you must quote the identifier just like other non-standard characters in @@ -229,7 +229,7 @@ normal S-expression syntax: with a backslash or with vertical bars. }===| Note that spaces are not allowed before a @litchar{[} or a -@litchar["{"], or they will be part of the following text (or Scheme +@litchar["{"], or they will be part of the following text (or Racket code). (More on using braces in body texts below.) @scribble-examples|==={ @@ -238,11 +238,11 @@ code). (More on using braces in body texts below.) Finally, remember that the Scribble is just an alternate for S-expressions. Identifiers still get their meaning, as in any -Scheme code, through the lexical context in which they appear. -Specifically, when the above @"@"-form appears in a Scheme expression +Racket code, through the lexical context in which they appear. +Specifically, when the above @"@"-form appears in a Racket expression context, the lexical environment must provide bindings for -@scheme[foo] as a procedure or a macro; it can be defined, required, -or bound locally (with @scheme[let], for example). +@racket[foo] as a procedure or a macro; it can be defined, required, +or bound locally (with @racket[let], for example). @; FIXME: unfortunate code duplication @interaction[ @@ -266,8 +266,8 @@ or bound locally (with @scheme[let], for example). @;-------------------------------------------------------------------- @section{The Command Part} -Besides being a Scheme identifier, the @nonterm{cmd} part of an -@"@"-form can have Scheme punctuation prefixes, which will end up +Besides being a Racket identifier, the @nonterm{cmd} part of an +@"@"-form can have Racket punctuation prefixes, which will end up wrapping the @italic{whole} expression. @scribble-examples|==={ @@ -275,14 +275,14 @@ wrapping the @italic{whole} expression. @#`#'#,@foo{blah} }===| -When writing Scheme code, this means that @litchar|{@`',@foo{blah}}| +When writing Racket code, this means that @litchar|{@`',@foo{blah}}| is exactly the same as @litchar|{`@',@foo{blah}}| and @litchar|{`',@@foo{blah}}|, but unlike the latter two, the first construct can appear in body texts with the same meaning, whereas the other two would not work (see below). After the optional punctuation prefix, the @nonterm{cmd} itself is not -limited to identifiers; it can be @italic{any} Scheme expression. +limited to identifiers; it can be @italic{any} Racket expression. @scribble-examples|==={ @(lambda (x) x){blah} @@ -305,7 +305,7 @@ the @litchar["@"] and the @litchar{;}), then the construct is a comment. There are two comment forms, one for arbitrary-text and possibly nested comments, and another one for line comments: -@schemeblock[ +@racketblock[ @#,BNF-seq[@litchar["@;{"] @kleenestar{@nonterm{any}} @litchar["}"]] @#,BNF-seq[@litchar["@;"] @kleenestar{@nonterm{anything-else-without-newline}}] @@ -323,7 +323,7 @@ following spaces (or tabs) are part of the comment (similar to blah} }===| -Tip: if you're editing in a Scheme-aware editor (like DrScheme or +Tip: if you're editing in a Racket-aware editor (like DrRacket or Emacs), it is useful to comment out blocks like this: @verbatim[#:indent 2]|==={ @@ -337,7 +337,7 @@ parenthesis. If only the @nonterm{cmd} part of an @"@"-form is specified, then the result is the command part only, without an extra set of parenthesis. -This makes it suitable for Scheme escapes in body texts. (More on this +This makes it suitable for Racket escapes in body texts. (More on this below, in the description of the body part.) @scribble-examples|==={ @@ -356,7 +356,7 @@ Finally, note that there are currently no special rules for using @;-------------------------------------------------------------------- @section{The Datum Part} -The datum part can contains arbitrary Scheme expressions, which +The datum part can contains arbitrary Racket expressions, which are simply stacked before the body text arguments: @scribble-examples|==={ @@ -383,7 +383,7 @@ for the same purpose. @foo{} }===| -The most common use of the datum part is for Scheme forms that expect +The most common use of the datum part is for Racket forms that expect keyword-value arguments that precede the body of text arguments. @scribble-examples|==={ @@ -408,7 +408,7 @@ are valid text. As described above, the text turns to a sequence of string arguments for the resulting form. Spaces at the beginning and end of lines are -discarded, and newlines turn to individual @scheme["\n"] strings +discarded, and newlines turn to individual @racket["\n"] strings (i.e., they are not merged with other body parts); see also the information about newlines and indentation below. Spaces are @italic{not} discarded if they appear after the open @litchar["{"] @@ -422,7 +422,7 @@ single-line body. @foo[1]{ bar } }===| -If @litchar["@"] appears in a body, then it is interpreted as Scheme +If @litchar["@"] appears in a body, then it is interpreted as Racket code, which means that the @"@"-reader is applied recursively, and the resulting syntax appears as part of the S-expression, among other string contents. @@ -433,8 +433,8 @@ string contents. If the nested @"@" construct has only a command---no body or datum parts---it will not appear in a subform. Given that the command part -can be any Scheme expression, this makes @"@" a general escape to -arbitrary Scheme code. +can be any Racket expression, this makes @"@" a general escape to +arbitrary Racket code. @scribble-examples|==={ @foo{a @bar c} @@ -497,19 +497,19 @@ in reverse order with paren-like characters (@litchar{(}, @foo|!!{X |!!@b{Y}...}!!| }===| -Finally, remember that you can use an expression escape with a Scheme +Finally, remember that you can use an expression escape with a Racket string for confusing situations. This works well when you only need to quote short pieces, and the above works well when you have larger multi-line body texts. @;-------------------------------------------------------------------- -@subsection{Scheme Expression Escapes} +@subsection{Racket Expression Escapes} -In some cases, you may want to use a Scheme identifier (or a number or +In some cases, you may want to use a Racket identifier (or a number or a boolean etc.) in a position that touches the following text; in -these situations you should surround the escaped Scheme expression by +these situations you should surround the escaped Racket expression by a pair of @litchar{|} characters. The text inside the bars is -parsed as a Scheme expression. +parsed as a Racket expression. @scribble-examples|==={ @foo{foo@bar.} @@ -518,7 +518,7 @@ parsed as a Scheme expression. @foo{foo@|3|.} }===| -This form is a generic Scheme expression escape, there is no body text +This form is a generic Racket expression escape, there is no body text or datum part when you use this form. @scribble-examples|==={ @@ -552,8 +552,8 @@ you want to control the sub expressions in the form. }===| Note that @litchar["@|{...}|"] can be parsed as either an escape expression or -as the Scheme command part of a @"@"-form. The latter is used in this case -(since there is little point in Scheme code that uses braces. +as the Racket command part of a @"@"-form. The latter is used in this case +(since there is little point in Racket code that uses braces. @scribble-examples|==={ @|{blah}| @@ -603,7 +603,7 @@ for spaces between a @litchar["{"] and text, or between text and a A single newline that follows an open brace or precedes a closing brace is discarded, unless there are only newlines in the body; other -newlines are read as a @scheme["\n"] string +newlines are read as a @racket["\n"] string @scribble-examples|==={ @foo{bar @@ -631,7 +631,7 @@ newlines are read as a @scheme["\n"] string }===| In the parsed S-expression syntax, a single newline string is used for -all newlines; you can use @scheme[eq?] to identify this line. This +all newlines; you can use @racket[eq?] to identify this line. This can be used to identify newlines in the original @nonterm{text-body}. @; FIXME: unfortunate code duplication (again): @@ -641,7 +641,7 @@ can be used to identify newlines in the original @nonterm{text-body}. @#,tt[" }"])]) (for-each (lambda (x) (display (if (eq? x nl) "\n... " x))) @#,tt["@`{foo"] - @#,elem[@tt[" @"] @scheme[,@(list "bar" "\n" "baz")]] + @#,elem[@tt[" @"] @racket[,@(list "bar" "\n" "baz")]] @#,tt[" blah}}"]) (newline)) (let ([nl (car @'{ @@ -658,7 +658,7 @@ S-expressions, but the column of each line is noticed, and all-space indentation strings are added so the result has the same indentation. A indentation string is added to each line according to its distance from the leftmost syntax object (except for empty lines). (Note: if -you try these examples on a mzscheme REPL, you should be aware that +you try these examples on a Racket REPL, you should be aware that the reader does not know about the ``@litchar{> }'' prompt.) @scribble-examples|==={ @@ -722,11 +722,11 @@ example, in }===| a formatter will need to apply the 2-space indentation to the -rendering of the @scheme[bold] body. +rendering of the @racket[bold] body. Note that to get a first-line text to be counted as a leftmost line, line and column accounting should be on for the input port -(@scheme[use-at-readtable] turns them on for the current input port). +(@racket[use-at-readtable] turns them on for the current input port). Without this, @litchar/lines|==={ @@ -745,7 +745,7 @@ source accounting is not on, but }===| will (due to the last line). Pay attention to this, as it can be a -problem with Scheme code, for example: +problem with Racket code, for example: @litchar/lines|==={ @code{(define (foo x) diff --git a/collects/scribblings/scribble/renderer.scrbl b/collects/scribblings/scribble/renderer.scrbl index f9817b23..dc70576c 100644 --- a/collects/scribblings/scribble/renderer.scrbl +++ b/collects/scribblings/scribble/renderer.scrbl @@ -1,7 +1,7 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-label scheme/class)) + (for-label racket/class)) @(define-syntax-rule (defmodule/local lib . content) (begin @@ -15,7 +15,7 @@ @title[#:tag "renderer"]{Renderer} A renderer is an object that provides two main methods: -@scheme[collect] and @scheme[render]. The first method is called to +@racket[collect] and @racket[render]. The first method is called to collect global information about the document, including information that spans multiple documents rendered together; the collection pass tends to be format-independent, and it usually implemented completely @@ -25,20 +25,20 @@ which is naturally specific to a particular format. @section{Base Renderer} @defmodule[scribble/base-render]{The -@schememodname[scribble/base-render] module provides @scheme[render%], +@racketmodname[scribble/base-render] module provides @racket[render%], which implements the core of a renderer. This rendering class must be -refined with a mixin from @schememodname[scribble/text-render], -@schememodname[scribble/html-render], or -@schememodname[scribble/latex-render].} +refined with a mixin from @racketmodname[scribble/text-render], +@racketmodname[scribble/html-render], or +@racketmodname[scribble/latex-render].} The mixin structure is meant to support document-specific extensions to the renderers. For example, the @exec{scribble} command-line tool might, in the future, extract rendering mixins from a document module (in addition to the document proper). -See the @filepath{base-render.ss} source for more information about +See the @filepath{base-render.rkt} source for more information about the methods of the renderer. Documents built with higher layers, such -as @schememodname[scribble/manual], generally do not call the render +as @racketmodname[scribble/manual], generally do not call the render object's methods directly. @defclass[render% object% ()]{ @@ -49,15 +49,15 @@ Represents a renderer. [refer-to-existing-files any/c #f] [root-path (or/c path-string? false/c) #f])]{ -Creates a renderer whose output will go to @scheme[dest-dir]. For -example, @scheme[dest-dir] could name the directory containing the +Creates a renderer whose output will go to @racket[dest-dir]. For +example, @racket[dest-dir] could name the directory containing the output Latex file, the HTML file for a single-file output, or the output sub-directory for multi-file HTML output. -If @scheme[root-path] is not @scheme[#f], it is normally the same as -@scheme[dest-dir] or a parent of @scheme[dest-dir]. It causes +If @racket[root-path] is not @racket[#f], it is normally the same as +@racket[dest-dir] or a parent of @racket[dest-dir]. It causes cross-reference information to record destination files relative to -@scheme[root-path]; when cross-reference information is serialized, it +@racket[root-path]; when cross-reference information is serialized, it can be deserialized via @method[render% deserialize-info] with a different root path (indicating that the destination files have moved).} @@ -68,7 +68,7 @@ moved).} collect-info?]{ Performs the @techlink{collect pass}. See @method[render% render] for -information on the @scheme[dests] argument.} +information on the @racket[dests] argument.} @defmethod[(resolve [srcs (listof part?)] [dests (listof path-string?)] @@ -76,7 +76,7 @@ information on the @scheme[dests] argument.} resolve-info?]{ Performs the @techlink{resolve pass}. See @method[render% render] for -information on the @scheme[dests] argument.} +information on the @racket[dests] argument.} @defmethod[(render [srcs (listof part?)] [dests (listof path-string?)] @@ -85,29 +85,29 @@ information on the @scheme[dests] argument.} Produces the final output. -The @scheme[dests] provide names of files for Latex or single-file +The @racket[dests] provide names of files for Latex or single-file HTML output, or names of sub-directories for multi-file HTML output. -If the @scheme[dests] are relative, they're relative to the current +If the @racket[dests] are relative, they're relative to the current directory; normally, they should indicates a path within the -@scheme[_dest-dir] supplied on initialization of the @scheme[render%] +@racket[_dest-dir] supplied on initialization of the @racket[render%] object.} @defmethod[(serialize-info [ri resolve-info?]) any/c]{ -Serializes the collected info in @scheme[ri].} +Serializes the collected info in @racket[ri].} @defmethod[(deserialize-info [v any/c] [ci collect-info?] [#:root root-path (or/c path-string? false/c) #f]) void?]{ -Adds the deserialized form of @scheme[v] to @scheme[ci]. +Adds the deserialized form of @racket[v] to @racket[ci]. -If @scheme[root-path] is not @scheme[#f], then file paths that are -recorded in @scheme[ci] as relative to an instantiation-supplied -@scheme[root-path] are deserialized as relative instead to the given -@scheme[root-path].} +If @racket[root-path] is not @racket[#f], then file paths that are +recorded in @racket[ci] as relative to an instantiation-supplied +@racket[root-path] are deserialized as relative instead to the given +@racket[root-path].} } @@ -119,7 +119,7 @@ recorded in @scheme[ci] as relative to an instantiation-supplied @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating plain text.}} +Specializes a @racket[render%] class for generating plain text.}} @; ---------------------------------------- @@ -129,21 +129,21 @@ Specializes a @scheme[render%] class for generating plain text.}} @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating HTML output. +Specializes a @racket[render%] class for generating HTML output. @defmethod[(set-external-tag-path [url string?]) void?]{ Configures the renderer to redirect links to external via -@scheme[url], adding a @scheme[tag] query element to the end of the -URL that contains the Base64-encoded, @scheme[print]ed, serialized -original tag (in the sense of @scheme[link-element]) for the link.} +@racket[url], adding a @racket[tag] query element to the end of the +URL that contains the Base64-encoded, @racket[print]ed, serialized +original tag (in the sense of @racket[link-element]) for the link.} } @defmixin[render-multi-mixin (render%) ()]{ Further specializes a rendering class produced by -@scheme[render-mixin] for generating multiple HTML +@racket[render-mixin] for generating multiple HTML files.} } @@ -156,4 +156,4 @@ files.} @defmixin[render-mixin (render%) ()]{ -Specializes a @scheme[render%] class for generating Latex input.}} +Specializes a @racket[render%] class for generating Latex input.}} diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl index 4f98ff2b..7925e321 100644 --- a/collects/scribblings/scribble/scheme.scrbl +++ b/collects/scribblings/scribble/scheme.scrbl @@ -1,157 +1,167 @@ #lang scribble/doc @(require scribble/manual "utils.ss" - (for-label scribble/scheme)) + (for-label scribble/racket)) -@title[#:tag "scheme"]{Scheme} +@title[#:tag "scheme"]{Racket} -@defmodule[scribble/scheme]{The @scheme[scribble/scheme] library -provides utilities for typesetting Scheme code. The -@scheme[scribble/manual] forms provide a higher-level interface.} +@defmodule*[(scribble/racket scribble/scheme)]{The +@racket[scribble/racket] library (or @racketmodname[scribble/scheme] +for backward compatibility) provides utilities for typesetting Racket +code. The @racket[scribble/manual] forms provide a higher-level +interface.} @defform*[[(define-code id typeset-expr) (define-code id typeset-expr uncode-id) (define-code id typeset-expr uncode-id d->s-expr) (define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)]]{ -Binds @scheme[id] to a form similar to @scheme[scheme] or -@scheme[schemeblock] for typesetting code. The form generated by -@scheme[define-code] handles source-location information, escapes via -@scheme[unquote], preservation of binding and property information, +Binds @racket[id] to a form similar to @racket[racket] or +@racket[racketblock] for typesetting code. The form generated by +@racket[define-code] handles source-location information, escapes via +@racket[unquote], preservation of binding and property information, and @tech{element transformers}. -The supplied @scheme[typeset-expr] expression should produce a +The supplied @racket[typeset-expr] expression should produce a procedure that performs the actual typesetting. This expression is -normally @scheme[to-element] or @scheme[to-paragraph]. The argument -supplied to @scheme[typeset-expr] is normally a syntax object, but -more generally it is the result of applying @scheme[d->s-expr]. +normally @racket[to-element] or @racket[to-paragraph]. The argument +supplied to @racket[typeset-expr] is normally a syntax object, but +more generally it is the result of applying @racket[d->s-expr]. -The optional @scheme[uncode-id] specifies the escape from literal code -to be recognized by @scheme[id]. The default is @scheme[unsyntax]. +The optional @racket[uncode-id] specifies the escape from literal code +to be recognized by @racket[id]. The default is @racket[unsyntax]. -The optional @scheme[d->s-expr] should produce a procedure that -accepts three arguments suitable for @scheme[datum->syntax]: a syntax -object or @scheme[#f], an arbitrary value, and a vector for a source +The optional @racket[d->s-expr] should produce a procedure that +accepts three arguments suitable for @racket[datum->syntax]: a syntax +object or @racket[#f], an arbitrary value, and a vector for a source location. The result should record as much or as little of the -argument information as needed by @scheme[typeset-expr] to typeset the -code. Normally, @scheme[d->s-expr] is @scheme[datum->syntax]. +argument information as needed by @racket[typeset-expr] to typeset the +code. Normally, @racket[d->s-expr] is @racket[datum->syntax]. -The @scheme[stx-prop-expr] should produce a procedure for recording a -@scheme['paren-shape] property when the source expression uses with -@scheme[id] has such a property. The default is -@scheme[syntax-property].} +The @racket[stx-prop-expr] should produce a procedure for recording a +@racket['paren-shape] property when the source expression uses with +@racket[id] has such a property. The default is +@racket[syntax-property].} -@defproc[(to-paragraph [v any/c]) block?]{ +@defproc[(to-paragraph [v any/c] [#:qq? qq? any/c #f]) block?]{ Typesets an S-expression that is represented by a syntax object, where source-location information in the syntax object controls the generated layout. -Identifiers that have @scheme[for-label] bindings are typeset and +Identifiers that have @racket[for-label] bindings are typeset and hyperlinked based on definitions declared elsewhere (via -@scheme[defproc], @scheme[defform], etc.). The identifiers -@schemeidfont{code:line}, @schemeidfont{code:comment}, and -@schemeidfont{code:blank} are handled as in @scheme[schemeblock], as +@racket[defproc], @racket[defform], etc.). The identifiers +@racketidfont{code:line}, @racketidfont{code:comment}, +@racketidfont{code:blank}, @racketidfont{code:hilite}, and +@racketidfont{code:quote} are handled as in @racket[racketblock], as are identifiers that start with @litchar{_}. -In addition, the given @scheme[v] can contain @scheme[var-id], -@scheme[shaped-parens], @scheme[just-context], or -@scheme[literal-syntax] structures to be typeset specially (see each -structure type for details), or it can contain @scheme[element] -structures that are used directly in the output.} +In addition, the given @racket[v] can contain @racket[var-id], +@racket[shaped-parens], @racket[just-context], or +@racket[literal-syntax] structures to be typeset specially (see each +structure type for details), or it can contain @racket[element] +structures that are used directly in the output. + +If @racket[qq?] is true, then @racket[v] is rendered ``quasiquote'' +style, much like @racket[print] with the @racket[print-as-quasiquote] +parameter set to @racket[#t]. In that case, @racket[for-label] +bindings on identifiers are ignored, since the identifiers are all +quoted in the output. Typically, @racket[qq?] is set to true for +printing result values.} -@defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c]) +@defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c] [#:qq? qq? any/c #f]) [v any/c]) block?]{ -Like @scheme[to-paragraph], but @scheme[prefix1] is prefixed onto the -first line, @scheme[prefix] is prefix to any subsequent line, and -@scheme[suffix] is added to the end. The @scheme[prefix1], -@scheme[prefix], and @scheme[suffix] arguments are used as -@tech{content}, except that if @scheme[suffix] is a list of elements, +Like @racket[to-paragraph], but @racket[prefix1] is prefixed onto the +first line, @racket[prefix] is prefix to any subsequent line, and +@racket[suffix] is added to the end. The @racket[prefix1], +@racket[prefix], and @racket[suffix] arguments are used as +@tech{content}, except that if @racket[suffix] is a list of elements, it is added to the end on its own line.} -@defproc[(to-element [v any/c]) element?]{ +@defproc[(to-element [v any/c] [#:qq? qq? any/c #f]) element?]{ -Like @scheme[to-paragraph], except that source-location information is +Like @racket[to-paragraph], except that source-location information is mostly ignored, since the result is meant to be inlined into a paragraph.} -@defproc[(to-element/no-color [v any/c]) element?]{ +@defproc[(to-element/no-color [v any/c] [#:qq? qq? any/c #f]) element?]{ -Like @scheme[to-element], but @scheme[for-syntax] bindings are +Like @racket[to-element], but @racket[for-syntax] bindings are ignored, and the generated text is uncolored. This variant is typically used to typeset results.} @defstruct[var-id ([sym (or/c symbol? identifier?)])]{ -When @scheme[to-paragraph] and variants encounter a @scheme[var-id] -structure, it is typeset as @scheme[sym] in the variable font, like -@scheme[schemevarfont]---unless the @scheme[var-id] appears under -quote or quasiquote, in which case @scheme[sym] is typeset as a symbol.} +When @racket[to-paragraph] and variants encounter a @racket[var-id] +structure, it is typeset as @racket[sym] in the variable font, like +@racket[racketvarfont]---unless the @racket[var-id] appears under +quote or quasiquote, in which case @racket[sym] is typeset as a symbol.} @defstruct[shaped-parens ([val any/c] [shape char?])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[shaped-parens] structure, it is typeset like a syntax object -that has a @scheme['paren-shape] property with value @scheme[shape].} +When @racket[to-paragraph] and variants encounter a +@racket[shaped-parens] structure, it is typeset like a syntax object +that has a @racket['paren-shape] property with value @racket[shape].} @defstruct[just-context ([val any/c] [context syntax?])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[just-context] structure, it is typeset using the -source-location information of @scheme[val] just the lexical context -of @scheme[ctx].} +When @racket[to-paragraph] and variants encounter a +@racket[just-context] structure, it is typeset using the +source-location information of @racket[val] just the lexical context +of @racket[ctx].} @defstruct[literal-syntax ([stx any/c])]{ -When @scheme[to-paragraph] and variants encounter a -@scheme[literal-syntax] structure, it is typeset as the string form of -@scheme[stx]. This can be used to typeset a syntax-object value in the +When @racket[to-paragraph] and variants encounter a +@racket[literal-syntax] structure, it is typeset as the string form of +@racket[stx]. This can be used to typeset a syntax-object value in the way that the default printer would represent the value.} @defproc[(element-id-transformer? [v any/c]) boolean?]{ -Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an +Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an @tech{element transformer} created by -@scheme[make-element-id-transformer], @scheme[#f] otherwise.} +@racket[make-element-id-transformer], @racket[#f] otherwise.} @defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)]) element-id-transformer?]{ -Provided @scheme[for-syntax]; creates an @deftech{element +Provided @racket[for-syntax]; creates an @deftech{element transformer}. When an identifier has a transformer binding to an @tech{element transformer}, then forms generated by -@scheme[define-code] (including @scheme[scheme] and -@scheme[schemeblock]) typeset the identifier by applying the -@scheme[proc] to the identifier. The result must be an expression -whose value, typically an @scheme[element], is passed on to functions -like @scheme[to-paragraph] .} +@racket[define-code] (including @racket[racket] and +@racket[racketblock]) typeset the identifier by applying the +@racket[proc] to the identifier. The result must be an expression +whose value, typically an @racket[element], is passed on to functions +like @racket[to-paragraph] .} @defproc[(variable-id? [v any/c]) boolean?]{ -Provided @scheme[for-syntax]; returns @scheme[#t] if @scheme[v] is an -@tech{element transformer} created by @scheme[make-variable-id], -@scheme[#f] otherwise.} +Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an +@tech{element transformer} created by @racket[make-variable-id], +@racket[#f] otherwise.} @defproc[(make-variable-id [sym (or/c symbol? identifier?)]) variable-id?]{ -Provided @scheme[for-syntax]; like @scheme[make-element-id-transformer] for -a transformer that produces @scheme[sym] typeset as a variable (like -@scheme[schemevarfont])---unless it appears under quote or quasiquote, -in which case @scheme[sym] is typeset as a symbol.} +Provided @racket[for-syntax]; like @racket[make-element-id-transformer] for +a transformer that produces @racket[sym] typeset as a variable (like +@racket[racketvarfont])---unless it appears under quote or quasiquote, +in which case @racket[sym] is typeset as a symbol.} @deftogether[( @defthing[output-color style?] @@ -177,4 +187,4 @@ in which case @scheme[sym] is typeset as a symbol.} @defthing[highlighted-color style?] )]{ -Styles that are used for coloring Scheme programs, results, and I/O.} +Styles that are used for coloring Racket programs, results, and I/O.} diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl index 3df63292..2527a382 100644 --- a/collects/scribblings/scribble/scribble.scrbl +++ b/collects/scribblings/scribble/scribble.scrbl @@ -2,7 +2,7 @@ @(require scribble/bnf "utils.ss") -@title{@bold{Scribble}: PLT Documentation Tool} +@title{@bold{Scribble}: Racket Documentation Tool} @author["Matthew Flatt" "Eli Barzilay"] @@ -15,7 +15,7 @@ programmatically. This document itself is written using Scribble. At the time that it was written, its source was available at -@(let ([url "http://svn.plt-scheme.org/plt/trunk/collects/scribblings/scribble/"]) +@(let ([url "http://git.racket-lang.org/plt/tree/HEAD:/collects/scribblings/scribble"]) (link url url)) starting with the @filepath{scribble.scrbl} file. diff --git a/collects/scribblings/scribble/sigplan.scrbl b/collects/scribblings/scribble/sigplan.scrbl index d9fe6c90..49f2a450 100644 --- a/collects/scribblings/scribble/sigplan.scrbl +++ b/collects/scribblings/scribble/sigplan.scrbl @@ -4,16 +4,16 @@ @title{SIGPLAN Paper Format} -@defmodulelang[scribble/sigplan]{The @schememodname[scribble/sigplan] -language is like @schememodname[scribble/manual], but configured with +@defmodulelang[scribble/sigplan]{The @racketmodname[scribble/sigplan] +language is like @racketmodname[scribble/manual], but configured with Latex style defaults to use the @filepath{sigplanconf.cls} class file that is included with Scribble.} @defidform[preprint]{ -Enables the @tt{preprint} option. Use @scheme[preprint] only on the +Enables the @tt{preprint} option. Use @racket[preprint] only on the same line as @hash-lang[], with only whitespace between -@schememodname[scribble/sigplan] and @scheme[preprint]: +@racketmodname[scribble/sigplan] and @racket[preprint]: @verbatim[#:indent 2]|{ #lang scribble/sigplan @preprint @@ -21,15 +21,15 @@ same line as @hash-lang[], with only whitespace between @defidform[10pt]{ -Enables the @tt{10pt} option. Use @scheme[10pt] only on the +Enables the @tt{10pt} option. Use @racket[10pt] only on the same line as @hash-lang[], with only whitespace between -@schememodname[scribble/sigplan] and @scheme[10pt]: +@racketmodname[scribble/sigplan] and @racket[10pt]: @verbatim[#:indent 2]|{ #lang scribble/sigplan @10pt }| -The @scheme[10pt] and @scheme[preprint] options can be +The @racket[10pt] and @racket[preprint] options can be used together and may appear in any order. } @@ -40,7 +40,7 @@ Generates a @tech{nested flow} for a paper abstract.} @defform[(include-abstract module-path)]{ -Similar to @scheme[include-section], but incorporates the document in the +Similar to @racket[include-section], but incorporates the document in the specified module as an abstract. The document must have no title or sub-parts.} @@ -49,7 +49,7 @@ sub-parts.} [email pre-content?]) block?]{ -A replacement for @scheme[author] that associates an affiliation and +A replacement for @racket[author] that associates an affiliation and e-mail address with the author name.} @deftogether[( @@ -71,4 +71,4 @@ Declares information that is collected into the copyright region of the paper.} )]{ Typesets category, term, and keyword information for the paper, which -is normally placed immediately after an @scheme[abstract] form.} +is normally placed immediately after an @racket[abstract] form.} diff --git a/collects/scribblings/scribble/srcdoc.scrbl b/collects/scribblings/scribble/srcdoc.scrbl index 4cccf754..a5048c36 100644 --- a/collects/scribblings/scribble/srcdoc.scrbl +++ b/collects/scribblings/scribble/srcdoc.scrbl @@ -3,25 +3,25 @@ "utils.ss" (for-label scribble/srcdoc scribble/extract - scheme/contract)) + racket/contract)) @title[#:tag "srcdoc"]{In-Source Documentation} -The @schememodname[scribble/srcdoc] and -@schememodname[scribble/extract] libraries support writing +The @racketmodname[scribble/srcdoc] and +@racketmodname[scribble/extract] libraries support writing documentation withing the documentation code along with an export contract, similar to using @as-index{JavaDoc}. With this approach, a single contract specification is used both for the run-time contract and the documentation of an exported binding. -The @schememodname[scribble/srcdoc] library provides forms for +The @racketmodname[scribble/srcdoc] library provides forms for exporting a binding with associated documentation. The -@scheme[scribble/extract] library is used to pull -@scheme[scribble/srcdoc]-based documentation into a Scribble document +@racket[scribble/extract] library is used to pull +@racket[scribble/srcdoc]-based documentation into a Scribble document (perhaps for multiple libraries). Although documentation is written with a library's implementation when -using @schememodname[scribble/srcdoc], the documentation creates no +using @racketmodname[scribble/srcdoc], the documentation creates no run-time overhead for the library. Similarly, typesetting the documentation does not require running the library. The two phases (run time versus documentation time) are kept separate in much the @@ -29,7 +29,7 @@ same way that the module system keeps expansion-time code separate from run-time code. For an example use, see the @filepath{file} collection's -@filepath{gif.ss} source file and the corresponding extraction in +@filepath{gif.rkt} source file and the corresponding extraction in @filepath{scribblings/gif.scrbl}. As that example illustrates, prefixing the module declaration with @@ -48,26 +48,26 @@ expressions. @defform[(provide/doc spec ...)]{ -Like @scheme[provide] or @scheme[provide/contract], but each -@scheme[spec] uses a @deftech{documentation transformer} to describe +Like @racket[provide] or @racket[provide/contract], but each +@racket[spec] uses a @deftech{documentation transformer} to describe the exported identifier and its contract. The currently supported @tech{documentation transformers} are -@scheme[proc-doc], @scheme[proc-doc/names], @scheme[parameter-doc], -and @scheme[thing-doc].} +@racket[proc-doc], @racket[proc-doc/names], @racket[parameter-doc], +and @racket[thing-doc].} @defform[(require/doc require-spec ...)]{ -Like @scheme[require], but for bindings that are needed at +Like @racket[require], but for bindings that are needed at documentation time (and documentation-expansion time, etc.) instead of -run time (and expansion time, etc.). A @scheme[require-doc] form has +run time (and expansion time, etc.). A @racket[require-doc] form has no effect on a normal use of the library; it affects only documentation extraction. -Typically, a library that uses @schememodname[scribble/srcdoc] -includes at least @scheme[(require/doc scribble/base scribble/manual)] -to get core Scheme forms and basic Scribble functions to use in +Typically, a library that uses @racketmodname[scribble/srcdoc] +includes at least @racket[(require/doc scribble/base scribble/manual)] +to get core Racket forms and basic Scribble functions to use in documentation expressions.} @defform*/subs[#:literals (-> ->* case->) @@ -81,27 +81,27 @@ documentation expressions.} (code:line keyword contract-expr)] [case-contract (case-> (-> arg ... result) ...)])]{ -When used in @scheme[provide/doc], exports @scheme[id] with the -contract described by @scheme[contract] or @scheme[case-contract], -just like using @scheme[provide/contract]. +When used in @racket[provide/doc], exports @racket[id] with the +contract described by @racket[contract] or @racket[case-contract], +just like using @racket[provide/contract]. -The @scheme[arg-id]s specify the names of arguments, which are not +The @racket[arg-id]s specify the names of arguments, which are not normally written as part of a contract. They are combined with the contract expression to generate the description of the binding in the -documentation via @scheme[defproc]. The @scheme[(arg-id default-expr)] +documentation via @racket[defproc]. The @racket[(arg-id default-expr)] pairs specify the names and default values of the optional arguments. -The @scheme[desc-expr] is a documentation-time expression that +The @racket[desc-expr] is a documentation-time expression that produces prose to describe the exported binding---that is, the last -part of the generated @scheme[defproc], so the description can refer -to the @scheme[arg-id]s using @scheme[scheme]. +part of the generated @racket[defproc], so the description can refer +to the @racket[arg-id]s using @racket[racket]. -The normal @scheme[require]s of the enclosing library are effectively -converted into @scheme[for-label] @scheme[require]s when generating -documentation, so that identifiers in the @scheme[contract]s are +The normal @racket[require]s of the enclosing library are effectively +converted into @racket[for-label] @racket[require]s when generating +documentation, so that identifiers in the @racket[contract]s are linked to their corresponding documentation. Similarly, any binding that is available in the run-time phase of of the enclosing library -can be referenced in documentation prose using the @scheme[scheme] +can be referenced in documentation prose using the @racket[racket] form.} @defform/subs[#:literals (-> ->d values) @@ -113,18 +113,18 @@ form.} (->d (arg ...) () #:pre-cond expression [id result]) (->d (arg ...) () #:rest id rest [id result])])]{ -Like @scheme[proc-doc], but supporting contract forms that embed -argument names. Only a subset of @scheme[->d] forms are currently +Like @racket[proc-doc], but supporting contract forms that embed +argument names. Only a subset of @racket[->d] forms are currently supported.} @defform[(thing-doc id contract-expr dec-expr)]{ -Like @scheme[proc-doc], but for an export of an arbitrary value.} +Like @racket[proc-doc], but for an export of an arbitrary value.} @defform[#:literals (parameter/c) (parameter-doc id (parameter/c contract-expr) arg-id desc-expr)]{ -Like @scheme[proc-doc], but for exporting a parameter.} +Like @racket[proc-doc], but for exporting a parameter.} @; ---------------------------------------- @@ -135,26 +135,26 @@ Like @scheme[proc-doc], but for exporting a parameter.} @defform[(include-extracted module-path)]{ Expands to a sequence of documentation forms extracted from -@scheme[module-path], which is expected to be a module that uses -@schememodname[scribble/srcdoc].} +@racket[module-path], which is expected to be a module that uses +@racketmodname[scribble/srcdoc].} @defform[(provide-extracted module-path)]{ -Similar to @scheme[include-extracted], but the documentation is -packaged and exported as @scheme[exported], instead of left +Similar to @racket[include-extracted], but the documentation is +packaged and exported as @racket[exported], instead of left inline. Use this form in combination with -@scheme[include-previously-extracted] when documentation from a single +@racket[include-previously-extracted] when documentation from a single source is to be split and typeset among multiple documentation -locations. The @scheme[provide-extracted] form extracts the -documentation once, and then @scheme[include-previously-extracted] +locations. The @racket[provide-extracted] form extracts the +documentation once, and then @racket[include-previously-extracted] form extracts documentation for specific bindings as needed.} @defform[(include-previously-extracted module-path regexp)]{ -Similar to @scheme[include-extracted], but instead of referring to the -source that contains its own documentation, @scheme[module-path] -refers to a module that uses @scheme[provide-extracted]. The -@scheme[include-previously-extracted] form expands to documentation -forms for all identifiers whose string forms match @scheme[regexp].} +Similar to @racket[include-extracted], but instead of referring to the +source that contains its own documentation, @racket[module-path] +refers to a module that uses @racket[provide-extracted]. The +@racket[include-previously-extracted] form expands to documentation +forms for all identifiers whose string forms match @racket[regexp].} diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl index fa34ef3e..8ce08ad8 100644 --- a/collects/scribblings/scribble/struct.scrbl +++ b/collects/scribblings/scribble/struct.scrbl @@ -14,18 +14,18 @@ @(define (compat) @italic{For backward compatibility.}) @(define-syntax-rule (compat/comp id) - @elem{@compat[] Compared to the normal constructor for @scheme[id]}) + @elem{@compat[] Compared to the normal constructor for @racket[id]}) @title[#:tag "struct"]{Compatibility Structures And Processing} @defmodule[scribble/struct]{ -The @scheme[scribble/struct] compatibility library mostly re-exports -@scheme[scribble/core], but using some different names (e.g., -@scheme[blockquote] instead of @scheme[nested-flow]).} +The @racket[scribble/struct] compatibility library mostly re-exports +@racket[scribble/core], but using some different names (e.g., +@racket[blockquote] instead of @racket[nested-flow]).} The following structure types and functions are re-exported directly: -@schemeblock[collect-info resolve-info tag? block? +@racketblock[collect-info resolve-info tag? block? delayed-block collected-info delayed-element ; delayed-element-content delayed-block-blocks current-serialize-resolve-info part-relative-element collect-info-parents ; part-relative-element-content delayed-index-desc collect-element render-element generated-tag ; generate-tag current-tag-prefixes add-current-tag-prefix @@ -38,7 +38,7 @@ The following structure types and functions are re-exported directly: The following structure types are re-exported, but the constructors and some selectors are replaced as documented further below: -@schemeblock[part paragraph table itemization compound-paragraph +@racketblock[part paragraph table itemization compound-paragraph element toc-element target-element toc-target-element page-target-element redirect-target-element link-element index-element] @@ -55,14 +55,14 @@ also exported. [parts (listof part?)]) part?]{ -@compat/comp[part], parses @scheme[style] to convert old formats to -the current one. Also, if @scheme[title-content] is a list with a +@compat/comp[part], parses @racket[style] to convert old formats to +the current one. Also, if @racket[title-content] is a list with a single item, the item by itself is stored in the resulting -@scheme[part].} +@racket[part].} @defproc[(part-flow [p part?]) (listof block?)]{ -@compat[] An alias for @scheme[part-blocks].} +@compat[] An alias for @racket[part-blocks].} @defproc[(part-title-content [p part?]) list?]{ @@ -82,10 +82,10 @@ coerced to one.} @defproc[(versioned-part? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-part], but adds a the -@scheme[document-version] @tech{style property} using the given -@scheme[version]. The @scheme[versioned-part?] predicate recognizes a -@scheme[part] with a @scheme[document-version] property.} +@compat[] Like @racket[make-part], but adds a the +@racket[document-version] @tech{style property} using the given +@racket[version]. The @racket[versioned-part?] predicate recognizes a +@racket[part] with a @racket[document-version] property.} @deftogether[( @defproc[(make-unnumbered-part [tag-prefix (or/c false/c string?)] @@ -99,16 +99,16 @@ coerced to one.} @defproc[(unnumbered-part? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-part], but adds the @scheme['unnumbered] -@tech{style property}. The @scheme[unnumbered-part?] predicate -recognizes a @scheme[part] with the @scheme['unnumbered] property.} +@compat[] Like @racket[make-part], but adds the @racket['unnumbered] +@tech{style property}. The @racket[unnumbered-part?] predicate +recognizes a @racket[part] with the @racket['unnumbered] property.} @defproc[(make-paragraph [content list?]) paragraph?]{ @compat/comp[paragraph], omits a style argument. Also, if -@scheme[content] is a list containing a single item, the item by -itself is stored in the resulting @scheme[paragraph].} +@racket[content] is a list containing a single item, the item by +itself is stored in the resulting @racket[paragraph].} @defproc[(paragraph-content [p paragraph?]) list?]{ @@ -123,10 +123,10 @@ coerced to one. @defproc[(styled-paragraph-style [p paragraph?]) style?] )]{ -@compat/comp[paragraph], parses @scheme[style] to convert old formats -to the current one. The @scheme[styled-paragraph?] predicate and -@scheme[styled-paragraph-style] accessor are aliases for -@scheme[paragraph?] and @scheme[paragraph-style].} +@compat/comp[paragraph], parses @racket[style] to convert old formats +to the current one. The @racket[styled-paragraph?] predicate and +@racket[styled-paragraph-style] accessor are aliases for +@racket[paragraph?] and @racket[paragraph-style].} @deftogether[( @@ -134,9 +134,9 @@ to the current one. The @scheme[styled-paragraph?] predicate and @defproc[(omitable-paragraph? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-paragraph], but adds the -@scheme['omitable] @tech{style property}. The -@scheme[omitable-paragraph?] predicate checks for a paragraph with the +@compat[] Like @racket[make-paragraph], but adds the +@racket['omitable] @tech{style property}. The +@racket[omitable-paragraph?] predicate checks for a paragraph with the property.} @@ -146,13 +146,13 @@ property.} @compat/comp[table], the style is converted, and each cell has a list of blocks instead of a single block. If any such list has multiple -blocks, they are combined into a @scheme[nested-flow].} +blocks, they are combined into a @racket[nested-flow].} @defproc[(table-flowss [table table?]) (listof (listof (or/c (listof block?) (one-of/c 'cont))))]{ -@compat[] Like @scheme[table-blockss], but adds a list wrapper to be -consistent with @scheme[make-table].} +@compat[] Like @racket[table-blockss], but adds a list wrapper to be +consistent with @racket[make-table].} @defproc[(make-itemization [blockss (listof (listof block?))]) itemization?]{ @@ -165,16 +165,16 @@ consistent with @scheme[make-table].} @defproc[(styled-itemization-style [i itemization?]) style?] )]{ -@compat/comp[itemization], parses @scheme[style] to convert old -formats to the current one. The @scheme[styled-itemization?] predicate -is an alias for @scheme[itemization?], and -@scheme[styled-itemization-style] is an alias for -@scheme[itemization-style].} +@compat/comp[itemization], parses @racket[style] to convert old +formats to the current one. The @racket[styled-itemization?] predicate +is an alias for @racket[itemization?], and +@racket[styled-itemization-style] is an alias for +@racket[itemization-style].} @defproc[(make-blockquote [style any/c][blocks (listof block?)]) nested-flow?]{ -@compat[] Like @scheme[make-nested-flow], but @scheme[style] is +@compat[] Like @racket[make-nested-flow], but @racket[style] is parsed to the current format.} @@ -185,16 +185,16 @@ parsed to the current format.} @defproc[(auxiliary-table? [v any/c]) boolean?] )]{ -@compat[] Like @scheme[make-table], but adds the @scheme['aux] -@tech{style property}. The @scheme[auxiliary-table?] predicate recognizes -tables with the @scheme['aux] property.} +@compat[] Like @racket[make-table], but adds the @racket['aux] +@tech{style property}. The @racket[auxiliary-table?] predicate recognizes +tables with the @racket['aux] property.} @defproc[(make-compound-paragraph [style any/c] [blocks (listof block?)]) compound-paragraph?]{ -@compat/comp[compound-paragraph], parses @scheme[style] to convert old +@compat/comp[compound-paragraph], parses @racket[style] to convert old formats to the current one.} @deftogether[( @@ -211,7 +211,7 @@ formats to the current one.} [entry-seq list?] [desc any/c]) index-element?] )]{ -@compat[] Compared to the normal constructors, parses @scheme[style] to convert old +@compat[] Compared to the normal constructors, parses @racket[style] to convert old formats to the current one.} @@ -222,42 +222,42 @@ formats to the current one.} )]{ @compat[] A @tech{content} list is treated as an element by these functions, -and the result of @scheme[element-content] is always a list.} +and the result of @racket[element-content] is always a list.} @defproc[(make-aux-element [style any/c] [content list?]) element?]{ -@compat[] Like @scheme[make-element], but adds the @scheme['aux] +@compat[] Like @racket[make-element], but adds the @racket['aux] @tech{style property}.} @defproc[(make-hover-element [style any/c] [content list?] [text string?]) element?]{ -@compat[] Like @scheme[make-element], but adds @scheme[hover-property] -containing @scheme[text] to the element's style.} +@compat[] Like @racket[make-element], but adds @racket[hover-property] +containing @racket[text] to the element's style.} @defproc[(make-script-element [style any/c] [content list?] [type string?] [script (or/c path-string? (listof string?))]) element?]{ -@compat[] Like @scheme[make-element], but adds @scheme[script-property] -containing @scheme[type] and @scheme[script] to the element's style.} +@compat[] Like @racket[make-element], but adds @racket[script-property] +containing @racket[type] and @racket[script] to the element's style.} @defstruct[with-attributes ([style any/c] [assoc (listof (cons/c symbol? string?))])]{ -@compat[] Used for an @scheme[element]'s style to combine a base style with -arbitrary HTML attributes. When the @scheme[style] field is itself an -instance of @scheme[with-attributes], its content is automatically -flattened into the enclosing @scheme[with-attributes] when it is used -(when, e.g., rendering an @scheme[element] or @scheme[paragraph]).} +@compat[] Used for an @racket[element]'s style to combine a base style with +arbitrary HTML attributes. When the @racket[style] field is itself an +instance of @racket[with-attributes], its content is automatically +flattened into the enclosing @racket[with-attributes] when it is used +(when, e.g., rendering an @racket[element] or @racket[paragraph]).} @defstruct[target-url ([addr path-string?] [style any/c])]{ -@compat[] Used as a style for an @scheme[element]. The @scheme[style] at this +@compat[] Used as a style for an @racket[element]. The @racket[style] at this layer is a style for the hyperlink.} @@ -265,9 +265,9 @@ layer is a style for the hyperlink.} (cons/c 'collects (listof bytes?)))] [scale real?])]{ -@compat[] Used as a style for an @scheme[element] to inline an image. The -@scheme[path] field can be a result of -@scheme[path->main-collects-relative].} +@compat[] Used as a style for an @racket[element] to inline an image. The +@racket[path] field can be a result of +@racket[path->main-collects-relative].} @@ -275,6 +275,6 @@ layer is a style for the hyperlink.} @defproc*[([(element->string (element content?)) string?] [(element->string (element content?) (renderer any/c) (p part?) (info resolve-info?)) string?])]{ -@compat[] An alias for @scheme[content->string]. +@compat[] An alias for @racket[content->string]. } diff --git a/collects/scribblings/scribble/utils.ss b/collects/scribblings/scribble/utils.rkt similarity index 97% rename from collects/scribblings/scribble/utils.ss rename to collects/scribblings/scribble/utils.rkt index 02d78579..c0c9ac31 100644 --- a/collects/scribblings/scribble/utils.ss +++ b/collects/scribblings/scribble/utils.rkt @@ -1,9 +1,9 @@ -#lang scheme/base +#lang racket/base (require scribble/core scribble/html-properties scribble/manual - (prefix-in scheme: scribble/scheme) + (prefix-in racket: scribble/racket) (prefix-in scribble: scribble/reader)) (define-syntax bounce-for-label @@ -15,12 +15,12 @@ (provide (for-label (all-from-out mod))))] [(_ mod ...) (begin (bounce-for-label mod) ...)])) -(bounce-for-label (all-except scheme (link) ()) +(bounce-for-label (all-except racket (link) ()) scribble/core scribble/base-render scribble/decode scribble/manual - scribble/scheme + scribble/racket scribble/html-properties scribble/latex-properties scribble/eval @@ -94,7 +94,7 @@ (map (lambda (x) (let ([@expr (if x (litchar/lines (car x)) "")] [sexpr (if x - (scheme:to-paragraph + (racket:to-paragraph ((norm-spacing 0) (cadr x))) "")] [reads-as (if x reads-as "")]) @@ -103,7 +103,7 @@ ;; stuff for the preprocessor examples -(require scheme/list (for-syntax scheme/base scheme/list)) +(require racket/list (for-syntax racket/base racket/list)) (define max-textsample-width 45) diff --git a/collects/scribblings/scribble/xref.scrbl b/collects/scribblings/scribble/xref.scrbl index 6956616f..ec9100c7 100644 --- a/collects/scribblings/scribble/xref.scrbl +++ b/collects/scribblings/scribble/xref.scrbl @@ -8,7 +8,7 @@ @title[#:tag "xref"]{Cross-Reference Utilities} -@defmodule[scribble/xref]{The @schememodname[scribble/xref] library +@defmodule[scribble/xref]{The @racketmodname[scribble/xref] library provides utilities for querying cross-reference information that was collected from a document build.} @@ -16,8 +16,8 @@ collected from a document build.} @defproc[(xref? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a cross-reference record created -by @scheme[load-xref], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a cross-reference record created +by @racket[load-xref], @racket[#f] otherwise.} @defproc[(load-xref [sources (listof (-> any/c))] @@ -28,18 +28,18 @@ by @scheme[load-xref], @scheme[#f] otherwise.} Creates a cross-reference record given a list of functions that each produce a serialized information obtained from @xmethod[render% -serialize-info]. If a @scheme[sources] element produces @scheme[#f], +serialize-info]. If a @racket[sources] element produces @racket[#f], its result is ignored. Since the format of serialized information is specific to a rendering -class, the optional @scheme[using-render%] argument accepts the +class, the optional @racket[using-render%] argument accepts the relevant class. It default to HTML rendering. -If @scheme[root-path] is not @scheme[#f], then file paths that are -serialized as relative to an instantiation-supplied @scheme[root-path] -are deserialized as relative instead to the given @scheme[root-path]. +If @racket[root-path] is not @racket[#f], then file paths that are +serialized as relative to an instantiation-supplied @racket[root-path] +are deserialized as relative instead to the given @racket[root-path]. -Use @scheme[load-collections-xref] from @schememodname[setup/xref] to +Use @racket[load-collections-xref] from @racketmodname[setup/xref] to get all cross-reference information for installed documentation.} @@ -58,7 +58,7 @@ get all cross-reference information for installed documentation.} [mode (or/c exact-integer? false/c)]) (or/c tag? false/c)]{ -Locates a tag in @scheme[xref] that documents a module export. The +Locates a tag in @racket[xref] that documents a module export. The binding is specified in one of several ways, as described below; all possibilities encode an exporting module and a symbolic name. The name must be exported from the specified module. Documentation is found @@ -66,35 +66,35 @@ either for the specified module or, if the exported name is re-exported from other other module, for the other module (transitively). -The @scheme[mode] argument specifies the relevant phase level for the -binding. The @scheme[binding] is specified in one of four ways: +The @racket[mode] argument specifies the relevant phase level for the +binding. The @racket[binding] is specified in one of four ways: @itemize[ - @item{If @scheme[binding] is an identifier, then - @scheme[identifier-binding] is used with @scheme[mode] to + @item{If @racket[binding] is an identifier, then + @racket[identifier-binding] is used with @racket[mode] to determine the binding.} - @item{If @scheme[binding] is a two-element list, then the first + @item{If @racket[binding] is a two-element list, then the first element provides the exporting module and the second the - exported name. The @scheme[mode] argument is effectively + exported name. The @racket[mode] argument is effectively ignored.} - @item{If @scheme[binding] is a seven-element list, then it corresponds - to a result from @scheme[identifier-binding] using - @scheme[mode].} + @item{If @racket[binding] is a seven-element list, then it corresponds + to a result from @racket[identifier-binding] using + @racket[mode].} - @item{If @scheme[binding] is a five-element list, then the first + @item{If @racket[binding] is a five-element list, then the first element is as for the two-element-list case, and the remain elements are as in the last four elements of the seven-element case.} ] -If a documentation point exists in @scheme[xref], a tag is returned, -which might be used with @scheme[xref-tag->path+anchor] or embedded in -a document rendered via @scheme[xref-render]. If no definition point -is found in @scheme[xref], the result is @scheme[#f].} +If a documentation point exists in @racket[xref], a tag is returned, +which might be used with @racket[xref-tag->path+anchor] or embedded in +a document rendered via @racket[xref-render]. If no definition point +is found in @racket[xref], the result is @racket[#f].} @defproc[(xref-tag->path+anchor [xref xref?] @@ -104,24 +104,24 @@ is found in @scheme[xref], the result is @scheme[#f].} (values (or/c false/c path?) (or/c false/c string?))]{ -Returns a path and anchor string designated by the key @scheme[tag] -according the cross-reference @scheme[xref]. The first result is -@scheme[#f] if no mapping is found for the given tag. The second -result is @scheme[#f] if the first result is @scheme[#f], and it can -also be @scheme[#f] if the tag refers to a page rather than a specific +Returns a path and anchor string designated by the key @racket[tag] +according the cross-reference @racket[xref]. The first result is +@racket[#f] if no mapping is found for the given tag. The second +result is @racket[#f] if the first result is @racket[#f], and it can +also be @racket[#f] if the tag refers to a page rather than a specific point in a page. -The optional @scheme[using-render%] argument is as for -@scheme[load-xref].} +The optional @racket[using-render%] argument is as for +@racket[load-xref].} @defproc[(xref-tag->index-entry [xref xref?] [tag tag?]) (or/c false/c entry?)]{ -Extract an @scheme[entry] structure that provides addition information -about the definition (of any) referenced by @scheme[tag]. This -function can be composed with @scheme[xref-binding->definition-tag] to +Extract an @racket[entry] structure that provides addition information +about the definition (of any) referenced by @racket[tag]. This +function can be composed with @racket[xref-binding->definition-tag] to obtain information about a binding, such as the library that exports the binding and its original name.} @@ -134,22 +134,22 @@ the binding and its original name.} [#:refer-to-existing-files? use-existing? any/c (not dest)]) (or/c void? any/c)]{ -Renders @scheme[doc] using the cross-reference info in @scheme[xref] -to the destination @scheme[dest]. For example, @scheme[doc] might be a +Renders @racket[doc] using the cross-reference info in @racket[xref] +to the destination @racket[dest]. For example, @racket[doc] might be a generated document of search results using link tags described in -@scheme[xref]. +@racket[xref]. -If @scheme[dest] is @scheme[#f], no file is written, and the result is +If @racket[dest] is @racket[#f], no file is written, and the result is an X-expression for the rendered page. Otherwise, the file -@scheme[dest] is written and the result is @|void-const|. +@racket[dest] is written and the result is @|void-const|. -The optional @scheme[using-render%] argument is as for -@scheme[load-xref]. It determines the kind of output that is +The optional @racket[using-render%] argument is as for +@racket[load-xref]. It determines the kind of output that is generated. -If @scheme[use-existing?] is true, then files referenced during +If @racket[use-existing?] is true, then files referenced during rendering (such as image files) are referenced from their existing -locations, instead of copying to the directory of @scheme[dest].} +locations, instead of copying to the directory of @racket[dest].} @defproc[(xref-transfer-info [renderer (is-a?/c render%)] @@ -157,15 +157,15 @@ locations, instead of copying to the directory of @scheme[dest].} [xref xref?]) void?]{ -Transfers cross-reference information to @scheme[ci], which is the -initially collected information from @scheme[renderer].} +Transfers cross-reference information to @racket[ci], which is the +initially collected information from @racket[renderer].} @defproc[(xref-index [xref xref?]) (listof entry?)]{ -Converts indexing information @scheme[xref] into a list of -@scheme[entry] structures.} +Converts indexing information @racket[xref] into a list of +@racket[entry] structures.} @defstruct[entry ([words (and/c (listof string?) cons?)] @@ -175,8 +175,8 @@ Converts indexing information @scheme[xref] into a list of Represents a single entry in a Scribble document index. -The @scheme[words] list corresponds to -@scheme[index-element-plain-seq]. The @scheme[content] list -corresponds to @scheme[index-element-entry-seq]. The @scheme[desc] -value corresponds to @scheme[index-element-desc]. The @scheme[tag] is +The @racket[words] list corresponds to +@racket[index-element-plain-seq]. The @racket[content] list +corresponds to @racket[index-element-entry-seq]. The @racket[desc] +value corresponds to @racket[index-element-desc]. The @racket[tag] is the destination for the index link into the main document.} diff --git a/collects/scriblib/autobib.ss b/collects/scriblib/autobib.rkt similarity index 99% rename from collects/scriblib/autobib.ss rename to collects/scriblib/autobib.rkt index 9c8de65a..367449b1 100644 --- a/collects/scriblib/autobib.ss +++ b/collects/scriblib/autobib.rkt @@ -36,7 +36,7 @@ (lambda (renderer part ri) (let ([s (resolve-get part ri `(,which ,(auto-bib-key bib-entry)))]) (list (make-link-element #f - (list s (auto-bib-specific bib-entry)) + (list (or s "???") (auto-bib-specific bib-entry)) `(autobib ,(auto-bib-key bib-entry)))))) (lambda () "(???)") (lambda () "(???)"))) diff --git a/collects/scriblib/figure.ss b/collects/scriblib/figure.rkt similarity index 100% rename from collects/scriblib/figure.ss rename to collects/scriblib/figure.rkt diff --git a/collects/scriblib/figure.tex b/collects/scriblib/figure.tex index 429e996d..04e90fac 100644 --- a/collects/scriblib/figure.tex +++ b/collects/scriblib/figure.tex @@ -9,7 +9,7 @@ \newlength{\FigOrigskip} \FigOrigskip=\parskip -\newenvironment{CenterfigureMulti}{\begin{figure*}\centering}{\end{figure*}} +\newenvironment{CenterfigureMulti}{\begin{figure*}[htp]\centering}{\end{figure*}} \newenvironment{CenterfigureMultiWide}{\begin{CenterfigureMulti}}{\end{CenterfigureMulti}} -\newenvironment{Centerfigure}{\begin{figure}\centering}{\end{figure}} +\newenvironment{Centerfigure}{\begin{figure}[htp]\centering}{\end{figure}} \newenvironment{FigureInside}{\begin{list}{}{\leftmargin=0pt\topsep=0pt\parsep=\FigOrigskip\partopsep=0pt}\item}{\end{list}} diff --git a/collects/scriblib/gui-eval.ss b/collects/scriblib/gui-eval.rkt similarity index 92% rename from collects/scriblib/gui-eval.ss rename to collects/scriblib/gui-eval.rkt index a18629f7..49d988c4 100644 --- a/collects/scriblib/gui-eval.ss +++ b/collects/scriblib/gui-eval.rkt @@ -1,14 +1,14 @@ -#lang scheme/base +#lang racket/base (require scribble/eval scribble/core scribble/scheme - scheme/class - scheme/file - scheme/runtime-path - scheme/serialize + racket/class + racket/file + racket/runtime-path + racket/serialize "private/gui-eval-exn.ss" - scheme/system) + racket/system) (define-syntax define-mr (syntax-rules () @@ -28,13 +28,16 @@ (define-mr gui-interaction-eval-show interaction-eval-show) (define-mr gui-def+int def+int) (define-mr gui-defs+int defs+int) -(define-mr gui-schememod+eval schememod+eval) -(define-mr gui-schemeblock+eval schemeblock+eval) +(define-mr gui-racketmod+eval racketmod+eval) +(define-mr gui-racketblock+eval racketblock+eval) + +(provide (rename-out [gui-racketmod+eval gui-schememod+eval] + [gui-racketblock+eval gui-schemeblock+eval])) (define mred? (getenv "MREVAL")) (when mred? - (gui-eval '(require scheme/gui/base)) + (gui-eval '(require racket/gui/base)) (gui-eval '(require slideshow))) ;; This one needs to be relative, because it ends up in the diff --git a/collects/scriblib/private/counter.ss b/collects/scriblib/private/counter.rkt similarity index 100% rename from collects/scriblib/private/counter.ss rename to collects/scriblib/private/counter.rkt diff --git a/collects/scriblib/private/gui-eval-exn.ss b/collects/scriblib/private/gui-eval-exn.rkt similarity index 100% rename from collects/scriblib/private/gui-eval-exn.ss rename to collects/scriblib/private/gui-eval-exn.rkt diff --git a/collects/scriblib/scribblings/gui-eval.scrbl b/collects/scriblib/scribblings/gui-eval.scrbl index 84d1e06e..f6a86f80 100644 --- a/collects/scriblib/scribblings/gui-eval.scrbl +++ b/collects/scriblib/scribblings/gui-eval.scrbl @@ -7,7 +7,7 @@ @schememodname[scriblib/gui-eval] library support example evaluations with results that are @schememodname[slideshow] picts.} -The trick is that @schememodname[scheme/gui] is not generally +The trick is that @schememodname[racket/gui] is not generally available when rendering documentation, because it requires a GUI context. The picture output is rendered to an image file when the @envvar{MREVAL} environment variable is set, so run the enclosing @@ -27,5 +27,5 @@ generated image. Like @scheme[interaction], etc., but actually evaluating the forms only when the @envvar{MREVAL} environment variable is set, and then in -an evaluator that is initialized with @schememodname[scheme/gui/base] +an evaluator that is initialized with @schememodname[racket/gui/base] and @schememodname[slideshow]. } diff --git a/collects/scriblib/scribblings/info.ss b/collects/scriblib/scribblings/info.rkt similarity index 100% rename from collects/scriblib/scribblings/info.ss rename to collects/scriblib/scribblings/info.rkt diff --git a/collects/tests/scribble/collect.ss b/collects/tests/scribble/collect.rkt similarity index 100% rename from collects/tests/scribble/collect.ss rename to collects/tests/scribble/collect.rkt diff --git a/collects/tests/scribble/main.ss b/collects/tests/scribble/main.rkt similarity index 100% rename from collects/tests/scribble/main.ss rename to collects/tests/scribble/main.rkt diff --git a/collects/tests/scribble/preprocessor.ss b/collects/tests/scribble/preprocessor.rkt similarity index 100% rename from collects/tests/scribble/preprocessor.ss rename to collects/tests/scribble/preprocessor.rkt diff --git a/collects/tests/scribble/reader.ss b/collects/tests/scribble/reader.rkt similarity index 99% rename from collects/tests/scribble/reader.ss rename to collects/tests/scribble/reader.rkt index 29e6d7a7..53ea81e3 100644 --- a/collects/tests/scribble/reader.ss +++ b/collects/tests/scribble/reader.rkt @@ -920,7 +920,7 @@ END-OF-TESTS ;; remove all comment lines [ts (regexp-replace* #px"(?m:^;.*\r?\n)" ts "")] ;; split the tests - [ts (regexp-split #px"(?:^|\r?\n)-+(?:$|\r?\n)" ts)]) + [ts (regexp-split #px"(?m:^)-+(?:$|\r?\n)" ts)]) (parameterize ([port-count-lines-enabled #t]) (for ([t ts] #:when (not (regexp-match? #px"^\\s*$" t))) (let ([m (or (regexp-match #px"^(.*)\n\\s*(-\\S+->)\\s*\n(.*)$"