Scribble overview: mention tables comments, and pictures

original commit: 44e55689a26bfc46aa0febdbb41d377344452d8b

collects/scribble/base.rkt

@@ -426,7 +426,8 @@
                 #:rest (listof pre-flow?)
                 compound-paragraph?)]
  [tabular (->* ((listof (listof (or/c 'cont block? content?))))
-               (#:style (or/c style? string? symbol? #f ))
+               (#:style (or/c style? string? symbol? #f)
+                #:sep (or/c content? block? #f))
                table?)])
 
 (define (convert-block-style style)
@@ -447,7 +448,7 @@
   (make-compound-paragraph (convert-block-style style)
                            (decode-flow c)))
 
-(define (tabular #:style [style #f] cells)
+(define (tabular #:style [style #f] #:sep [sep #f] cells)
   (define (nth-str pos)
     (case (modulo pos 10)
       [(1) "st"]
@@ -476,12 +477,15 @@
        row)))
   (make-table (convert-block-style style)
               (map (lambda (row)
-                     (map (lambda (cell)
+                     (define (cvt cell)
                        (cond
                         [(eq? cell 'cont) cell]
                         [(block? cell) cell]
                         [else (make-paragraph plain cell)]))
-                          row))
+                     (define l (map cvt row))
+                     (if sep
+                         (add-between l (cvt sep))
+                         l))
                    cells)))
 
 ;; ----------------------------------------

collects/scribblings/scribble/base.scrbl

@@ -240,13 +240,18 @@ Returns @racket[#t] if @racket[v] is an item produced by
 
 
 @defproc[(tabular [cells (listof (listof (or/c block? content? 'cont)))]
-                  [#:style style (or/c style? string? symbol? #f) #f]) 
+                  [#:style style (or/c style? string? symbol? #f) #f]
+                  [#:sep sep (or/c block? content? #f) #f])
          table?]{
 
 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.
 
+If @racket[sep] is not @racket[#f], it is inserted between every
+column in the table. Otherwise, the default style places no space
+between table columns.
+
 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 @racket['cont] must not appear as the first cell in a row.

collects/scribblings/scribble/core.scrbl

@@ -502,6 +502,8 @@ The currently recognized @tech{style properties} are as follows:
 @defstruct[table ([style style?]
                   [blockss (listof (listof (or/c block? (one-of/c 'cont))))])]{
 
+See also the @racket[tabular] function.
+
 A @techlink{table} has, roughly, a list of list of blocks. A cell in
 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

collects/scribblings/scribble/how-to-paper.scrbl

@@ -1,5 +1,6 @@
 #lang scribble/doc
 @(require scribble/manual scribble/bnf "utils.rkt"
+          slideshow/pict
           (for-label scriblib/figure scribble/base scribble/sigplan))
 
 @(define-syntax-rule (samplemod . text) (codeblock . text))
@@ -8,6 +9,10 @@
      "#lang scribble/base" "\n" a . text))
 @(define (result . text) (apply nested #:style 'inset text))
 
+@(define sep @hspace[1])
+
+@(define sub*section subsection)
+
 @title[#:tag "getting-started"]{Getting Started}
 
 No matter what you want to do with Scribble, it's best to start by
@@ -223,11 +228,11 @@ lexically scoped.
 @; ----------------------------------------
 @section{More Functions}
 
-The @racketmodname[scribble/sigplan] and
+The @racketmodname[scribble/base] language provides a collection of
-@racketmodname[scribble/manual] languages are supersets of the
+basic operations (and The @racketmodname[scribble/sigplan] and
-@racketmodname[scribble/base] language, which provides a collection of
+@racketmodname[scribble/manual] are supersets of
-basic operations. Many of the operations are style variations that you
+@racketmodname[scribble/base]). Many of the operations are style
-can apply to text:
+variations that you can apply to text:
 
           @sample|{
             He's a @smaller{small mouse}. The glass is too
@@ -251,6 +256,8 @@ can also be nested within calls to @racket[title] or @racket[section]:
             @section{@italic{Not} the Last Straw}
           }|
 
+@sub*section{Centering}
+
 The @racket[centered] operation centers a flow of text:
 
          @sample|{
@@ -275,12 +282,15 @@ which renders as
            and see if anyone brings you more.
        }
 
+@sub*section{Margin Notes}
+
 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 @racket[margin-note], then the content shows
-@margin-note{If you use @racket[margin-note], then the content shows
              up over here.}
 
+@sub*section{Itemizations}
+
 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
@@ -307,6 +317,29 @@ which renders as
                            you must bring your own straw.}]
          }
 
+@sub*section{Tables}
+
+The @racket[tabular] function takes a list of lists to organize into a
+two-dimensional table. By default, no spacing is added between columns,
+so supply a @racket[#:sep] argument to acts as a column separator.
+For example,
+
+   @sample|{
+     @tabular[#:sep @hspace[1]
+              (list (list @bold{Animal} @bold{Food})
+                    (list "mouse"       "cookie")
+                    (list "moose"       "muffin"))]
+   }|
+
+else
+
+   @result{
+     @tabular[#:sep @hspace[1]
+              (list (list @bold{Animal} @bold{Food})
+                    (list "mouse"       "cookie")
+                    (list "moose"       "muffin"))]
+   }
+
 @; ----------------------------------------
 @section{Text Mode vs. Racket Mode for Arguments}
 
@@ -496,6 +529,17 @@ like @racket[section] or @racket[italic] accepts content to typeset,
 it normally accepts an arbitrary number of arguments that together
 form the content.
 
+In addition to its role for command, a @litchar["@"] can be followed
+by @litchar{;} to start a @index['("Scribble"
+"comments")]{comment}. If the character after @litchar{;} is
+@litchar["{"], then the comment runs until a matching @litchar["}"],
+otherwise the comment runs until the end-of-line:
+
+@racketblock[
+ @#,BNF-seq[@litchar["@;{"] @nonterm{comment} @litchar["}"]]
+ @#,BNF-seq[@litchar["@;"]  @nonterm{line-comment}]
+]
+
 For more information on the syntax of @litchar["@"], see
 @secref["reader"]. The full syntax includes a few more details, such
 as brackets like @litchar["|{"]...@litchar["}|"] for text-mode
@@ -595,6 +639,30 @@ renders as
       @verbatim|{@(number->string (+ 1 2))}|
   }
 
+
+@; ----------------------------------------
+@section[#:tag "pictures"]{Pictures}
+
+Any value that is convertable to an image can be used directly within
+a Scribble document. Functions from the @racketmodname[slideshow/pict]
+and @racketmodname[2htdp/image] libraries, for example, generate
+images. For example,
+
+@sample|{
+  @(require slideshow/pict)
+
+  This cookie has lost its chocolate chips: 
+  @(colorize (filled-ellipse 40 40) "beige").
+}|
+
+renders as
+
+ @result{
+   This cookie has lost its chocolate chips:
+   @(colorize (filled-ellipse 40 40) "beige").
+ }
+
+
 @; ----------------------------------------
 @section[#:tag "roadmap"]{Next Steps}