From dcd0fb713438e5ca236a8b86a36ca19512372809 Mon Sep 17 00:00:00 2001
From: Matthias Felleisen <matthias@ccs.neu.edu>
Date: Thu, 21 Oct 2010 11:10:08 -0400
Subject: [PATCH] [Style] getting started

---
 .../style/correct-maintain-speed.scrbl        | 19 +++++++
 collects/scribblings/style/shared.rkt         |  9 +++
 collects/scribblings/style/style.scrbl        | 28 +++++++++
 collects/scribblings/style/textual.scrbl      | 57 +++++++++++++++++++
 4 files changed, 113 insertions(+)
 create mode 100644 collects/scribblings/style/correct-maintain-speed.scrbl
 create mode 100644 collects/scribblings/style/shared.rkt
 create mode 100644 collects/scribblings/style/style.scrbl
 create mode 100644 collects/scribblings/style/textual.scrbl

diff --git a/collects/scribblings/style/correct-maintain-speed.scrbl b/collects/scribblings/style/correct-maintain-speed.scrbl
new file mode 100644
index 0000000000..b09db79084
--- /dev/null
+++ b/collects/scribblings/style/correct-maintain-speed.scrbl
@@ -0,0 +1,19 @@
+#lang scribble/base
+
+@title[#:tag "correct-maintain-speed"]{Basic Facts of Life}
+
+Write code that is correct; maintainable; and fast. The ordering of this
+adjectives is critical: correct is more important than maintainable;
+maintainable is more important than fast; and fast is important to include,
+because nobody wants to live with slow programs.
+
+Code is correct.
+
+Code is maintainable.
+
+Code is fast.
+
+The following suggestions are about creating maintainable and fast
+code. The production of correct code is a project for life, and depends to
+a high degree on reflection---i.e., thinking about what you are doing and
+not just doing it.
diff --git a/collects/scribblings/style/shared.rkt b/collects/scribblings/style/shared.rkt
new file mode 100644
index 0000000000..242910cff8
--- /dev/null
+++ b/collects/scribblings/style/shared.rkt
@@ -0,0 +1,9 @@
+#lang racket
+
+; things to be shared among all sections of the style guide
+
+(require (for-label racket)
+         scribble/manual)
+
+(provide (for-label (all-from-out racket))
+         (all-from-out scribble/manual))
diff --git a/collects/scribblings/style/style.scrbl b/collects/scribblings/style/style.scrbl
new file mode 100644
index 0000000000..f69fdd394a
--- /dev/null
+++ b/collects/scribblings/style/style.scrbl
@@ -0,0 +1,28 @@
+#lang scribble/base
+
+@(require "shared.rkt")
+
+@title{How to Program Racket}
+@author{Matthias Felleisen, Matthew Flatt}
+
+@; -----------------------------------------------------------------------------
+
+Since 1995 PLT has grown from a handful of people who worked on/with the
+ repository to three dozen and more. In addition, Racekt is an open source
+ project, meaning other people study the code in the repository and use it
+ as an implicit guide to Racket programming. To manage the growth of the PLT
+ developer basis and to showcase good Racket coding, every contribution
+ should satisfy certain basic criteria.
+
+This document spells out these criteria, and it is also a call for
+ improvements and suggestions for additional criteria.  Like code, this
+ document lives and benefits from the "many pairs of eyes" effect of open
+ source. Code should be viewed by more than one person; a second person is
+ likely to catch mistakes and problems and hidden bugs. This document is
+ meta-code, and the same ideas apply. If you have suggestions, contact the
+ authors via email.
+
+@; -----------------------------------------------------------------------------
+
+@include-section["correct-maintain-speed.scrbl"]
+@include-section["textual.scrbl"]
diff --git a/collects/scribblings/style/textual.scrbl b/collects/scribblings/style/textual.scrbl
new file mode 100644
index 0000000000..01f62c0c5d
--- /dev/null
+++ b/collects/scribblings/style/textual.scrbl
@@ -0,0 +1,57 @@
+#lang scribble/base
+
+@(require "shared.rkt")
+
+@title{Textual Matters}
+
+@; -----------------------------------------------------------------------------
+@section{Indentation}
+
+DrRacket indents code. Use it. If you wish to be a real friend of PLT, use
+DrRacket all the time, and do request features and changes for things you
+don't like.
+
+Real friends of PLT use DrRacket to write their programs, and they don't
+override DrRacket's indentation style. They accept it and leave it alone.
+The resulting uniformity helps guide eyes.
+
+@margin-note{Okay, okay. We are using emacs to write this guide.} Minor
+friends of PLT use Emacs and/or vi(m).  Nevertheless, these minor friends
+adjust their chosen editor so that it follows DrRacket's way of indenting
+code.
+
+One of the most important disagreements may concern @scheme[if]. So once
+and for all:
+
+@(racketmod
+racket
+#:file good
+(if (positive? x)
+    (send rocket-object launch)
+    (redirect (- x)))
+)
+
+@(racketmod
+racket
+#:file bad
+(if (positive? x)
+  (send rocket-object launch)
+  (redirect (- x)))
+)
+
+Also note that the then- and else-branches are separate entities, and each
+entity deserves at least one line.
+
+@; -----------------------------------------------------------------------------
+@section{Line Width}
+
+A line in Racket is at most 80 characters wide.
+
+If you use Emacs to edit, create a line with ";; " followed by ctrl-U 77
+and "-". Okay, use DrRacket to create such lines by holding down the dash
+key.
+
+@; -----------------------------------------------------------------------------
+@section{Where to Put Parentheses}
+
+Racket isn't C. Put all closing parentheses on one line.