diff --git a/pkgs/racket-doc/info.rkt b/pkgs/racket-doc/info.rkt index 3bc80197e5..5248fe00fa 100644 --- a/pkgs/racket-doc/info.rkt +++ b/pkgs/racket-doc/info.rkt @@ -34,7 +34,8 @@ "net-doc" "planet-doc" "mzscheme-doc" - "compiler-lib")) + "compiler-lib" + "drracket")) (define pkg-desc "Base Racket documentation") diff --git a/pkgs/racket-doc/scribblings/style/branch-and-commit.scrbl b/pkgs/racket-doc/scribblings/style/branch-and-commit.scrbl index c80de81ff8..4efc0d6e35 100644 --- a/pkgs/racket-doc/scribblings/style/branch-and-commit.scrbl +++ b/pkgs/racket-doc/scribblings/style/branch-and-commit.scrbl @@ -1,6 +1,6 @@ #lang scribble/base -@(require "shared.rkt") +@(require "shared.rkt" scribble/core) @title[#:tag "branch-and-commit"]{Retiquette: Branch and Commit} @@ -51,14 +51,15 @@ Write meaningful commit messages. The first line (say 72 chars) should more blah blah blah, with more details about the actual change } - The advantage of a blank line is that ``git log'' and other tools display - the commit messages properly. If you prefer the ``-m'' command line flag + The advantage of a blank line is that @tt{git log} and other tools display + the commit messages properly. If you prefer the @tt{-m} command line flag over an editor, you can use several of them in a row. The message for bug report fixes should contain ``Close PR NNNNN'' so that bug reports are automatically closed. -To avoid 'merge commits', update your repository with @tt{git --rebase pull}. +To avoid `merge commits', update your repository with +@element['tt @list{git --rebase pull}]. @; ----------------------------------------------------------------------------- @section{No Commit ``Bombs,'' Please} diff --git a/pkgs/racket-doc/scribblings/style/constructs.scrbl b/pkgs/racket-doc/scribblings/style/constructs.scrbl index 91dc1362a3..6b5d571d53 100644 --- a/pkgs/racket-doc/scribblings/style/constructs.scrbl +++ b/pkgs/racket-doc/scribblings/style/constructs.scrbl @@ -23,24 +23,24 @@ Seasoned Schemers, not necessarily Racketeers, also use triple and quadruple semicolons. This is considered a courtesy to distinguish file headers from section headers. -In addition to ``;'', we have two other mechanisms for commenting code: - ``#|...|#'' for blocks and ``#;'' to comment out an expression. +In addition to @litchar{;}, we have two other mechanisms for commenting code: + @litchar{#|}...@litchar{|#} for blocks and @litchar{#;} to comment out an expression. @defterm{Block comments} are for those rare cases when an entire block of definitions and/or expressions must be commented out at once. - @defterm{Expression comments}---``#;''---apply to the following + @defterm{Expression comments}---@litchar{#;}---apply to the following S-expression. This makes them a useful tool for debugging. They can even - be composed in interesting ways with other comments, for example, ``#;#;'' - will comment two expressions, and a line with just ``;#;'' gives you a + be composed in interesting ways with other comments, for example, @litchar{#;#;} + will comment two expressions, and a line with just @litchar{;#;} gives you a single-character ``toggle'' for the expression that starts on the next line. But on the flip side, many tools don't process them - properly---treating them instead as a ``#'' followed by a commented line. + properly---treating them instead as a @litchar{#} followed by a commented line. For example, in DrRacket S-expression comments are ignored when it comes to syntax coloring, which makes it easy to miss them. In Emacs, the commented text is colored like a comment and treated as text, which makes - it difficult to edit as code. The bottom line here is that ``#;'' + it difficult to edit as code. The bottom line here is that @litchar{#;} comments are useful for debugging, but try to avoid leaving them in - committed code. If you really want to use ``#;'', clarify their use with - a line comment (``;''). + committed code. If you really want to use @litchar{#;}, clarify their use with + a line comment (@litchar{;}). @; ----------------------------------------------------------------------------- @section{Definitions} diff --git a/pkgs/racket-doc/scribblings/style/shared.rkt b/pkgs/racket-doc/scribblings/style/shared.rkt index 87e6467f28..ee4448d19e 100644 --- a/pkgs/racket-doc/scribblings/style/shared.rkt +++ b/pkgs/racket-doc/scribblings/style/shared.rkt @@ -7,7 +7,8 @@ scribble/base scribble/manual scribble/struct - (only-in scribble/core table-columns style plain) + (only-in scribble/core table-columns table-cells style plain + color-property) scribble/html-properties racket/list) @@ -57,20 +58,28 @@ (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)))])) + [(row-table (row titles ...) (row char x ...) ...) + #`(row-table/proc + (list + (list (paragraph plain (format "~a" 'titles)) ...) + (list (paragraph plain (litchar (~a 'char))) + (paragraph plain (format "~a" 'x)) ...) ...))])) -(define (sty columns width) +(define (row-table/proc stuff) + (table (sty (length (car stuff)) 200 #:valign? #f) + stuff)) + +(define (sty columns width #:valign? [valign? #t]) (define space - (style #f `(,(attributes `((width . ,(format "~a" width)) (align . "left") (valign . "top")))))) + (style #f `(,(attributes `((width . ,(format "~a" width)) (align . "left") + ,@(if valign? + (list '(valign . "top")) + (list))))))) ;; -- in -- (style #f (list - (attributes '((border . "1") (cellpadding . "1"))) - (table-columns (make-list columns space))))) + (attributes '((border . "1") (cellpadding . "1"))) + (table-columns (make-list columns space))))) ;; =================================================================================================== ;; the following doesn't work diff --git a/pkgs/racket-doc/scribblings/style/style.scrbl b/pkgs/racket-doc/scribblings/style/style.scrbl index d4b93ad063..7bb877d7e8 100644 --- a/pkgs/racket-doc/scribblings/style/style.scrbl +++ b/pkgs/racket-doc/scribblings/style/style.scrbl @@ -2,7 +2,7 @@ @(require "shared.rkt") -@title{How to Program Racket} +@title{How to Program Racket: a Style Guide} @author{Matthias Felleisen, Matthew Flatt, Robby Findler, Jay McCarthy} @section-index{Style Guide} @@ -57,13 +57,13 @@ Also, look over the commit messages. If you see problems with the code @; ----------------------------------------------------------------------------- -@include-section{correct-maintain-speed.scrbl} -@include-section{testing.scrbl} -@include-section{unit.scrbl} -@include-section{constructs.scrbl} -@include-section{textual.scrbl} -@include-section{some-performance.scrbl} -@include-section{branch-and-commit.scrbl} -@include-section{acknowledgment.scrbl} +@include-section["correct-maintain-speed.scrbl"] +@include-section["testing.scrbl"] +@include-section["unit.scrbl"] +@include-section["constructs.scrbl"] +@include-section["textual.scrbl"] +@include-section["some-performance.scrbl"] +@include-section["branch-and-commit.scrbl"] +@include-section["acknowledgment.scrbl"] @include-section{todo.scrbl} diff --git a/pkgs/racket-doc/scribblings/style/textual.scrbl b/pkgs/racket-doc/scribblings/style/textual.scrbl index 5dc24c78a8..759593bc7e 100644 --- a/pkgs/racket-doc/scribblings/style/textual.scrbl +++ b/pkgs/racket-doc/scribblings/style/textual.scrbl @@ -114,9 +114,9 @@ rules, we need to use the @emph{default} settings of DrRacket's indentation for this rule to make sense. If you add new constructs, say a for loop, please contact Robby for advice on how to add a default setting for the indentation functionality. If you add entire languages, say something on -the order of Typed Racket, we will need to wait for Matthew and Robby to -provide an indentation protocol on the @verbatim{#lang} line; please be -patient and use the existing indentation tool anyway. +the order of Typed Racket, see +@secref[#:doc '(lib "scribblings/tools/tools.scrbl") "lang-languages-customization"] +for how to implement tabbing. @bold{Caveat 2}: This rule does not apply to scribble code. @@ -127,8 +127,8 @@ Do not use tab characters in your code. Tabs make it hard to use textual tools like git or diff effectively. To disable tabs, @itemlist[ @item{in DrRacket: you are all set. It doesn't insert tabs.} -@item{in Emacs: add (setq indent-tabs-mode nil) to your emacs initialization file.} -@item{in vi: set expandtab.} +@item{in Emacs: add @tt{(setq indent-tabs-mode nil)} to your emacs initialization file.} +@item{in vi: @tt{:set expandtab}1.} ] @; ----------------------------------------------------------------------------- @@ -149,9 +149,10 @@ read code on monitors that accommodate close to 250 columns, and on occasion, our monitors are even wider. It is time to allow for somewhat more width in exchange for meaningful 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. +So, when you create a file, add a line with @litchar{;; } followed by ctrl-U 99 and +@litchar{-}. 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. +In scribble use @litchar|{@; }| as the prefix. @; ----------------------------------------------------------------------------- @section{Line Breaks} @@ -336,7 +337,7 @@ Finally, in addition to regular alphanumeric characters, Racketeers use a something about the name: @row-table[ - @row[symbol kind example] + @row[Character Kind Example] @row[? "predicates and boolean-valued functions" boolean?] @row[! "setters and field mutators" set!] @row[% "classes" game-state%] @@ -346,10 +347,10 @@ Finally, in addition to regular alphanumeric characters, Racketeers use a @row["#%" "kernel identifiers" #%app] ] @margin-note*{Identifiers with this prefix are mostly used in modules that - define new languages.} The use of ``#%'' to prefix names from the kernel + define new languages.} The use of @litchar{#%} to prefix names from the kernel language warns readers that these identifiers are extremely special and they need to watch out for subtleties. No other identifiers start with - ``#'' and, in particular, all tokens starting with ``#:'' are keywords. + @litchar{#} and, in particular, all tokens starting with @litchar{#:} are keywords. @; ----------------------------------------------------------------------------- @section{Graphical Syntax}