From dbfbd6e860555d1c464095f06bda6c802fbe4b55 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Wed, 23 Feb 2011 23:01:59 -0500 Subject: [PATCH] [Style] table, names, size --- collects/scribblings/style/shared.rkt | 39 ++++++++++++++++++------ collects/scribblings/style/size.scrbl | 7 +++-- collects/scribblings/style/textual.scrbl | 37 ++++++++++++++++++++-- 3 files changed, 68 insertions(+), 15 deletions(-) diff --git a/collects/scribblings/style/shared.rkt b/collects/scribblings/style/shared.rkt index e385c6e7ad..1b2e36be8d 100644 --- a/collects/scribblings/style/shared.rkt +++ b/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 - (style #f - (list - (attributes '((border . "1") (cellpadding . "10"))) - (table-columns (make-list (length stuff) space)))) - (apply map (compose make-flow list) stuff))) + (table (sty 2 500) (apply map (compose make-flow list) stuff))) + +(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 columns space))))) ;; =================================================================================================== ;; the following doesn't work @@ -64,4 +85,4 @@ code racket form code - ...)) \ No newline at end of file + ...)) diff --git a/collects/scribblings/style/size.scrbl b/collects/scribblings/style/size.scrbl index 16acef748d..0e908947db 100644 --- a/collects/scribblings/style/size.scrbl +++ b/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 -can't come up with a good name for such units, you are probably looking at -the wrong kind of division; consider alternatives. +units compute, implement or serve, use meaningful names; see +@secref{names}. Conversely, if you can't come up with a good name for such +units, you are probably looking at the wrong kind of division; consider +alternatives. diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl index 58a7ac67c3..680f414d8c 100644 --- a/collects/scribblings/style/textual.scrbl +++ b/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 "-". -When you separate "sections" of code in a file, insert the same line. This -provides some line-width orientation in the middle of a file, too. +This number is a compromise. People used to recommend a line width of 80 or +72 column. The number is a historical artifact. It is also a good number if +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^] +]