add 'filebox' Scribble function

original commit: bb2611559163dbb80c7d1736785fa381be9f316c

collects/scribble/private/manual-scheme.rkt

@@ -65,16 +65,13 @@
                                                      ',#'lang
                                                      (to-element ',#'lang))
                                                    #'(racket lang)))))
-                            #'lang)]
+                            #'lang)])
-                   [(file ...)
        (if (syntax-e #'filename)
-                        (list
+           (quasisyntax/loc stx
-                         (datum->syntax
+             (filebox
-                          #'filename
+              filename
-                          `(code:comment (unsyntax (t "In \"" ,(syntax-e #'filename) "\":")))
+              #,(syntax/loc stx (racketblock0 modtag rest ...))))
-                          #'filename))
+           (syntax/loc stx (racketblock modtag rest ...))))]
-                        null)])
-       (syntax/loc stx (racketblock file ... modtag rest ...)))]
     [(_ lang rest ...)
      (syntax/loc stx (racketmod #:file #f lang rest ...))]))
 

collects/scribble/private/manual-style.rkt

@@ -4,9 +4,12 @@
          "../base.ss"
          (only-in "../basic.ss" aux-elem itemize)
          "../scheme.ss"
-         (only-in "../core.ss" make-style plain)
+         (only-in "../core.ss" make-style plain
+                  make-nested-flow
+                  [element? core:element?])
          "manual-utils.ss"
          "on-demand.ss"
+         "manual-sprop.rkt"
          racket/list
          racket/contract
          racket/string)
@@ -18,6 +21,7 @@
          (rename-out [image image/plain])
          itemize
          aux-elem)
+(provide/contract [filebox ((or/c core:element? string?) pre-flow? . -> . block?)])
 
 (define styling-f/c
   (() () #:rest (listof pre-content?) . ->* . element?))
@@ -210,3 +214,20 @@
             [(eq? i 'rsquo) (list 'prime)]
             [else (list i)])))
       c))))
+
+(define (filebox filename . inside)
+  (make-nested-flow 
+   (make-style "Sfilebox" scheme-properties)
+   (list
+    (make-styled-paragraph 
+     (list (make-element
+            (make-style "Sfilename" scheme-properties)
+            (if (string? filename)
+                (filepath filename)
+                filename)))
+     (make-style "Sfiletitle" scheme-properties))
+    (make-nested-flow 
+     (make-style "Sfilecontent" scheme-properties)
+     (decode-flow inside)))))
+
+

collects/scribble/racket.rkt

@@ -270,7 +270,10 @@
            [line (or (syntax-line first) 0)])
       (define (finish-line!)
         (when multi-line?
-          (set! docs (cons (make-paragraph omitable (reverse content))
+          (set! docs (cons (make-paragraph omitable 
+                                           (if (null? content)
+                                               (list (hspace 1))
+                                               (reverse content)))
                            docs))
           (set! content null)))
       (define out

collects/scribble/scheme.css

@@ -164,3 +164,25 @@
  margin-left: 1em;
  margin-right: 1em;
 }
+
+.Sfilebox {
+  margin-left: 1em;
+  margin-right: 1em;
+}
+
+.Sfiletitle {
+  text-align: right;
+  margin: 0em 0em 0em 0em;
+}
+
+.Sfilename {
+  border-top: 1px solid #6C8585;
+  border-right: 1px solid #6C8585;
+  padding-left: 0.5em;
+  padding-right: 0.5em;
+  background-color: #ECF5F5;
+}
+
+.Sfilecontent {
+  margin: 0em 0em 0em 0em;
+}

collects/scribblings/scribble/manual.scrbl

@@ -143,12 +143,21 @@ without insetting the code.}
 @defform[(racketinput datum ...)]{Like @racket[racketblock], but the
 @racket[datum] are typeset after a prompt representing a REPL.}
 
-@defform[(racketmod lang datum ...)]{Like @racket[racketblock], but
+@defform/subs[(racketmod maybe-file lang datum ...)
-the @racket[datum] are typeset inside a @racketmodfont{#lang}-form
+              ([maybe-file code:blank
-module whose language is @racket[lang]. The source location of
+                           (code:line #:file filename-expr)])]{
-@racket[lang] (relative to the body @racket[datum]s) determines the
+
-relative positioning of the @racketmodfont{#lang} line in the typeset
+Like @racket[racketblock], but the @racket[datum] are typeset inside a
-output.}
+@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. So, line up
+@racket[lang] with the left end of the content code.
+
+If @racket[#:file] is provided, then the code block is typeset using
+@racket[filebox] with @racket[filename-expr] as the filename
+argument.}
 
 @defform[(racket datum ...)]{Like @racket[racketblock], but typeset on
 a single line and wrapped with its enclosing paragraph, independent of
@@ -1189,6 +1198,14 @@ An alias for @racket[centered] for backward compatibility.}
 
  ]}
 
+@defproc[(filebox [filename (or/c string? element?)] [pre-flow pre-flow?] ...)
+         block?]{
+
+Typesets the @racket[pre-flow]s as the content of
+@racket[filename]. For example, the content may be inset on the page
+with @racket[filename] above it. If @racket[filename] is a string, it
+is passed to @racket{filepath} to obtain an @tech{element}.}
+
 @; ------------------------------------------------------------------------
 @section[#:tag "index-entries"]{Index-Entry Descriptions}