commit ff459128d494448dc8c324c4c9b09b195993fd66
parent d3734342412792107bd54148d19c09c1d4ae352e
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 23 Sep 2012 11:53:30 -0500
Scribble overview: mention tables comments, and pictures
original commit: 44e55689a26bfc46aa0febdbb41d377344452d8b
Diffstat:
4 files changed, 95 insertions(+), 16 deletions(-)
diff --git a/collects/scribble/base.rkt b/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)
- (cond
- [(eq? cell 'cont) cell]
- [(block? cell) cell]
- [else (make-paragraph plain cell)]))
- row))
+ (define (cvt cell)
+ (cond
+ [(eq? cell 'cont) cell]
+ [(block? cell) cell]
+ [else (make-paragraph plain cell)]))
+ (define l (map cvt row))
+ (if sep
+ (add-between l (cvt sep))
+ l))
cells)))
;; ----------------------------------------
diff --git a/collects/scribblings/scribble/base.scrbl b/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.
diff --git a/collects/scribblings/scribble/core.scrbl b/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
diff --git a/collects/scribblings/scribble/how-to-paper.scrbl b/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
-@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:
+The @racketmodname[scribble/base] language provides a collection of
+basic operations (and The @racketmodname[scribble/sigplan] and
+@racketmodname[scribble/manual] are supersets of
+@racketmodname[scribble/base]). Many of the operations are style
+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}
