Put some code examples into the manual

diff --git a/docs/Makefile.lisp b/docs/Makefile.lisp
index 1bb2176..a831d8a 100644 (file)
--- a/docs/Makefile.lisp
+++ b/docs/Makefile.lisp
@@ -20,7 +20,7 @@
 
   (target* `(static-file ,name) ()
     (when (file-newer-p source destination)
-      (path:cp source destination))))
+      (path:cp source destination :overwrite t))))
 
 (static-file "asciidoc.css" (path:catfile *asciidoc-root* "stylesheets/" "asciidoc.css"))
 

diff --git a/docs/fiveam.css b/docs/fiveam.css
index 56b8cf9..7b40666 100644 (file)
--- a/docs/fiveam.css
+++ b/docs/fiveam.css
@@ -1,6 +1,8 @@
 body {
-  width: 560px;
-  margin-left: auto;
-  margin-right: auto;
-  margin-top: 20px;
+    width: 42em;
+    margin-left: auto;
+    margin-right: auto;
+    margin-top: 20px;
 }
+
+h1, h2 { width: 30em; }
\ No newline at end of file

diff --git a/docs/manual.txt b/docs/manual.txt
index aedfe12..8d4ed3f 100644 (file)
--- a/docs/manual.txt
+++ b/docs/manual.txt
@@ -13,18 +13,53 @@ Fall/Winter 2012
 
 === The Super Brief Introduction ===
 
-FiveAM is a testing framework. See the xref:API_REFERENCE[api] for
-details.
+|================================
+| (xref:OP_DEF-TEST[`def-test`] `NAME` () &body `BODY`) | define tests
+| (xref:OP_IS[`is`] (`PREDICATE` `EXPECTED` `ACTUAL`)) | check that, according to `PREDICATE` our `ACTUAL` is the same as our `EXPECTED`
+| (xref:OP_IS[`is-true`] VALUE) | check that a value is non-NIL
+| (xref:OP_RUN![`run!`] TEST-NAME) | run one (or more) tests and print the results
+| (xref:OP_RUN![`!`]) | rerun the most recently run test.
+|================================
+
+See the xref:API_REFERENCE[api] for details.
 
 === An Ever So Slightly Longer Introduction ===
 
 You use define some xref:TESTS[tests] (using
 xref:OP_DEF-TEST[`def-test`]), each of which consists of some
 xref:CHECKS[checks] (with xref:OP_IS[`is`] and friends) which can pass
-or fail; you xref:RUNNING_TESTS[run] some tests (using
-xref:OP_RUN-EPOINT-[run!] and friends) and you look at the results
-(probably using xref:OP_RUN-EPOINT-[run!] again). Lather, rinse,
-repeat.
+or fail:
+
+--------------------------------
+(def-test a-test ()
+  (is (= 4 (+ 2 2)))
+  (is-false (= 5 (+ 2 2))))
+--------------------------------
+
+you xref:RUNNING_TESTS[run] some tests (using xref:OP_RUN[run] and
+friends) and you look at the results (using using
+xref:OP_EXPLAIN[explain]); or you do both at once (using
+xref:OP_RUN-EPOINT-[run!]):
+
+--------------------------------
+CL-USER> (run! 'a-test)
+..
+Did 2 checks.
+  Pass: 2 (100%)
+  Skip: 0 (  0%)
+  Fail: 0 (  0%)
+--------------------------------
+
+Lather, rinse, repeat:
+
+--------------------------------
+CL-USER> (!)
+..
+Did 2 checks.
+  Pass: 2 (100%)
+  Skip: 0 (  0%)
+  Fail: 0 (  0%)
+--------------------------------
 
 === The Real Introduction ===
 
@@ -62,7 +97,7 @@ behaviour driven development. patches welcome (they'll get laughed at
 at first, but they'll get applied, and then they'll get used, and then
 they'll be an essential part of fiveam itself...)
 
-=== Words ===
+==== Words ====
 
 Since there are far many more testing frameworks than there are words
 for talking about testing frameworks, the same words end up meaning
@@ -442,9 +477,7 @@ source code (like defmacro).
 
 ================================
 --------------------------------
-(def-test NAME
-    (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) 
-  &body BODY)
+(def-test NAME (&key DEPENDS-ON SUITE FIXTURE COMPILE-AT PROFILE) &body BODY)
 --------------------------------
 
 include::docstrings/OP_DEF-TEST.txt[]