[Style] some of Robby's suggestions

collects/scribblings/style/constructs.scrbl

@@ -42,9 +42,10 @@ racket
 @; -----------------------------------------------------------------------------
 @section{Conditionals}
 
-Like definitional constructs, conditionals come in many flavors, too. Because
+Like definitional constructs, conditionals come in many flavors,
-@scheme[cond] and its relatives now allow local uses of @scheme[define], you
+too. Because @scheme[cond] and its relatives (@scheme[case],
-should prefer them over @scheme[if].
+@scheme[match], etc) now allow local uses of @scheme[define], you should
+prefer them over @scheme[if].
 
 @compare[
 @racketmod[#:file
@@ -71,3 +72,6 @@ racket
 	   (curved fst (chk rst)))))
 ]
 ]
+
+Of course you should also favor @scheme[cond] (and its relatives) over
+@scheme[if] to match the shape of the data definition.

collects/scribblings/style/correct-maintain-speed.scrbl

@@ -123,8 +123,8 @@ Making code fast is an endless task.
 Making code @emph{reasonably} fast is the goal.
 
 It is especially the goal for all pieces of the code base that are reused
- elsewhere. Write them using @racketmod[racket] so that they don't affect
+ elsewhere. Write them using @rkt/base[] so that they don't affect the
- the load-time for scripts. See the next section.
+ load-time for scripts. See the next section.
 
 As with correctness, performance demands some "testing". At a minimum,
  exercise your code on some reasonably large inputs. Add a file to the test
@@ -156,5 +156,7 @@ And as you read on, keep in mind that we are not perfectionists. We produce
 So what is the major lesson of this section? When you fix a bug, make sure
  to commit (1) the code delta, (2) the new test case, and (3) the revised
  docs (if applicable) in one batch. If the creation of a single commit is
- to complex, please push all pieces at once so that the readers can see how
+ too complex of if you wish to factor out one of the commits, please push
- things belong together.
+ all pieces at once. That way the code base is always in a state where
+ code, tests, and documentation are in sync, and readers of commit messages
+ can evaluate changes completely.

collects/scribblings/style/shared.rkt

@@ -1,8 +1,9 @@
-#lang racket
+#lang s-exp racket
 
 ; things to be shared among all sections of the style guide
 
 (require (for-label racket)
+         scribble/base
          scribble/manual
          scribble/struct
          (only-in scribble/core table-columns style)
@@ -12,10 +13,17 @@
 (provide (for-label (all-from-out racket))
          (all-from-out scribble/manual))
 
-(provide compare)
+(provide
+  compare ;; create a comparison box for two code snippets
+  ;; good    ;; label a code fragment 'good' [doesn't work]
+  ;; bad     ;; label a code fragment 'bad' [doesn't work]
+  rkt rkt/base rkt/gui)
 
-;; compare: two elements,
+(define (rkt) (racketmodname racket))
+(define (rkt/base) (racketmodname racket/base))
+(define (rkt/gui) (racketmodname racket/gui))
 
+;; compare: two code snippets, in two columns: left is good, right is bad
 (define (compare stuff1 stuff2)
   (define stuff (list (list stuff1) (list stuff2)))
   (define space (style #f (list (attributes '((width . "500") (valign . "top"))))))
@@ -25,3 +33,35 @@
            (attributes '((border . "1") (cellpadding . "10")))
            (table-columns (make-list (length stuff) space))))
    (apply map (compose make-flow list) stuff)))
+
+;; ===================================================================================================
+;; the following doesn't work
+
+;; label a piece of syntax good or bad
+(define-syntax-rule
+  (good form code ...)
+(racketmod #:file
+(tt "good")
+racket
+form
+code
+...))
+
+(define-syntax-rule
+  (bad form code ...)
+  (labeled-code
+   "bad"
+   form
+   code
+   ...))
+
+(define-syntax-rule
+  (labeled-code lbl:string form code ...)
+  ;; ===>
+  (racketmod
+   #:file
+   (tt lbl:string)
+   racket
+   form
+   code
+   ...))

collects/scribblings/style/some-performance.scrbl

@@ -3,9 +3,6 @@
 @(require "shared.rkt")
 
 @; -----------------------------------------------------------------------------
-@(define (rkt) @racketmodname[racket])
-@(define (rkt/base) @racketmodname[racket/base])
-@(define (rkt/gui) @racketmodname[racket/gui])
 
 @title{Some Performance Hints}
 

collects/scribblings/style/textual.scrbl

@@ -103,6 +103,48 @@ racket
   ...)
 ]
 ]
+
+All of the arguments to a function belong on a single line unless the line
+becomes too long, in which case you want to put each argument expression on
+its own line
+
+@compare[
+@racketmod[#:file
+@tt{good}
+racket
+
+(place-image img 10 10 background)
+
+(code:comment #, @t{and})
+
+(composition img
+             (- width  hdelta)
+             (- height vdelta)
+	     bg)
+
+]
+
+@racketmod[#:file
+@tt{bad}
+racket
+
+(composition ufo-with-flames
+             10 v-delta bg)
+
+]]
+
+Here is an exception:
+@racketmod[#:file
+@tt{good}
+racket
+
+(overlay/offset (rectangle 100 10 "solid" "blue")
+                10 10
+                (rectangle 10 100 "solid" "red"))
+]
+ In this case, the two arguments on line 2 are both short and conceptually
+ related.
+
 @margin-note{We need more of these rules}
 
 @; -----------------------------------------------------------------------------