diff --git a/TrickleApi.md b/TrickleApi.md
index 50e240f..6fb718c 100644
--- a/TrickleApi.md
+++ b/TrickleApi.md
@@ -1,81 +1,101 @@
-[[PageOutline]]
+# Trickle message API
+
The interface for [trickle messages](TrickleMessages) includes both client-side and server-side components.
# Client-side API
To send a trickle-up message, call
-
- int boinc_send_trickle_up(char* variety, char* text)
-
+```
+int boinc_send_trickle_up(char* variety, char* text)
+```
To receive a trickle-down message, call
-
- int boinc_receive_trickle_down(char* buf, int len)
-
+```
+int boinc_receive_trickle_down(char* buf, int len)
+```
This returns true (nonzero) if there was a message.
# Server-side API
-To handle trickle-up messages, use a 'trickle_handler' daemon.
-This is a program, based on sched/trickle_handler.cpp, linked with a function
+# Handling trickle-up messages
-
- int handle_trickle(MSG_FROM_HOST&);
-
- struct MSG_FROM_HOST {
- int create_time;
- int hostid;
- char variety[256]; // project-defined; what kind of msg
- char xml[MSG_FROM_HOST_BLOB_SIZE];
- };
-
+To handle trickle-up messages, use a 'trickle_handler' daemon.
+This is a program, based on sched/trickle_handler.cpp, linked with functions
+
+```
+int handle_trickle_init(int argc, char** argv); // initialize
+int handle_trickle(MSG_FROM_HOST&); // handle a trickle message
+
+struct MSG_FROM_HOST {
+ int create_time;
+ int hostid;
+ char variety[256]; // project-defined; what kind of msg
+ char xml[MSG_FROM_HOST_BLOB_SIZE];
+};
+```
This function should return zero if the message was handled successfully.
The 'hostid' field identifies the host from which the message was sent.
The daemon must be passed a '--variety X' command-line argument, telling it what kind of messages to handle.
The daemon should be specified in the [project configuration file](ProjectDaemons).
+By default, a trickle handler daemon enumerates msg_from_host records with handled==0,
+and when done sets handled=1.
+If you need multiple stages of trickle handling,
+you can do so by assigning **handled_enum** and **handled_set** in handle_trickle_init().
+For example, by setting these to 1 and 2 respectively you can add a 2nd stage of handling.
+
+
+# Sending trickle-down messages
+
To send trickle-down messages (from a trickle handler daemon or other program) you must insert a record in the 'msg_to_host' table.
From C/C++, this is done as follows:
-
- DB_MSG_TO_HOST mth;
-
- mth.clear();
- mth.create_time = time(0);
- mth.hostid = hostid;
- sprintf(mth.xml,
- "\n"
- " %s\n"
- " ...\n"
- "\n",
- ...
- );
- retval = mth.insert();
-
+```
+DB_MSG_TO_HOST mth;
+
+mth.clear();
+mth.create_time = time(0);
+mth.hostid = hostid;
+sprintf(mth.xml,
+ "\n"
+ " %s\n"
+ " ...\n"
+ "\n",
+ ...
+);
+retval = mth.insert();
+```
To send trickle-down messages, include
-
-
-
+```
+
+```
in your [configuration](ProjectOptions#Clientcontrol) (config.xml) file.
+# Purging trickle messages
+
If you use either type of trickle message, you should include
-
-
-
- run_in_ops purge_trickles.php
- 24 hours
-
-
+```
+
+
+ run_in_ops purge_trickles.php
+ 24 hours
+
+```
in your [configuration](ProjectOptions#Clientcontrol) (config.xml) file,
to delete unneeded trickle-related records from your database.
+It you use multiple stages of trickle-up handling, use
+```
+purge_trickles.php msg_from_host 2
+```
+or whatever the final value of "handled" is.
# Replicated trickle-up messages
@@ -83,14 +103,14 @@ You can arrange to have trickle-up messages sent not only the the project's sche
but to other schedulers as well.
To do this, including the following in your gui_urls.xml file:
-
-
- http://a.b.edu/test2_cgi/cgi
- [ ... ]
-
-
+```
+
+ http://a.b.edu/test2_cgi/cgi
+ [ ... ]
+
+```
The messages sent to these trickle-up handlers
are abbreviated versions of scheduler RPC requests.
-This works only with 6.13.5+ clients.
\ No newline at end of file
+This works only with 6.13.5+ clients.