From 8cbf9f1c2e3d7ec507ea6262132d24189b668f03 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonygarnockjones@gmail.com>
Date: Mon, 10 Jun 2013 19:51:58 -0400
Subject: [PATCH] Fix up linkage of on-message etc.

---
 marketplace/scribblings/highlevel.scrbl | 43 +++++++++++++++++--------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/marketplace/scribblings/highlevel.scrbl b/marketplace/scribblings/highlevel.scrbl
index 40c8c1a..12e63aa 100644
--- a/marketplace/scribblings/highlevel.scrbl
+++ b/marketplace/scribblings/highlevel.scrbl
@@ -257,17 +257,7 @@ collection of macros helps streamline endpoint setup.
 @defform[(observe-publishers/everything topic handler ...)]
 @defform[(observe-publishers/everything: State topic handler ...)]
 @defform[(build-endpoint pre-eid role handler ...)]
-@defform[(build-endpoint: State pre-eid role handler ...)
-	 #:grammar
-	 [(handler unfiltered-handler
-		   (match-state pattern handler ...)
-		   (match-orientation pattern handler ...)
-		   (match-conversation pattern handler ...)
-		   (match-interest-type pattern handler ...)
-		   (match-reason pattern handler ...))
-	  (unfiltered-handler (on-presence expr ...)
-			      (on-absence expr ...)
-			      (on-message [pattern expr ...] ...))]]
+@defform[(build-endpoint: State pre-eid role handler ...)]
 )]{
 
 The many variations on the core
@@ -302,6 +292,8 @@ note that @racket[?] is a wildcard in a topic pattern, while
 
 @subsection{Receiving messages}
 
+@defform[(on-message [pattern expr ...] ...)]{
+
 Supply an @racket[on-message] handler clause to an endpoint definition
 to handle incoming message events (as distinct from presence- or
 absence-events).
@@ -315,8 +307,14 @@ The following endpoint @emph{subscribes} to all messages, but only
 		['hello (list (send-message 'goodbye)
 			      (quit))]))]
 
+}
+
+}
+
 @subsection{Action-only vs. State updates}
 
+@defform[(match-state pattern handler ...)]{
+
 If a group of handlers is wrapped in @racket[match-state], then all
 the wrapped handlers are expected to return
 @seclink["constructing-transitions"]{transition structures}.
@@ -341,8 +339,15 @@ or, explicitly accessing the endpoint's process's state,
 		 (on-message ['ping (transition old-state
 				      (send-message 'pong))])))]
 
+}
+
 @subsection{Handling presence and absence events}
 
+@deftogether[(
+@defform[(on-presence expr ...)]
+@defform[(on-absence expr ...)]
+)]{
+
 Other endpoints (in this or other processes) may have matching topics
 and complementary orientations to the current endpoint. When such
 endpoints come and go, presence and absence events are generated in
@@ -410,13 +415,19 @@ This way, if process B starts before process A, then B will
 automatically wait until A is ready to receive ping requests before
 issuing any.
 
+}
+
 @subsection{Exit reasons}
 
+@defform[(match-reason pattern handler ...)]{
+
 If a handler is wrapped in a @racket[match-reason] form, then the exit
 reason supplied to the @racket[delete-endpoint] or @racket[quit]
 action that led to the @racket[absence-event] is available to the
 endpoint's @racket[on-absence] handler expression.
 
+}
+
 @subsection[#:tag "updating-endpoints"]{Updating endpoints}
 
 If, when an endpoint is created, an existing endpoint with an
@@ -432,6 +443,12 @@ automatic support for avoiding such transients.
 
 @subsection{Who am I talking to?}
 
+@deftogether[(
+@defform[(match-orientation pattern handler ...)]
+@defform[(match-conversation pattern handler ...)]
+@defform[(match-interest-type pattern handler ...)]
+)]{
+
 Wrapping a handler in @racket[match-orientation],
 @racket[match-conversation], and/or @racket[match-interest-type] gives
 a handler access to the contents of the @racket[role] structure
@@ -451,6 +468,8 @@ to the orientation of the current endpoint) or
 See @secref{Examples} for examples of the use of
 @racket[match-conversation] and friends.
 
+}
+
 @subsection[#:tag "participating-vs-observing"]{Participating in a conversation vs. observing conversations}
 
 The core @racket[build-endpoint] form takes an expression evaluating
@@ -486,8 +505,6 @@ create @emph{subscriber}-oriented endpoints. The rationale for this is
 that as a participant, the code should declare the role being played;
 but as an observer, the code should declare the roles being observed.
 
-}
-
 @subsection[#:tag "naming-endpoints"]{Naming endpoints}
 
 Endpoint names can be used to @seclink["updating-endpoints"]{update}