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)
 
   (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"))
 
 
 (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 {
 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 ===
 
 
 === 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
 
 === 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 ===
 
 
 === 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...)
 
 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
 
 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[]
 --------------------------------
 
 include::docstrings/OP_DEF-TEST.txt[]