From 2f90b1316028820aad8a8f321fc2a7833da26ed0 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Sat, 31 Oct 2009 16:40:10 -0500
Subject: [PATCH] touch up quotation documentation

---
 core/quotations/quotations-docs.factor | 21 ++++++++++-----------
 core/syntax/syntax-docs.factor         |  2 +-
 2 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/core/quotations/quotations-docs.factor b/core/quotations/quotations-docs.factor
index 983ddbaf9a..b6be8d36f3 100644
--- a/core/quotations/quotations-docs.factor
+++ b/core/quotations/quotations-docs.factor
@@ -3,29 +3,28 @@ vectors kernel combinators ;
 IN: quotations
 
 ARTICLE: "quotations" "Quotations"
-"Conceptually, a quotation is an anonymous function (a value denoting a snippet of code) which can be passed around and called."
+"A quotation is an anonymous function (a value denoting a snippet of code) which can be used as a value and called. Quotations are delimited by square brackets (" { $snippet "[ ]" } "); see " { $link "syntax-quots" } " for details on their syntax."
 $nl
-"Concretely, a quotation is an immutable sequence of objects, some of which may be words, together with a block of machine code which may be executed to achieve the effect of evaluating the quotation. The machine code is generated by a fast non-optimizing quotation compiler which is always running and is transparent to the developer."
-$nl
-"Quotations form a class of objects, however in most cases, methods should dispatch on " { $link callable } " instead, so that " { $link curry } " and " { $link compose } " values can participate."
+"Quotations form a class of objects:"
 { $subsections
     quotation
     quotation?
 }
-"Quotations evaluate sequentially from beginning to end. Literals are pushed on the stack and words are executed. Details can be found in " { $link "evaluator" } "."
-$nl
-"Quotation literal syntax is documented in " { $link "syntax-quots" } "."
-$nl
+"A more general class is provided for methods to dispatch on that includes quotations, " { $link curry } ", and " { $link compose } " objects:"
+{ $subsections
+    callable
+}
+"Quotations evaluate sequentially from beginning to end. Literals are pushed on the stack and words are executed. Details can be found in " { $link "evaluator" } ". Words can be placed in wrappers to suppress execution:"
+{ $subsections "wrappers" }
 "Quotations implement the " { $link "sequence-protocol" } ", and existing sequences can be converted into quotations:"
 { $subsections
     >quotation
     1quotation
 }
-"Wrappers:"
-{ $subsections "wrappers" } ;
+"Although quotations can be treated as sequences, the compiler will be unable to reason about quotations manipulated as sequences at runtime. " { $link "compositional-combinators" } " are provided for runtime partial application and composition of quotations." ;
 
 ARTICLE: "wrappers" "Wrappers"
-"Wrappers are used to push words on the data stack; they evaluate to the object being wrapped:"
+"Wrappers evaluate to the object being wrapped when encountered in code. They are are used to suppress the execution of " { $link "words" } " so that they can be used as values."
 { $subsections
     wrapper
     literalize
diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor
index 2a8bf53e64..e0b6c1acb9 100644
--- a/core/syntax/syntax-docs.factor
+++ b/core/syntax/syntax-docs.factor
@@ -106,7 +106,7 @@ ARTICLE: "syntax-numbers" "Number syntax"
 } ;
 
 ARTICLE: "syntax-words" "Word syntax"
-"A word occurring inside a quotation is executed when the quotation is called. Sometimes a word needs to be pushed on the data stack instead. The canonical use-case for this is passing the word to the " { $link execute } " combinator, or alternatively, reflectively accessing word properties (" { $link "word-props" } ")."
+"A word occurring inside a quotation is executed when the quotation is called. Sometimes a word needs to be pushed on the data stack instead. The canonical use case for this is passing the word to the " { $link execute } " combinator, or alternatively, reflectively accessing word properties (" { $link "word-props" } ")."
 { $subsections
     POSTPONE: \
     POSTPONE: POSTPONE: