[Style] table, names, size

collects/scribblings/style/shared.rkt

@@ -6,7 +6,7 @@
          scribble/base
          scribble/manual
          scribble/struct
-         (only-in scribble/core table-columns style)
+         (only-in scribble/core table-columns style plain)
          scribble/html-properties
          racket/list)
 
@@ -17,6 +17,8 @@
   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]
+  column-table
+  row-table
   rkt rkt/base rkt/gui)
 
 (define (rkt) (racketmodname racket))
@@ -26,13 +28,32 @@
 ;; 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"))))))
+  (table (sty 2 500) (apply map (compose make-flow list) stuff)))
-  (table
+
+(define-syntax (column-table stx)
+  (syntax-case stx (col)
+    [(_ (col x ...) ...)
+     #`(begin
+	 (define stuff (list (list (paragraph plain (format "~a" 'x)) ...) ...))
+	 (table (sty (length stuff) 200)
+	        (apply map (compose make-flow list) stuff)))]))
+
+(define-syntax (row-table stx)
+  (syntax-case stx (row)
+    [(_ (row x ...) ...)
+     #`(begin
+	 (define stuff (list (list (paragraph plain (format "~a" 'x)) ...) ...))
+	 (table (sty (length (first stuff)) 200)
+	        (map make-flow stuff)))]))
+
+(define (sty columns width)
+  (define space
+    (style #f `(,(attributes `((width . ,(format "~a" width)) (align . "center") (valign . "top"))))))
+  ;; -- in --
   (style #f
     (list
       (attributes '((border . "1") (cellpadding . "10")))
-           (table-columns (make-list (length stuff) space))))
+      (table-columns (make-list columns space)))))
-   (apply map (compose make-flow list) stuff)))
 
 ;; ===================================================================================================
 ;; the following doesn't work

collects/scribblings/style/size.scrbl

@@ -11,6 +11,7 @@ Keep functions small. Keep classes small. Keep units small. Keep modules small.
 
 Anytime a unit of code looks incomprehensible, it is probably too
 large. Break it up into smaller units. To bring across what these smaller
-units compute, implement or serve, use meaningful names. Conversely, if you
+units compute, implement or serve, use meaningful names; see
-can't come up with a good name for such units, you are probably looking at
+@secref{names}.  Conversely, if you can't come up with a good name for such
-the wrong kind of division; consider alternatives.
+units, you are probably looking at the wrong kind of division; consider
+alternatives.

collects/scribblings/style/textual.scrbl

@@ -213,6 +213,37 @@ racket
 
 A line in a Racket file is at most 102 characters wide.
 
-When you create a file, add a line with ";; " followed by ctrl-U 99 and "-".
+This number is a compromise. People used to recommend a line width of 80 or
-When you separate "sections" of code in a file, insert the same line. This
+72 column. The number is a historical artifact. It is also a good number if
-provides some line-width orientation in the middle of a file, too.
+you wish to print code or project it at a reasonably large font size in a
+typical class room. In reality, we don't print code anymore and we don't
+show much of our code base to a classroom full of students. We regularly
+read code on monitors that accommodate close to 200 columns, and on
+occasion, our monitors are even wider. It is time to allow for somewhat
+more width in exchange for meaning full identifiers.
+
+So, when you create a file, add a line with ";; " followed by ctrl-U 99 and
+"-". When you separate "sections" of code in a file, insert the same line.
+These lines help both writers and readers to orient themselves in a file.
+
+@; -----------------------------------------------------------------------------
+@section[#:tag "names"]{Names}
+
+Use meaningful names. The Lisp convention is to use full English words
+separated by dashes. Racket code benefits from the same convention.
+
+In addition to regular alphanumeric characters, Racketeers use a few
+special characters.
+
+@column-table[
+ @col[? ! "@" ^ %]
+ @col[1 2 3 4 5]
+ @col[1 2 3 4 5] ]
+
+@row-table[
+ @row[? predicates boolean?]
+ @row[! setters    set!]
+ @row[% classes    a%]
+ @row["@" units      a@]
+ @row[^ signatures a^]
+]