scribble/text: finish documentation

original commit: cdb5c9dfdb50f6cb4dab09be11f3f46b81c32d59

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/shaded.css

@@ -1,5 +1 @@
 
-.Shaded {
-  width: 100%;
-  background-color: #E8E8FF;
-}

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

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"
+          (except-in "utils.rkt" splice begin include)
-          (for-label racket/base
+          (for-label (except-in racket/base begin)
-                     ;; FIXME: need to get this in
+                     scribble/text
-                     ;; 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
+@defmodulelang[scribble/text]{The @racketmodname[scribble/text]
-provides everything from @racket[racket/base] with a few changes that
+language provides everything from @racket[racket/base],
-make it suitable as a text generation or a preprocessor language:
+@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].}

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))
+        (list* (str->elts (substring str 0 (caar spaces)))
-               (hspace (- (cdar spaces) (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 "")
+    (list (as-flow (if (equal? str "")
-      ;;FIXME: this works in html, but in latex it creates a redundant newline
+                       (smaller (hspace 1))
-      (list (as-flow (make-element 'newline '())))
+                       (str->elts str)))))
-      (list (as-flow (make-element 'tt (str->elts str))))))
+  (define (make-box strs [file #f])
-  (define (small-attr attr)
+    (nested #:style 'code-inset
-    (make-style attr (list
+            (let ([t (make-table plain (map make-line strs))])
-                      (make-attributes '([style . "font-size: 82%;"])))))
+              (if file
-  (define (make-box strs)
+                  (filebox file t)
-    (make-table (small-attr "Shaded") (map make-line strs)))
+                  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)
+                 (list (make-table-columns (list (make-style #f '(left top))))))
-                                                                 "Short"
+     (cons (list (as-flow (make-box strs1)))
-                                                                 "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)))
            (map (lambda (file strs)
-                  (let* ([file (make-element 'tt (list file ":" 'nbsp))]
+                  (list (as-flow (make-box strs file))))
-                         [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)))))
                 filenames strsm)))
    (make-box strs2)))