diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.css b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.css index 75b47e81..8b137891 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.css +++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.css @@ -1,5 +1 @@ -.Shaded { - width: 100%; - background-color: #E8E8FF; -} diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.tex b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.tex index 4814ac88..c7002ea4 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.tex +++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.tex @@ -1,5 +1,2 @@ -\newenvironment{Shaded}{}{} \newcommand{\Short}[1]{\begin{minipage}[c]{6ex}#1\end{minipage}} -\newcommand{\Medium}[1]{\begin{minipage}[c]{20ex}#1\end{minipage}} - diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl index 3b4fd69a..ce373185 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl +++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/text.scrbl @@ -1,22 +1,34 @@ #lang scribble/doc @(require scribble/manual scribble/core scribble/html-properties scribble/latex-properties - "utils.rkt" - (for-label racket/base - ;; FIXME: need to get this in - ;; scribble/text - )) + (except-in "utils.rkt" splice begin include) + (for-label (except-in racket/base begin) + scribble/text + (only-in scribble/text + [begin/text begin] + [include/text include]))) @initialize-tests +@(define (tech/r s) @tech[s #:doc '(lib "scribblings/reference/reference.scrbl")]) + +@(define-syntax-rule (def-rkt t-id) + (begin + (require (for-label racket/include)) + (define t-id @racket[include]))) +@(def-rkt rkt-include) + @title[#:tag "text" #:style (make-style #f (list (make-tex-addition "shaded.tex") (make-css-addition "shaded.css"))) ]{Text Generation} @section-index["Preprocessor"] -@defmodulelang[scribble/text]{The @racketmodname[scribble/text] language -provides everything from @racket[racket/base] with a few changes that -make it suitable as a text generation or a preprocessor language: +@defmodulelang[scribble/text]{The @racketmodname[scribble/text] +language provides everything from @racket[racket/base], +@racket[racket/promise], @racket[racket/list], and +@racket[racket/string], but with additions and a changed treatment of +the module top level to make it suitable as for text generation or a +preprocessor language: @itemize[ @@ -33,6 +45,12 @@ make it suitable as a text generation or a preprocessor language: } +When @racketmodname[scribble/text] is used via @racket[require] +instead of @hash-lang[], then it does not change the printing of +values, it does not include the bindings of @racket[racket/base], +@racket[include] is provided as @racket[include/text], and +@racket[begin] is provided as @racket[begin/text]. + @; TODO: @; * make all example sections be subsections, @; * add a reference section, @@ -1197,3 +1215,130 @@ Racket-with-@"@"-expressions file as shown above.) ... and to that I say "Foo!", I think. Repeating yourself much? }-| + +@;-------------------------------------------------------------------- +@section{Text Generation Functions} + +@defproc[(output [v any/c] [port output-port? (current-output-port)]) void?]{ + +Outputs values to @racket[port] as follows for each kind of @racket[v]: + + @itemlist[ + + @item{@tech/r{strings}, @tech/r{byte strings}, @tech/r{symbols}, + @tech/r{paths}, @tech/r{keywords}, @tech/r{numbers}, and + @tech/r{characters}: converts the value to a string along the + same lines as @racket[display], and then passes the string to + the @deftech{current writer}, which is initially + @racket[display]} + + @item{@|void-const|, @racket[#f], or @racket[null]: no output} + + @item{@tech/r{list}: output depends on the current mode, which is + initially @tech{splice mode}: + + @itemlist[ + + @item{@deftech{block mode}: each item in order, using the + starting column as the @deftech{current + indentation} (which starts out empty)} + + @item{@deftech{splice mode}: outputs each item in order} + + ]} + + @item{@racket[(block _v2 ...)]: outputs each @racket[_v2] in @tech{block mode}.} + + @item{@racket[(splice _v2 ...)]: outputs each @racket[_v2] in @tech{splice mode}.} + + @item{@racket[(set-prefix _pfx _v2 ...)]: sets the @deftech{current + prefix}, which is initially empty, to @racket[_pfx] while + outputting each @racket[_v2].} + + @item{@racket[(add-prefix _pfx _v2 ...)]: sets the @tech{current + prefix} to by adding @racket[_pfx] while outputting each + @racket[_v2].} + + @item{@racket[(disable-prefix _v2 ...)]: sets the @tech{current + prefix} to empty while outputting each @racket[_v2].} + + @item{@racket[(restore-prefix _v2 ...)]: rewinds the + @tech{current prefix} by one enclosing adjustments while + outputting each @racket[_v2].} + + @item{@racket[flush]: outputs the @tech{current indentation} and @tech{current prefix}.} + + @item{@racket[(with-writer _writer _v2 ...)]: sets the @tech{current writer} + to @racket[_writer] with outputting each @racket[_v2].} + + @item{@tech/r{promise}: outputs the result of @racket[(force v)]} + + @item{@tech/r{box}: outputs the result of @racket[(unbox v)]} + + @item{procedure of 0 arguments: outputs the result of @racket[(v)]} + +]} + +@defproc[(block [v any/c] ...) any/c]{ + +Produces a value that outputs each @racket[v] in @tech{block mode}.} + +@defproc[(splice [v any/c] ...) any/c]{ + +Produces a value that outputs each @racket[v] in @tech{splice mode}.} + +@deftogether[( +@defproc[(disable-prefix [v any/c] ...) any/c] +@defproc[(restore-prefix [v any/c] ...) any/c] +@defproc[(add-prefix [pfx (or/c string? exact-nonnegative-integer?)] [v any/c] ...) any/c] +@defproc[(set-prefix [pfx (or/c string? exact-nonnegative-integer?)] [v any/c] ...) any/c] +)]{ + +Produces a value that outputs with an adjusted @tech{current prefix}. +An integer as a prefix is equivalent to a string with as many space +characters.} + + +@defthing[flush void?]{ + +A value that outputs as the @tech{current indentation} plus @tech{current prefix}.} + + +@defproc[(with-writer [writer (string? . -> . any/c)] [v any/c] ...) any/c]{ + +Produces a value that outputs with an adjusted @tech{current writer}.} + + +@defproc[(add-newlines [items list?] [#:sep sep an/y "\n"]) list?]{ + +Like @racket[add-between], but first removes @racket[#f] and @|void-const| +elements of @racket[items].} + + +@defproc[(split-lines [items list?]) (listof list?)]{ + +Converts @racket[items] to a list of lists, where consecutive +non-@racket["\n"] values are kept together in a nested list, and +@racket["\n"] values are dropped.} + + +@defform[(include/text maybe-char path-spec) + #:grammar ([maybe-char code:blank + (code:line #:command-char command-char)])]{ + +Like @rkt-include from @racketmodname[racket/include], but reads the +file at @racket[path-spec] in the same way as for +@racketmodname[scribble/text]. If @racket[command-char] is supplied, +then it replaces @litchar["@"] as the escape character. + +The @racketmodname[scribble/text] language via @hash-lang[] provides +@racket[include/text] as @racket[include].} + +@defform[(begin/text form ...)]{ + +Like @racket[begin], but the results of expression @racket[forms] are +collected into a list that is returned as the result of the +@racket[begin/list] form. + +The @racketmodname[scribble/text] language via @hash-lang[] provides +@racket[begin/text] as @racket[begin].} diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/utils.rkt b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/utils.rkt index 1ae1c999..f1acb71d 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/utils.rkt +++ b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/utils.rkt @@ -115,20 +115,20 @@ (define (str->elts str) (let ([spaces (regexp-match-positions #rx"(?:^| ) +" str)]) (if spaces - (list* (substring str 0 (caar spaces)) - (hspace (- (cdar spaces) (caar spaces))) + (list* (str->elts (substring str 0 (caar spaces))) + (smaller (hspace (- (cdar spaces) (caar spaces)))) (str->elts (substring str (cdar spaces)))) - (list (make-element 'tt (list str)))))) + (list (smaller (make-element 'tt str)))))) (define (make-line str) - (if (equal? str "") - ;;FIXME: this works in html, but in latex it creates a redundant newline - (list (as-flow (make-element 'newline '()))) - (list (as-flow (make-element 'tt (str->elts str)))))) - (define (small-attr attr) - (make-style attr (list - (make-attributes '([style . "font-size: 82%;"]))))) - (define (make-box strs) - (make-table (small-attr "Shaded") (map make-line strs))) + (list (as-flow (if (equal? str "") + (smaller (hspace 1)) + (str->elts str))))) + (define (make-box strs [file #f]) + (nested #:style 'code-inset + (let ([t (make-table plain (map make-line strs))]) + (if file + (filebox file t) + t)))) (define filenames (map car more)) (define indent (let ([d (- max-textsample-width (for*/fold ([m 0]) @@ -144,19 +144,10 @@ (values (make-table (make-style #f - (list (make-table-columns (list (make-style (if (null? filenames) - "Short" - "Medium") - '(right top)) - (make-style #f '(left top)))))) - (cons (list (as-flow (make-table (small-attr #f) - (list (list (as-flow indent))))) - (as-flow (make-box strs1))) + (list (make-table-columns (list (make-style #f '(left top)))))) + (cons (list (as-flow (make-box strs1))) (map (lambda (file strs) - (let* ([file (make-element 'tt (list file ":" 'nbsp))] - [file (list (make-element 'italic (list file)))]) - (list (as-flow (make-element (make-style #f (list (make-background-color-property '(232 232 255)))) file)) - (as-flow (make-box strs))))) + (list (as-flow (make-box strs file)))) filenames strsm))) (make-box strs2)))