Proto pages done.

20 files changed, 532 insertions, 1029 deletions

diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc
deleted file mode 100644
index 67b3d974..00000000
--- a/docs/man/nng_bus.7.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-= nng_bus(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_bus - bus protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/bus0/bus.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _bus_)))
-The ((_bus_ protocol)) provides for building mesh networks where
-every peer is connected to every other peer.
-In this protocol, each message sent by a node is sent to every one of
-its directly connected peers.
-
-TIP: Messages are only sent to directly connected peers.
-This means that in the event that a peer is connected indirectly, it will not
-receive messages.
-When using this protocol to build mesh networks, it
-is therefore important that a _fully-connected_ mesh network be constructed.
-
-All message delivery in this pattern is ((best-effort)), which means that
-peers may not receive messages.
-Furthermore, delivery may occur to some,
-all, or none of the directly connected peers.
-(Messages are not delivered when peer nodes are unable to receive.)
-Hence, send operations will never block; instead if the
-message cannot be delivered for any reason it is discarded.
-
-TIP: In order to minimize the likelihood of message loss, this protocol
-should not be used for high throughput communications.
-Furthermore, the more traffic _in aggregate_ that occurs across the topology,
-the more likely that message loss is to occur.
-
-=== Socket Operations
-
-The xref:nng_bus_open.3.adoc[`nng_bus0_open()`] functions create a bus socket.
-This socket may be used to send and receive messages.
-Sending messages will attempt to deliver to each directly connected peer.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The _bus_ protocol has no protocol-specific options.
-
-=== Protocol Headers
-
-When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will
-contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header.
-If a message containing such a header is sent using a raw _bus_ socket, then,
-the message will be delivered to all connected pipes _except_ the one
-identified in the header.
-This behavior is intended for use with xref:nng_device.3.adoc[device]
-configurations consisting of just a single socket.
-Such configurations are useful in the creation of rebroadcasters, and this
-capability prevents a message from being routed back to its source.
-If no header is present, then a message is sent to all connected pipes.
-
-When using normal (cooked mode) _bus_ sockets, no message headers are present.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_bus_open.3.adoc[nng_bus_open(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc
deleted file mode 100644
index 9a035823..00000000
--- a/docs/man/nng_pair.7.adoc
+++ /dev/null
@@ -1,135 +0,0 @@
-= nng_pair(7)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_pair - pair protocol
-
-== SYNOPSIS
-
-.Version 0
-[source,c]
-----
-#include <nng/protocol/pair0/pair.h>
-----
-
-.Version 1
-[source,c]
-----
-#include <nng/protocol/pair1/pair.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _pair_)))
-The ((_pair_ protocol)) implements a peer-to-peer pattern, where
-relationships between peers are one-to-one.
-
-=== Socket Operations
-
-The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socket.
-
-Normally, this pattern will block when attempting to send a message if
-no peer is able to receive the message.
-
-NOTE: Even though this mode may appear to be reliable, because back-pressure
-prevents discarding messages most of the time, there are topologies involving
-_devices_ (see xref:nng_device.3.adoc[`nng_device()`]) or raw mode sockets
-(see xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) where
-messages may be discarded.
-Applications that require reliable delivery semantics should consider using
-xref:nng_req.7.adoc[_req_] sockets, or
-implement their own acknowledgment layer on top of _pair_ sockets.
-
-=== Protocol Versions
-
-Version 0 is the legacy version of this protocol.
-It lacks any header
-information, and is suitable when building simple one-to-one topologies.
-
-TIP: Use version 0 if you need to communicate with other implementations,
-including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or
-https://github.com/go-mangos/mangos[mangos].
-
-Version 1 of the protocol offers improved protection against loops when
-used with xref:nng_device.3.adoc[`nng_device()`].
-
-=== Polyamorous Mode
-
-WARNING: Polyamorous mode is deprecated, and support for it will likely
-be removed in a future release.
-Applications are strongly discouraged from making further use of it.
-
-Normally pair sockets are for one-to-one communication, and a given peer
-will reject new connections if it already has an active connection to another
-peer.
-
-((_Polyamorous_ mode)) changes this, to allow a socket to communicate with
-multiple directly-connected peers.
-This mode is enabled by opening a socket with the
-xref:nng_pair_open.3.adoc[`nng_pair1_open_poly()`]
-function
-
-NOTE: Polyamorous mode is only available when using pair version 1.
-
-In polyamorous mode a socket can support many one-to-one connections.
-In this mode, the application must
-choose the remote peer to receive an outgoing message by setting the
-xref:nng_pipe.5.adoc[`nng_pipe`] to use for the outgoing message with
-the xref:nng_msg_set_pipe.3.adoc[`nng_msg_set_pipe()`] function.
-
-If no remote peer is specified by the sender, then the protocol will select
-any available connected peer.
-
-Most often the value of the outgoing pipe will be obtained from an incoming
-message using the xref:nng_msg_get_pipe.3.adoc[`nng_msg_get_pipe()`] function,
-such as when replying to an incoming message.
-
-NOTE: Directed send _only_ works with directly connected peers.
-It will not function across xref:nng_device.3.adoc[device] proxies.
-
-In order to prevent head-of-line blocking, if the peer on the given pipe
-is not able to receive (or the pipe is no longer available, such as if the
-peer has disconnected), then the message will be discarded with no notification
-to the sender.
-
-=== Protocol Options
-
-The following protocol-specific options are available.
-
-xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]::
-
-   (`int`, version 1 only).  Maximum time-to-live.
-
-((`NNG_OPT_PAIR1_POLY`))::
-
-   (`bool`, version 1 only)  This option is no longer supported.
-   Formerly it was used to configure _polyamorous_ mode, but that mode
-   is now established by using the `nng_pair1_open_poly()` function.
-
-=== Protocol Headers
-
-Version 0 of the pair protocol has no protocol-specific headers.
-
-Version 1 of the pair protocol uses a single 32-bit unsigned value.  The
-low-order (big-endian) byte of this value contains a "hop" count, and is
-used in conjunction with the
-xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`] option to guard against
-device forwarding loops.
-This value is initialized to 1, and incremented each time the message is
-received by a new node.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_pair_open.3.adoc[nng_pair_open(3)],
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_pub.7.adoc b/docs/man/nng_pub.7.adoc
deleted file mode 100644
index fcebd417..00000000
--- a/docs/man/nng_pub.7.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-= nng_pub(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_pub - publisher protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/pubsub0/pub.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _pub_)))
-The ((_pub_ protocol)) is one half of a ((publisher))/subscriber pattern.
-In this pattern, a publisher sends data, which is broadcast to all
-subscribers.
-The subscribing applications only see the data to which
-they have subscribed.
-
-The _pub_ protocol is the publisher side, and the
-xref:nng_sub.7.adoc[_sub_] protocol is the subscriber side.
-
-NOTE: In this implementation, the publisher delivers all messages to all
-subscribers.
-The subscribers maintain their own subscriptions, and filter them locally.
-Thus, this pattern should not be used in an attempt to reduce bandwidth
-consumption.
-
-The topics that subscribers subscribe to is just the first part of
-the message body.
-Applications should construct their messages accordingly.
-
-=== Socket Operations
-
-The xref:nng_pub_open.3.adoc[`nng_pub0_open()`] functions create a publisher socket.
-This socket may be used to send messages, but is unable to receive them.
-Attempts to receive messages will result in `NNG_ENOTSUP`.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The _pub_ protocol has no protocol-specific options.
-
-=== Protocol Headers
-
-The _pub_ protocol has no protocol-specific headers.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_pub_open.3.adoc[nng_pub_open(3)],
-xref:nng_sub.7.adoc[nng_sub(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_pull.7.adoc b/docs/man/nng_pull.7.adoc
deleted file mode 100644
index 0b325dab..00000000
--- a/docs/man/nng_pull.7.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-= nng_pull(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_pull - pull protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/pipeline0/pull.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _pull_)))
-The ((_pull_ protocol)) is one half of a ((pipeline pattern)).
-The other half is the xref:nng_push.7.adoc[_push_] protocol.
-
-In the pipeline pattern, pushers distribute messages to pullers.
-Each message sent
-by a pusher will be sent to one of its peer pullers,
-chosen in a round-robin fashion
-from the set of connected peers available for receiving.
-This property makes this pattern useful in ((load-balancing)) scenarios.
-
-=== Socket Operations
-
-The xref:nng_pull_open.3.adoc[`nng_pull0_open()`] functions create a puller socket.
-This socket may be used to receive messages, but is unable to send them.
-Attempts to send messages will result in `NNG_ENOTSUP`.
-
-When receiving messages, the _pull_ protocol accepts messages as
-they arrive from peers.
-If two peers both have a message ready, the
-order in which messages are handled is undefined.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The _pull_ protocol has no protocol-specific options.
-
-=== Protocol Headers
-
-The _pull_ protocol has no protocol-specific headers.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_pull_open.3.adoc[nng_pull_open(3)],
-xref:nng_push.7.adoc[nng_push(7)],
-xref:nng.7.adoc[nng(7)],
diff --git a/docs/man/nng_push.7.adoc b/docs/man/nng_push.7.adoc
deleted file mode 100644
index b630c2bb..00000000
--- a/docs/man/nng_push.7.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-= nng_push(7)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_push - push protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/pipeline0/push.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _push_)))
-The ((_push_ protocol)) is one half of a ((pipeline pattern)).
-The other side is the xref:nng_pull.7.adoc[_pull_] protocol.
-
-In the pipeline pattern, pushers distribute messages to pullers.
-Each message sent by a pusher will be sent to one of its peer pullers,
-chosen in a round-robin fashion
-from the set of connected peers available for receiving.
-This property makes this pattern useful in ((load-balancing)) scenarios.
-
-=== Socket Operations
-
-The xref:nng_push_open.3.adoc[`nng_push0_open()`] call creates a pusher socket.
-This socket may be used to send messages, but is unable to receive them.
-Attempts to receive messages will result in `NNG_ENOTSUP`.
-
-Send operations will observe flow control (back-pressure), so that
-only peers capable of accepting a message will be considered.
-If no peer is available to receive a message, then the send operation will
-wait until one is available, or the operation times out.
-
-NOTE: Although the pipeline protocol honors flow control, and attempts
-to avoid dropping messages, no guarantee of delivery is made.
-Furthermore, as there is no capability for message acknowledgment,
-applications that need reliable delivery are encouraged to consider the
-xref:nng_req.7.adoc[_req_] protocol instead.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-xref:nng_options.5.adoc#NNG_OPT_SENDBUF[`NNG_OPT_SENDBUF`]::
-
-    (`int`, 0 - 8192)
-    Normally this is set to zero, indicating that send operations are unbuffered.
-    In unbuffered operation, send operations will wait until a suitable peer is available to receive the message.
-    If this is set to a positive value (up to 8192), then an intermediate buffer is
-    provided for the socket with the specified depth (in messages).
-
-NOTE: Transport layer buffering may occur in addition to any socket
-    buffer determined by this option.
-
-=== Protocol Headers
-
-The _push_ protocol has no protocol-specific headers.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_push_open.3.adoc[nng_push(3)],
-xref:nng_pull.7.adoc[nng_pull(7)],
-xref:nng_req.7.adoc[nng_req(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_rep.7.adoc b/docs/man/nng_rep.7.adoc
deleted file mode 100644
index ea40eb3a..00000000
--- a/docs/man/nng_rep.7.adoc
+++ /dev/null
@@ -1,86 +0,0 @@
-= nng_rep(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_rep - reply protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/reqrep0/rep.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _rep_)))
-The ((_rep_ protocol)) is one half of a ((request/reply pattern)).
-In this pattern, a requester sends a message to one replier, who
-is expected to reply.
-The request is resent if no reply arrives,
-until a reply is received or the request times out.
-
-TIP: This protocol is useful in setting up RPC-like services.
-It is also reliable, in that a requester will keep retrying until
-a reply is received.
-
-The _rep_ protocol is the replier side, and the
-xref:nng_req.7.adoc[_req_] protocol is the requester side.
-
-=== Socket Operations
-
-The xref:nng_rep_open.3.adoc[`nng_rep0_open()`] functions create a replier socket.
-This socket may be used to receive messages (requests), and then to send
-replies.
-
-Generally a reply can only be sent after receiving a request.
-
-Send operations will result in `NNG_ESTATE` if no corresponding request
-was previously received.
-
-Likewise, only one receive operation may be pending at a time.
-Any additional concurrent receive operations will result in `NNG_ESTATE`.
-
-xref:nng.7.adoc#raw_mode[Raw] mode sockets ignore all these restrictions.
-
-=== Context Operations
-
-This protocol supports the creation of xref:nng_ctx.5.adoc[contexts] for concurrent
-use cases using xref:nng_ctx_open.3.adoc[`nng_ctx_open()`].
-
-Each context may have at most one outstanding request, and operates
-independently of the others.
-The restrictions for order of operations with sockets apply equally
-well for contexts, except that each context will be treated as if it were
-a separate socket.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-==== Protocol Options
-
-The _rep_ protocol has no protocol-specific options.
-
-==== Protocol Headers
-
-(((backtrace)))
-The _rep_ protocol uses a _backtrace_ in the header.
-This is more fully documented in the xref:nng_req.7.adoc[_req_] manual.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_rep_open.3.adoc[nng_rep_open(3)],
-xref:nng.7.adoc[nng(7)],
-xref:nng_req.7.adoc[nng_req(7)]
diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc
deleted file mode 100644
index 1d958562..00000000
--- a/docs/man/nng_req.7.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-= nng_req(7)
-//
-// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_req - request protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/reqrep0/req.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _req_)))
-The ((_req_ protocol)) is one half of a ((request/reply pattern)).
-In this pattern, a requester sends a message to one replier, who
-is expected to reply.
-The request is resent if no reply arrives,
-until a reply is received or the request times out.
-
-TIP: This protocol is useful in setting up RPC-like services.
-It is also "reliable", in that a the requester will keep retrying until
-a reply is received.
-
-NOTE: Because requests are resent, it is important that they be ((idempotent))
-to ensure predictable and repeatable behavior even in the face of duplicated
-requests, which can occur (for example if a reply message is lost for
-some reason.)
-
-(((load-balancing)))
-The requester generally only has one outstanding request at a time unless
-in raw mode (via
-xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]),
-and it will generally attempt to spread work requests to different peer repliers.
-
-TIP: This property, when combined with xref:nng_device.3.adoc[`nng_device()`]
-can help provide a degree of load-balancing.
-
-The _req_ protocol is the requester side, and the
-xref:nng_rep.7.adoc[_rep_] protocol is the replier side.
-
-=== Socket Operations
-
-The xref:nng_req_open.3.adoc[`nng_req0_open()`] functions create a requester socket.
-This socket may be used to send messages (requests), and then to receive replies.
-
-Generally a reply can only be received after sending a request.
-(Attempts to receive a message will result in `NNG_ESTATE` if there is no
-outstanding request.)
-
-Furthermore, only a single receive operation may be pending at a time.
-Attempts to post more receive operations concurrently will result in
-`NNG_ESTATE`.
-
-Requests may be canceled by sending a different request.
-This will cause the requester to discard any reply from the earlier request,
-but it will not stop a replier
-from processing a request it has already received or terminate a request
-that has already been placed on the wire.
-
-xref:nng.7.adoc#raw_mode[Raw] mode sockets ignore all these restrictions.
-
-=== Context Operations
-
-This protocol supports the creation of xref:nng_ctx.5.adoc[contexts] for concurrent
-use cases using xref:nng_ctx_open.3.adoc[`nng_ctx_open()`].
-
-The `NNG_OPT_REQ_RESENDTIME` value may be configured differently
-on contexts created this way.
-
-Each context may have at most one outstanding request, and operates
-independently from the others.
-
-The restrictions for order of operations with sockets apply equally
-well for contexts, except that each context will be treated as if it were
-a separate socket.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The following protocol-specific option is available.
-
-((`NNG_OPT_REQ_RESENDTIME`))::
-
-   (xref:nng_duration.5.adoc[`nng_duration`])
-   When a new request is started, a timer of this duration is also started.
-   If no reply is received before this timer expires, then the request will
-   be resent.
-+
-(Requests are also automatically resent if the peer to whom
-the original request was sent disconnects, or if a peer becomes available
-while the requester is waiting for an available peer.)
-+
-Resending may be deferred up to the value of the `NNG_OPT_RESENDTICK` parameter.
-
-((`NNG_OPT_REQ_RESENDTICK`))::
-
-   (xref:nng_duration.5.adoc[`nng_duration`])
-   This is the granularity of the clock that is used to check for resending.
-   The default is a second.  Setting this to a higher rate will allow for
-   more timely resending to occur, but may incur significant additional
-   overhead when the socket has many outstanding requests (contexts).
-+
-When there are no requests outstanding that have a resend set, then
-the clock does not tick at all.
-+
-This option is shared for all contexts on a socket, and is only available for the socket itself.
-
-
-=== Protocol Headers
-
-(((backtrace)))
-This protocol uses a _backtrace_ in the header.
-This form uses a stack of 32-bit big-endian identifiers.
-There *must* be at least one identifier, the __request ID__, which will be the
-last element in the array, and *must* have the most significant bit set.
-
-There may be additional __peer ID__s preceding the request ID.
-These will be distinguishable from the request ID by having their most
-significant bit clear.
-
-When a request message is received by a forwarding node (see
-xref:nng_device.3.adoc[`nng_device()`]), the forwarding node prepends a
-32-bit peer ID (which *must* have the most significant bit clear),
-which is the forwarder's way of identifying the directly connected
-peer from which it received the message.
-(This peer ID, except for the
-most significant bit, has meaning only to the forwarding node itself.)
-
-It may help to think of prepending a peer ID as pushing a peer ID onto the
-front of the stack of headers for the message.
-(It will use the peer ID
-it popped from the front to determine the next intermediate destination
-for the reply.)
-
-When a reply message is created, it is created using the same headers
-that the request contained.
-
-A forwarding node can pop the peer ID it originally pushed on the
-message, stripping it from the front of the message as it does so.
-
-When the reply finally arrives back at the initiating requester, it
-should have only a single element in the message, which will be the
-request ID it originally used for the request.
-
-// TODO: Insert reference to RFC.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_ctx_open.3.adoc[nng_ctx_open(3)],
-xref:nng_device.3.adoc[nng_device(3)],
-xref:nng_req_open.3.adoc[nng_req_open(3)],
-xref:nng_ctx.5.adoc[nng_ctx(5)],
-xref:nng.7.adoc[nng(7)],
-xref:nng_rep.7.adoc[nng_rep(7)]
diff --git a/docs/man/nng_respondent.7.adoc b/docs/man/nng_respondent.7.adoc
deleted file mode 100644
index f6f1538f..00000000
--- a/docs/man/nng_respondent.7.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-= nng_respondent(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_respondent - respondent protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/survey0/respond.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _respondent_)))
-The ((_respondent_ protocol)) is one half of a ((survey pattern)).
-In this pattern, a surveyor sends a survey, which is broadcast to all
-peer respondents.
-The respondents then have a chance to reply (but are not obliged to reply).
-The survey itself is a timed event, so that responses
-received after the survey has finished are discarded.
-
-TIP: This protocol is useful in solving voting problems, such as leader
-election in cluster configurations, as well as certain kinds of service
-discovery problems.
-
-The _respondent_ protocol is the respondent side, and the
-xref:nng_surveyor.7.adoc[_surveyor_] protocol is the surveyor side.
-
-=== Socket Operations
-
-The xref:nng_respondent_open.3.adoc[`nng_respondent0_open()`] functions create a
-respondent socket.
-This socket may be used to receive messages, and then to send replies.
-A reply can only be sent after receiving a survey, and generally the
-reply will be sent to surveyor from whom the last survey was received.
-
-Respondents may discard a survey by simply not replying to it.
-
-Raw mode sockets (set with xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`])
-ignore all these restrictions.
-
-=== Context Operations
-
-This protocol supports the creation of xref:nng_ctx.5.adoc[contexts] for concurrent
-use cases using xref:nng_ctx_open.3.adoc[`nng_ctx_open()`].
-
-Incoming surveys will be routed to and received by only one context.
-Additional surveys may be received by other contexts in parallel.
-Replies made using a context will be returned to the the surveyor that
-issued the survey most recently received by that context.
-The restrictions for order of operations with sockets apply equally
-well for contexts, except that each context will be treated as if it were
-a separate socket.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.
-An earlier and incompatible version of the protocol was used in older
-pre-releases of http://nanomsg.org[nanomsg], but was not released in any
-production version.)
-
-=== Protocol Options
-
-The _respondent_ protocol has no protocol-specific options.
-
-=== Protocol Headers
-
-(((backtrace)))
-The _respondent_ protocol uses a _backtrace_ in the header.
-This is more fully documented in the xref:nng_surveyor.7.adoc[_surveyor_] manual.
-
-// TODO: Insert reference to RFC.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_respondent_open.3.adoc[nng_respondent_open(3)],
-xref:nng_surveyor.7.adoc[nng_surveyor(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc
deleted file mode 100644
index 2d0e6de1..00000000
--- a/docs/man/nng_sub.7.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-= nng_sub(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_sub - subscriber protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-#include <nng/protocol/pubsub0/sub.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _sub_)))
-The ((_sub_ protocol)) is one half of a publisher/((subscriber)) pattern.
-In this pattern, a publisher sends data, which is broadcast to all subscribers.
-The subscribing applications only see the data to which they have subscribed.
-
-The _sub_ protocol is the subscriber side, and the
-xref:nng_pub.7.adoc[_pub_] protocol is the publisher side.
-
-NOTE: In this implementation, the publisher delivers all messages to all
-subscribers.
-The subscribers maintain their own subscriptions, and filter them locally.
-Thus, this pattern should not be used in an attempt to
-reduce bandwidth consumption.
-
-The topics that subscribers subscribe to is just the first part of
-the message body.
-Applications should construct their messages accordingly.
-
-=== Socket Operations
-
-The xref:nng_sub_open.3.adoc[`nng_sub0_open()`] functions create a subscriber socket.
-This socket may be used to receive messages, but is unable to send them.
-Attempts to send messages will result in `NNG_ENOTSUP`.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The following protocol-specific options are available.
-
-((`NNG_OPT_SUB_SUBSCRIBE`))(((subscribe)))::
-
-   This option registers a topic that the subscriber is interested in.
-   The option is write-only, and takes an array of bytes, of arbitrary size.
-   Each incoming message is checked against the list of subscribed topics.
-   If the body begins with the entire set of bytes in the topic, then the
-   message is accepted.  If no topic matches, then the message is
-   discarded.
-+
-NOTE: This option is a byte array.  Thus if you use
-xref:nng_setopt.3.adoc[`nng_setopt_string()`] the `NUL` terminator byte will
-be included in the topic.
-If that isn't desired, consider using
-xref:nng_setopt.3.adoc[`nng_setopt()`] and using `strlen()` of the topic
-as the topic size.
-+
-TIP: To receive all messages, an empty topic (zero length) can be used.
-
-((`NNG_OPT_SUB_UNSUBSCRIBE`))::
-
-   This option, also read-only, removes a topic from the subscription list.
-   Note that if the topic was not previously subscribed to with
-   `NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result.
-
-((`NNG_OPT_SUB_PREFNEW`))::
-
-   (`bool`)
-   This read/write option specifies the behavior of the subscriber when the queue is full.
-   When `true` (the default), the subscriber will make room in the queue by removing the oldest message.
-   When `false`, the subscriber will reject messages if the message queue does not have room.
-
-=== Protocol Headers
-
-The _sub_ protocol has no protocol-specific headers.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_sub_open.3.adoc[nng_sub_open(3)],
-xref:nng_pub.7.adoc[nng_pub(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_surveyor.7.adoc b/docs/man/nng_surveyor.7.adoc
deleted file mode 100644
index 6b38c0eb..00000000
--- a/docs/man/nng_surveyor.7.adoc
+++ /dev/null
@@ -1,149 +0,0 @@
-= nng_surveyor(7)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_surveyor - surveyor protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/nng.h>
-#include <nng/protocol/survey0/survey.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _surveyor_)))
-The ((_surveyor_ protocol)) is one half of a ((survey pattern)).
-In this pattern, a surveyor sends a survey, which is broadcast to all
-peer respondents.
-The respondents then have a chance to reply (but are not obliged to reply).
-The survey itself is a timed event, so that responses
-received after the survey has finished are discarded.
-
-TIP: This protocol is useful in solving voting problems, such as
-((leader election)) in cluster configurations, as well as certain kinds of
-((service discovery)) problems.
-
-The _surveyor_ protocol is the surveyor side, and the
-xref:nng_respondent.7.adoc[_respondent_] protocol is the respondent side.
-
-=== Socket Operations
-
-The xref:nng_surveyor_open.3.adoc[`nng_surveyor0_open()`]
-functions create a surveyor socket.
-This socket may be used to send messages (surveys), and then to receive replies.
-A reply can only be received after sending a survey.
-A surveyor can normally expect to receive at most one reply from each responder.
-(Messages can be duplicated in some topologies,
-so there is no guarantee of this.)
-
-Attempts to receive on a socket with no outstanding survey will result
-in `NNG_ESTATE`.
-If the survey times out while the surveyor is waiting
-for replies, then the result will be `NNG_ETIMEDOUT`.
-
-Only one survey can be outstanding at a time; sending another survey will
-cancel the prior one, and any responses from respondents from the prior
-survey that arrive after this will be discarded.
-
-xref:nng.7.adoc#raw_mode[Raw] mode sockets ignore all these restrictions.
-
-=== Context Operations
-
-This protocol supports the creation of xref:nng_ctx.5.adoc[contexts] for concurrent
-use cases using xref:nng_ctx_open.3.adoc[`nng_ctx_open()`].
-
-Each context can initiate its own surveys, and it will receive only
-responses to its own outstanding surveys.
-Other contexts on the same socket may have overlapping surveys
-operating at the same time.
-
-Each of these may have their own timeouts established with
-`NNG_OPT_SURVEYOR_SURVEYTIME`.
-
-Additionally, sending a survey on a context will only cancel an outstanding
-survey on the same context.
-
-NOTE: Due to the best-effort nature of this protocol, if too may contexts
-are attempting to perform surveys simultaneously, it is possible for either
-individual outgoing surveys or incoming responses to be lost.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.
-An earlier and incompatible version of the protocol was used in older
-pre-releases of
-http://nanomsg.org[nanomsg], but was not released in any production
-version.)
-
-=== Protocol Options
-
-The following protocol-specific options is available.
-
-((`NNG_OPT_SURVEYOR_SURVEYTIME`))::
-
-   (xref:nng_duration.5.adoc[`nng_duration`]) Duration of surveys.
-   When a new survey is started, a timer of this duration is also started.
-   Any responses arriving this time will be discarded.
-   Attempts to receive
-   after the timer expires with no other surveys started will result in
-   `NNG_ESTATE`.
-   Attempts to receive when this timer expires will result in `NNG_ETIMEDOUT`.
-
-=== Protocol Headers
-
-(((backtrace)))
-This form uses a stack of 32-bit big-endian identifiers.
-There *must* be at least one identifier, the __survey ID__, which will be the
-last element in the array, and *must* have the most significant bit set.
-
-There may be additional __peer ID__s preceding the survey ID.
-These will be distinguishable from the survey ID by having their most
-significant bit clear.
-
-When a survey message is received by a forwarding node (see
-xref:nng_device.3.adoc[`nng_device()`]), the forwarding node prepends a
-32-bit peer ID (which *must* have the most significant bit clear),
-which is the forwarder's way of identifying the directly connected
-peer from which it received the message.
-(This peer ID, except for the
-most significant bit, has meaning only to the forwarding node itself.)
-
-It may help to think of prepending a peer ID as pushing a peer ID onto the
-front of the stack of headers for the message.
-(It will use the peer ID
-it popped from the front to determine the next intermediate destination
-for the response.)
-
-When a response message is created, it is created using the same headers
-that the survey contained.
-
-A forwarding node can pop the peer ID it originally pushed on the
-message, stripping it from the front of the message as it does so.
-
-When the response finally arrives back at the initiating surveyor, it
-should have only a single element in the message, which will be the
-survey ID it originally used for the request.
-
-More detail can be found in the
-https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt[RFC sp-surveyor-01]
-document.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_surveyor_open.3.adoc[nng_surveyor_open(3)],
-xref:nng_respondent.7.adoc[nng_respondent(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/proto/bus.adoc b/docs/ref/proto/bus.adoc
new file mode 100644
index 00000000..bbe3340d
--- /dev/null
+++ b/docs/ref/proto/bus.adoc
@@ -0,0 +1,41 @@
+## Bus Protocol (_BUS_)
+
+The ((_BUS_ protocol))(((potocol, _BUS_))) provides for building mesh networks where every peer is connected to every other peer.
+In this protocol, each message sent by a node is sent to every one of its directly connected peers.
+
+TIP: Messages are only sent to directly connected peers.
+This means that in the event that a peer is connected indirectly, it will not receive messages.
+When using this protocol to build mesh networks, it is therefore important that a _fully-connected_ mesh network be constructed.
+
+All message delivery in this pattern is ((best-effort)), which means that peers may not receive messages.
+Furthermore, delivery may occur to some, all, or none of the directly connected peers.
+(Messages are not delivered when peer nodes are unable to receive.)
+Hence, send operations will never block.
+If a message cannot be delivered for any reason it is discarded.
+
+TIP: In order to minimize the likelihood of message loss, this protocol should not be used for high throughput communications.
+Furthermore, the more traffic _in aggregate_ that occurs across the topology, the more likely that message loss is to occur.
+
+#### Socket Operations
+
+The xref:../sock/nng_bus_open.adoc[`nng_bus_open`] functions create a _BUS_ socket.
+This socket may be used to send and receive messages.
+Sending messages will attempt to deliver to each directly connected peer.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The _BUS_ protocol has no protocol-specific options.
+
+#### Protocol Headers
+
+When using a _BUS_ socket in xref:../sock/raw.adoc[raw mode], received messages will contain the incoming xref:../pipe/index.adoc[pipe] ID as the sole element in the header.
+If a message containing such a header is sent using a raw _BUS_ socket, then, the message will be delivered to all connected pipes _except_ the one identified in the header.
+This behavior is intended for use with xref:../sock/nng_device.adoc[device] configurations consisting of just a single socket.
+Such configurations are useful in the creation of rebroadcasters, and this capability prevents a message from being routed back to its source.
+If no header is present, then a message is sent to all connected pipes.
+
+When using normal (cooked mode) _BUS_ sockets, no message headers are present.
diff --git a/docs/ref/proto/pair.adoc b/docs/ref/proto/pair.adoc
new file mode 100644
index 00000000..f06d672b
--- /dev/null
+++ b/docs/ref/proto/pair.adoc
@@ -0,0 +1,65 @@
+## Pair Protocol (_PAIR_)
+
+The ((_PAIR_ protocol))(((protocol, _PAIR_))) implements a peer-to-peer pattern, where
+relationships between peers are one-to-one.
+
+#### Socket Operations
+
+The xref:nng_pair_open.adoc[`nng_pair_open`] functions create a _pair_ socket.
+
+Normally, this pattern will block when attempting to send a message if no peer is able to receive the message.
+
+NOTE: Even though this mode may appear to be reliable, because back-pressure prevents discarding messages most of the time, there are topologies involving xref:../sock/nng_device.adoc[_devices_] or xref:../sock/raw.adoc[raw mode] sockets where messages may be discarded.
+Applications that require reliable delivery semantics should consider using the xref:req.adoc[_REQ_] protocol, or implement their own acknowledgment layer on top of _PAIR_ sockets.
+
+#### Protocol Versions
+
+Version 0 is the legacy version of this protocol.
+It lacks any header information, and is suitable when building simple one-to-one topologies.
+
+TIP: Use version 0 if you need to communicate with older implementations, including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library.
+
+Version 1 of the protocol offers improved protection against loops when used with xref:nng_device.adoc[`nng_device`].
+
+#### Polyamorous Mode
+
+NOTE: Polyamorous mode is deprecated, and support for it may be removed in a future release, when a suitable mesh protocol is available.
+In the meantime, applications are encouraged to look to other patterns.footnote:[We won't remove polyamorous mode unless a suitable replacement with many-to-one semantics is available.]
+
+NOTE: Polyamorous mode only works with directly connected and does not interoperate with `nng_device`.footnote:[This is why it is deprecated.]
+
+Normally pair sockets are for one-to-one communication, and a given peer will reject new connections if it already has an active connection to another peer.
+
+((_Polyamorous_ mode)) changes this, to allow a socket to communicate with multiple directly-connected peers.
+This mode is enabled by opening a socket with the xref:nng_pair_open.adoc[`nng_pair1_open_poly`] function.footnote:[Polyamorous mode is only available when using pair version 1.]
+
+In polyamorous mode a socket can support many one-to-one connections.
+In this mode, the application must choose the remote peer to receive an outgoing message by setting the xref:../pipe/index.adoc[pipe] to use for the outgoing message with the xref:../msg/nng_msg_set_pipe.adoc[`nng_msg_set_pipe`] function.
+
+If no remote peer is specified by the sender, then the protocol will select any available connected peer.
+
+Most often the value of the outgoing pipe will be obtained from an incoming message using the xref:../msg/nng_msg_get_pipe.adoc[`nng_msg_get_pipe`] function, such as when replying to an incoming message.
+
+In order to prevent head-of-line blocking, if the peer on the given pipe is not able to receive (or the pipe is no longer available, such as if the peer has disconnected), then the message will be discarded with no notification to the sender.
+
+#### Protocol Options
+
+The following protocol-specific options are available.
+
+xref:nng_options.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]::
+
+   (`int`, version 1 only).  Maximum time-to-live.
+
+((`NNG_OPT_PAIR1_POLY`))::
+
+   (`bool`, version 1 only, deprecated)
+   This option is no longer supported.
+   Formerly it was used to configure _polyamorous_ mode, but that mode is now established by using the `nng_pair1_open_poly` function.
+
+#### Protocol Headers
+
+Version 0 of the pair protocol has no protocol-specific headers.
+
+Version 1 of the pair protocol uses a single 32-bit unsigned value.
+The low-order (big-endian) byte of this value contains a "hop" count, and is used in conjunction with the `NNG_OPT_MAXTTL` option to guard against device forwarding loops.
+This value is initialized to 1, and incremented each time the message is received by a new node.
diff --git a/docs/ref/proto/pub.adoc b/docs/ref/proto/pub.adoc
new file mode 100644
index 00000000..1d46afb2
--- /dev/null
+++ b/docs/ref/proto/pub.adoc
@@ -0,0 +1,36 @@
+## Publisher Protocol (_PUB_)
+
+The ((_PUB_ protocol))(((protocol, _PUB_))) is one half of a ((publisher))/subscriber pattern.
+In this pattern, a publisher sends data, which is broadcast to all subscribers.
+The subscribing applications only see the data to which they have subscribed.
+
+The _PUB_ protocol is the publisher side, and the xref:sub.adoc[_SUB_] protocol is the subscriber side.
+
+The publisher delivers all messages to all subscribers.
+The subscribers maintain their own subscriptions, and filter them locally.footnote:[Thus, this pattern should not be used in an attempt to reduce bandwidth consumption.]
+
+The topics that subscribers subscribe to is just the first part of the message body.
+Applications should construct their messages accordingly.
+
+#### Socket Operations
+
+The xref:../sock/nng_pub_open.adoc[`nng_pub_open`] functions create a publisher socket.
+This socket may be used to send messages, but is unable to receive them.
+Attempts to receive messages will result in `NNG_ENOTSUP`.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The _PUB_ protocol has no protocol-specific options.
+
+#### Protocol Headers
+
+The _PUB_ protocol has no protocol-specific headers.
+
+### See Also
+
+xref:sub.adoc[Subscriber Protocol (_SUB_)],
+xref:../sock/nng_pub_open.adoc[nng_pub_open]
diff --git a/docs/ref/proto/pull.adoc b/docs/ref/proto/pull.adoc
new file mode 100644
index 00000000..ec44300e
--- /dev/null
+++ b/docs/ref/proto/pull.adoc
@@ -0,0 +1,29 @@
+## Pull Protocol (_PULL_)
+
+The ((_pull_ protocol))(((protocol, _pull_))) is one half of a ((pipeline pattern)).
+The other half is the xref:push.adoc[_PUSH_] protocol.
+
+In the pipeline pattern, pushers distribute messages to pullers.
+Each message sent by a pusher will be sent to one of its ready peer pullers, chosen in a round-robin fashion.
+This property makes this pattern useful in ((load-balancing)) scenarios.
+
+#### Socket Operations
+
+The xref:nng_pull_open.adoc[`nng_pull_open`] functions create a puller socket.
+This socket may be used to receive messages, but is unable to send them.
+Attempts to send messages will result in `NNG_ENOTSUP`.
+
+When receiving messages, the _pull_ protocol accepts messages as they arrive from peers.
+If two peers both have a message ready, the order in which messages are handled is undefined.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The _PULL_ protocol has no protocol-specific options.
+
+#### Protocol Headers
+
+The _PULL_ protocol has no protocol-specific headers.
diff --git a/docs/ref/proto/push.adoc b/docs/ref/proto/push.adoc
new file mode 100644
index 00000000..4f228c77
--- /dev/null
+++ b/docs/ref/proto/push.adoc
@@ -0,0 +1,39 @@
+## Push Protocol (_PUSH_)
+
+The ((_PUSH_ protocol))(((protocol, _PUSH_)))  is one half of a ((pipeline pattern)).
+The other side is the xref:pull.adoc[_PULL_] protocol.
+
+In the pipeline pattern, pushers distribute messages to pullers.
+Each message sent by a pusher will be sent to one of its ready peer pullers, chosen in a round-robin fashion.
+This property makes this pattern useful in ((load-balancing)) scenarios.
+
+#### Socket Operations
+
+The xref:nng_push_open.adoc[`nng_push0_open`] call creates a pusher socket.
+This socket may be used to send messages, but is unable to receive them.
+Attempts to receive messages will result in `NNG_ENOTSUP`.
+
+Send operations will observe flow control (back-pressure), so that only peers capable of accepting a message will be considered.
+If no peer is available to receive a message, then the send operation will wait until one is available, or the operation times out.
+
+NOTE: Although the pipeline protocol honors flow control, and attempts to avoid dropping messages, no guarantee of delivery is made.
+Furthermore, as there is no capability for message acknowledgment, applications that need reliable delivery are encouraged to consider the xref:nng_req.adoc[_REQ_] protocol instead.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+xref:nng_options.adoc#NNG_OPT_SENDBUF[`NNG_OPT_SENDBUF`]::
+
+    (`int`, 0 - 8192)
+    Normally this is set to zero, indicating that send operations are unbuffered.
+    In unbuffered operation, send operations will wait until a suitable peer is available to receive the message.
+    If this is set to a positive value (up to 8192), then an intermediate buffer is provided for the socket with the specified depth (in messages).
+
+NOTE: Transport layer buffering may occur in addition to any socket buffer determined by this option.
+
+#### Protocol Headers
+
+The _PUSH_ protocol has no protocol-specific headers.
diff --git a/docs/ref/proto/rep.adoc b/docs/ref/proto/rep.adoc
new file mode 100644
index 00000000..8fa09469
--- /dev/null
+++ b/docs/ref/proto/rep.adoc
@@ -0,0 +1,44 @@
+## Reply Protocol (_REP_)
+
+The ((_REP_ protocol))(((protocol, _REP_))) is one half of a ((request/reply pattern)).
+In this pattern, a requester sends a message to one replier, whois expected to reply.
+The request is resent if no reply arrives, until a reply is received or the request times out.
+
+This protocol is useful in setting up RPC-like services.
+It is also "reliable", in that a requester will keep retrying until a reply is received.
+
+The _REP_ protocol is the replier side, and the xref:req.adoc[_REQ_] protocol is the requester side.
+
+#### Socket Operations
+
+The xref:../socket/nng_rep_open.adoc[`nng_rep_open`] functions create a replier socket.
+This socket may be used to receive messages (requests), and then to send replies.
+
+A reply can only be sent after receiving a request.
+Send operations will result in `NNG_ESTATE` if no corresponding request was previously received.
+
+Likewise, only one receive operation may be pending at a time.footnote:[However contexts can be used to allow concurrent request processing.]
+Any additional concurrent receive operations will result in `NNG_ESTATE`.
+
+xref:../sock/nng.adoc#raw_mode[Raw mode] sockets ignore all these restrictions.
+
+#### Context Operations
+
+This protocol supports the creation of xref:../ctx/index.adoc[contexts] for concurrent processing using xref:../ctx/nng_ctx_open.adoc[`nng_ctx_open`].
+
+Each context may have at most one outstanding request, and operates independently of the others.
+The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The _rep_ protocol has no protocol-specific options.
+
+#### Protocol Headers
+
+(((backtrace)))
+The _REP_ protocol uses a _backtrace_ in the header.
+This is documented in the xref:req.adoc[_REQ_] protocol.
diff --git a/docs/ref/proto/req.adoc b/docs/ref/proto/req.adoc
new file mode 100644
index 00000000..9ba7908f
--- /dev/null
+++ b/docs/ref/proto/req.adoc
@@ -0,0 +1,98 @@
+## Request Protocol (_REQ_)
+
+The ((_REQ_ protocol))(((protocol, _REQ_))) is one half of a ((request/reply pattern)).
+In this pattern, a requester sends a message to one replier, who is expected to reply.
+The request is resent if no reply arrives, until a reply is received or the request times out.
+
+This protocol is useful in setting up RPC-like services.
+It is also "reliable", in that a requester will keep retrying until a reply is received.
+
+NOTE: Because requests are resent, it is important that they be ((idempotent)) to ensure predictable and repeatable behavior even in the face of duplicated requests. If requests are not idempotent, then the automatic retry behavior should be disabled by setting `NNG_OPT_REQ_RESENDTIME` to zero.
+
+(((load-balancing)))
+The requester only has one outstanding request at a time{empty}footnote:[Unless a context or raw mode is used.] and it will generally attempt to spread work requests to different peer repliers.
+
+TIP: This property, when combined with xref:../sock/nng_device.adoc[`nng_device`] can help provide a degree of load-balancing.
+
+The _REQ_ protocol is the requester side, and the xref:nng_rep.adoc[_REQ_] protocol is the replier side.
+
+#### Socket Operations
+
+The xref:nng_req_open.adoc[`nng_req_open`] functions create a requester socket.
+This socket may be used to send messages (requests), and then to receive replies.
+
+A reply can only be received after sending a request.
+(Attempts to receive a message will result in `NNG_ESTATE` if there is no outstanding request.)
+
+Furthermore, only a single receive operation may be pending at a time.
+Attempts to post more receive operations concurrently will result in `NNG_ESTATE`.
+
+Requests may be canceled by sending a different request.
+This will cause the requester to discard any reply from the earlier request, but it will not stop a replier
+from processing a request it has already received or terminate a request that has already been placed on the wire.
+
+xref:../sock/raw.adoc[Raw mode] sockets ignore all these restrictions.
+
+#### Context Operations
+
+This protocol supports the creation of xref:../ctx/index.adoc[contexts] for concurrent use cases using xref:../ctx/nng_ctx_open.adoc[`nng_ctx_open`].
+
+The `NNG_OPT_REQ_RESENDTIME` value may be configured differently on contexts.
+
+Each context may have at most one outstanding request, and operates independently from the others.
+
+The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The following protocol-specific option is available.
+
+((`NNG_OPT_REQ_RESENDTIME`))::
+
+(xref:nng_duration.adoc[`nng_duration`])
+When a new request is started, a timer of this duration is also started.
+If no reply is received before this timer expires, then the request will
+be resent.
++
+(Requests are also automatically resent if the peer to whom
+the original request was sent disconnects, or if a peer becomes available
+while the requester is waiting for an available peer.)
++
+Resending may be deferred up to the value of the `NNG_OPT_RESENDTICK` parameter.
+
+((`NNG_OPT_REQ_RESENDTICK`))::
+
+(xref:nng_duration.adoc[`nng_duration`])
+This is the granularity of the clock that is used to check for resending.
+The default is a second.
+Setting this to a higher rate will allow for more timely resending to occur, but may incur significant additional overhead when the socket has many outstanding requests (contexts).
++
+When there are no requests outstanding that have a resend set, then the clock does not tick at all.
++
+This option is socket-wide, and is only available for the socket itself.
+
+
+#### Protocol Headers
+
+This protocol uses a _backtrace_(((backtrace))) in the header.
+This form uses a stack of 32-bit big-endian identifiers.
+There *must* be at least one identifier, the __request ID__, which will be the last element in the array, and *must* have the most significant bit set.
+
+There may be additional __peer ID__s preceding the request ID.
+These will be distinguishable from the request ID by having their most significant bit clear.
+
+When a request message is received by a forwarding node (see xref:nng_device.adoc[`nng_device`]), the forwarding node prepends a 32-bit peer ID (which *must* have the most significant bit clear), which is the forwarder's way of identifying the directly connected peer from which it received the message.
+(This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.)
+
+It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message.
+(It will use the peer ID it popped from the front to determine the next intermediate destination for the reply.)
+
+When a reply message is created, it is created using the same headers that the request contained.
+
+A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so.
+
+When the reply finally arrives back at the initiating requester, it should have only a single element in the message, which will be the request ID it originally used for the request.
diff --git a/docs/ref/proto/respondent.adoc b/docs/ref/proto/respondent.adoc
new file mode 100644
index 00000000..4a52f26e
--- /dev/null
+++ b/docs/ref/proto/respondent.adoc
@@ -0,0 +1,43 @@
+## Respondent Protocol (_RESPONDENT_)
+
+The ((_RESPONDENT_ protocol))(((protocol, _RESPONDENT_))) is one half of a ((survey pattern)).
+In this pattern, a surveyor sends a survey, which is broadcast to all peer respondents.
+The respondents then have a chance to reply (but are not obliged to reply).
+The survey itself is a timed event, so that responses received after the survey has finished are discarded.
+
+This protocol is useful in solving voting problems, such as leader election, as well as certain kinds of service discovery problems.
+
+The _RESPONDENT_ protocol is the respondent side, and the xref:surveyor.adoc[_SURVEYOR_] protocol is the surveyor side.
+
+#### Socket Operations
+
+The xref:nng_respondent_open.adoc[`nng_respondent_open`] functions create a respondent socket.
+This socket may be used to receive messages, and then to send replies.
+A reply can only be sent after receiving a survey, and the reply will be sent to surveyor from whom survey was received.
+
+Respondents may discard a survey by simply not replying to it.
+
+xref:../sock/raw.adoc[Raw mode] sockets ignore all these restrictions.
+
+#### Context Operations
+
+This protocol supports the creation of xref:../ctx/index.adoc[contexts] for concurrent use cases using xref:../ctx/nng_ctx_open.adoc[`nng_ctx_open`].
+
+Incoming surveys will be routed to and received by only one context.
+Additional surveys may be received by other contexts in parallel.
+Replies made using a context will be returned to the the surveyor that issued the survey most recently received by that context.
+The restrictions for order of operations with sockets apply equally well for contexts, except that each context will be treated as if it were a separate socket.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.
+An earlier and incompatible version of the protocol was used in older pre-releases of http://nanomsg.org[nanomsg], but was not released in any production version.]
+
+#### Protocol Options
+
+The _RESPONDENT_ protocol has no protocol-specific options.
+
+#### Protocol Headers
+
+The _RESPONDENT_ protocol uses a _backtrace_(((backtrace))) in the header.
+This is documented in the xref:nng_surveyor.adoc[_SURVEYOR_] protocol.
diff --git a/docs/ref/proto/sub.adoc b/docs/ref/proto/sub.adoc
new file mode 100644
index 00000000..86b9934a
--- /dev/null
+++ b/docs/ref/proto/sub.adoc
@@ -0,0 +1,58 @@
+## Subscriber Protocol (_SUB_)
+
+The ((_SUB_ protocol))(((protocol, _SUB_))) is one half of a publisher/((subscriber)) pattern.
+In this pattern, a publisher sends data, which is broadcast to all subscribers.
+The subscribing applications only see the data to which they have subscribed.
+
+The _SUB_ protocol is the subscriber side, and the
+xref:pub.adoc[_PUB_] protocol is the publisher side.
+
+The publisher delivers all messages to all subscribers.
+The subscribers maintain their own subscriptions, and filter them locally.footnote:[Thus, this pattern should not be used in an attempt to reduce bandwidth consumption.]
+
+The topics that subscribers subscribe to is just the first part of the message body.
+Applications should construct their messages accordingly.
+
+#### Socket Operations
+
+The xref:nng_sub_open.adoc[`nng_sub_open`] functions create a subscriber socket.
+This socket may be used to receive messages, but is unable to send them.
+Attempts to send messages will result in `NNG_ENOTSUP`.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.]
+
+#### Protocol Options
+
+The following protocol-specific options are available.
+
+((`NNG_OPT_SUB_SUBSCRIBE`))(((subscribe)))::
+
+This option registers a topic that the subscriber is interested in.
+The option is write-only, and takes an array of bytes, of arbitrary size.
+Each incoming message is checked against the list of subscribed topics.
+If the body begins with the entire set of bytes in the topic, then the message is accepted.
+If no topic matches, then the message is discarded.
++
+TIP: This option is a byte array.
+Thus if you use xref:nng_set.adoc[`nng_set_string`] the `NUL` terminator byte will be included in the topic.
+If that isn't desired, consider using `nng_set` and using `strlen` of the topic as the topic size.
++
+TIP: To receive all messages, an empty topic (zero length) can be used.
+
+((`NNG_OPT_SUB_UNSUBSCRIBE`))::
+
+This option, also read-only, removes a topic from the subscription list.
+Note that if the topic was not previously subscribed to with `NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result.
+
+((`NNG_OPT_SUB_PREFNEW`))::
+
+(`bool`)
+This read/write option specifies the behavior of the subscriber when the queue is full.
+When `true` (the default), the subscriber will make room in the queue by removing the oldest message.
+When `false`, the subscriber will reject messages if the message queue does not have room.
+
+#### Protocol Headers
+
+The _SUB_ protocol has no protocol-specific headers.
diff --git a/docs/ref/proto/surveyor.adoc b/docs/ref/proto/surveyor.adoc
new file mode 100644
index 00000000..4ef51966
--- /dev/null
+++ b/docs/ref/proto/surveyor.adoc
@@ -0,0 +1,79 @@
+## Surveyor Protocol (_SURVEYOR_)
+
+The ((_SURVEYOR_ protocol))(((protocol, _SURVEYOR_))) is one half of a ((survey pattern)).
+In this pattern, a surveyor sends a survey, which is broadcast to all peer respondents.
+The respondents then have a chance to reply (but are not obliged to reply).
+The survey itself is a timed event, so that responses received after the survey has finished are discarded.
+
+This protocol is useful in solving voting problems, such as ((leader election)), as well as certain kinds of ((service discovery)) problems.
+
+The _SURVEYOR_ protocol is the surveyor side, and the xref:respondent.adoc[_RESPONDENT_] protocol is the respondent side.
+
+#### Socket Operations
+
+The xref:nng_surveyor_open.adoc[`nng_surveyor_open`] functions create a _SURVEYOR_ socket.
+This socket may be used to send messages (surveys), and then to receive replies.
+A reply can only be received after sending a survey.
+A surveyor can normally expect to receive at most one reply from each responder.
+(Messages can be duplicated in some topologies, so there is no guarantee of this.)
+
+Attempts to receive on a socket with no outstanding survey will result in `NNG_ESTATE`.
+If the survey times out while the surveyor is waiting for replies, then the result will be `NNG_ETIMEDOUT`.
+
+Only one survey can be outstanding at a time; sending another survey will cancel the prior one, and any responses from respondents from the prior survey that arrive after this will be discarded.
+
+xref:../sock/raw.adoc[Raw mode] sockets ignore all these restrictions.
+
+#### Context Operations
+
+This protocol supports the creation of xref:../ctx/index.adoc[contexts] for concurrent
+use cases using xref:../ctx/nng_ctx_open.adoc[`nng_ctx_open`].
+
+Each context can initiate its own surveys, and it will receive only responses to its own outstanding surveys.
+Other contexts on the same socket may have overlapping surveys operating at the same time.
+
+Each of these may have their own timeouts established with`NNG_OPT_SURVEYOR_SURVEYTIME`.
+
+Additionally, sending a survey on a context will only cancel an outstanding survey on the same context.
+
+NOTE: Due to the best-effort nature of this protocol, if too may contexts are attempting to perform surveys simultaneously, it is possible for either individual outgoing surveys or incoming responses to be lost.
+
+#### Protocol Versions
+
+Only version 0 of this protocol is supported.footnote:[At the time of writing, no other versions of this protocol have been defined.
+An earlier and incompatible version of the protocol was used in older pre-releases of http://nanomsg.org[nanomsg], but was not released in any production version.]
+
+#### Protocol Options
+
+The following protocol-specific options is available.
+
+((`NNG_OPT_SURVEYOR_SURVEYTIME`))::
+
+(xref:nng_duration.adoc[`nng_duration`]) Duration of surveys.
+When a new survey is started, a timer of this duration is also started.
+Any responses arriving this time will be discarded.
+Attempts to receive after the timer expires with no other surveys started will result in `NNG_ESTATE`.
+Attempts to receive when this timer expires will result in `NNG_ETIMEDOUT`.
+
+#### Protocol Headers
+
+(((backtrace)))This form uses a stack of 32-bit big-endian identifiers.
+There *must* be at least one identifier, the __survey ID__, which will be the last element in the array, and *must* have the most significant bit set.
+
+There may be additional __peer ID__s preceding the survey ID.
+These will be distinguishable from the survey ID by having their most significant bit clear.
+
+When a survey message is received by a forwarding node (see xref:nng_device.adoc[`nng_device`]), the forwarding node prepends a
+32-bit peer ID (which *must* have the most significant bit clear), which is the forwarder's way of identifying the directly connected peer from which it received the message.
+(This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.)
+
+It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message.
+(It will use the peer IDit popped from the front to determine the next intermediate destination for the response.)
+
+When a response message is created, it is created using the same headers that the survey contained.
+
+A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so.
+
+When the response finally arrives back at the initiating surveyor, it should have only a single element in the message, which will be the survey ID it originally used for the request.
+
+More detail can be found in the https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt[RFC sp-surveyor-01] document.