Further cleanups on reference manual

- fixed unwrapped text in new man pages
- fixed over-long lines in older pages, where possible
- removed reference to old standalong devices from index page
- added refernce to new zmq_device[3] documented from index page
- some minor spelling corrections

10 files changed, 117 insertions, 60 deletions

diff --git a/doc/zmq.txt b/doc/zmq.txt
index e8a3a97..0ff26e7 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -140,20 +140,14 @@ Local in-process (inter-thread) communication transport::
 
 Devices
 ~~~~~~~
-Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
-building blocks intended to serve as intermediate nodes in complex messaging
-topologies.
-
-The following devices are provided:
-
-Forwarder device for request-response messaging::
-    linkzmq:zmq_queue[1]
-
-Forwarder device for publish-subscribe messaging::
-    linkzmq:zmq_forwarder[1]
-
-Streamer device for parallelized pipeline messaging::
-    linkzmq:zmq_streamer[1]
+0MQ provides 'devices', which are building blocks that act as intermediate
+nodes in complex messaging topologies.  Devices can act as brokers that other
+nodes connect to, proxies that connect through to other nodes, or any mix of
+these two models.
+
+You can start a device in an application thread, see linkzmq:zmq_device[3],
+and you can also start devices externally, as standalone processes, see
+linkzmq:zmq_deviced[1].
 
 
 ERROR HANDLING
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt
index 62c4584..2678ca6 100644
--- a/doc/zmq_bind.txt
+++ b/doc/zmq_bind.txt
@@ -24,10 +24,15 @@ the underlying transport protocol selected.
 
 The following transports are defined:
 
-'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
-'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
-'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
-'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
+'inproc'::
+    local in-process (inter-thread) communication transport, see
+    linkzmq:zmq_inproc[7]
+'ipc'::
+    local inter-process communication transport, see linkzmq:zmq_ipc[7]
+'tcp'::
+    unicast transport using TCP, see linkzmq:zmq_tcp[7]
+'pgm', 'epgm'::
+    reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
 
 With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
 multiple endpoints using _zmq_connect()_, while simultaneously accepting
diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt
index 47e0540..6121493 100644
--- a/doc/zmq_connect.txt
+++ b/doc/zmq_connect.txt
@@ -24,10 +24,15 @@ the underlying transport protocol selected.
 
 The following transports are defined:
 
-'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
-'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
-'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
-'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
+'inproc'::
+    local in-process (inter-thread) communication transport, see
+    linkzmq:zmq_inproc[7]
+'ipc'::
+    local inter-process communication transport, see linkzmq:zmq_ipc[7]
+'tcp'::
+    unicast transport using TCP, see linkzmq:zmq_tcp[7]
+'pgm', 'epgm'::
+    reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
 
 With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
 multiple endpoints using _zmq_connect()_, while simultaneously accepting
diff --git a/doc/zmq_device.txt b/doc/zmq_device.txt
index 7797693..e18d2af 100644
--- a/doc/zmq_device.txt
+++ b/doc/zmq_device.txt
@@ -13,7 +13,8 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-The _zmq_device()_ function starts a built-in 0MQ device.  The 'device' argument is one of:
+The _zmq_device()_ function starts a built-in 0MQ device.  The 'device'
+argument is one of:
 
 'ZMQ_QUEUE'::
     starts a queue device
@@ -22,48 +23,77 @@ The _zmq_device()_ function starts a built-in 0MQ device.  The 'device' argument
 'ZMQ_STREAMER'::
     starts a streamer device
 
-The device connects a frontend socket to a backend socket.  Conceptually, data flows from frontend to backend.  Depending on the socket types, replies may flow in the opposite direction.
+The device connects a frontend socket to a backend socket.  Conceptually, data
+flows from frontend to backend.  Depending on the socket types, replies may
+flow in the opposite direction.
 
-Before calling _zmq_device()_ you must set any socket options, and connect or bind both frontend and backend sockets.  The two conventional device models are:
+Before calling _zmq_device()_ you must set any socket options, and connect or
+bind both frontend and backend sockets.  The two conventional device models
+are:
 
 *proxy*::
-    bind frontend socket to an endpoint, and connect backend socket to downstream components.  A proxy device model does not require changes to the downstream topology but that topology is static (any changes require reconfiguring the device).
+    bind frontend socket to an endpoint, and connect backend socket to
+    downstream components.  A proxy device model does not require changes to
+    the downstream topology but that topology is static (any changes require
+    reconfiguring the device).
 *broker*::
-    bind frontend socket to one endpoint and bind backend socket to a second endpoint.  Downstream components must now connect into the device.  A broker device model allows a dynamic downstream topology (components can come and go at any time).
+    bind frontend socket to one endpoint and bind backend socket to a second
+    endpoint.  Downstream components must now connect into the device.  A
+    broker device model allows a dynamic downstream topology (components can
+    come and go at any time).
 
-_zmq_device()_ runs in the current thread and returns only if/when the current context is closed.
+_zmq_device()_ runs in the current thread and returns only if/when the current
+context is closed.
 
 
 QUEUE DEVICE
 ------------
-'ZMQ_QUEUE' creates a shared queue that collects requests from a set of clients, and distributes these fairly among a set of services.  Requests are fair-queued from frontend connections and load-balanced between backend connections.  Replies automatically return to the client that made the original request.
+'ZMQ_QUEUE' creates a shared queue that collects requests from a set of
+clients, and distributes these fairly among a set of services.  Requests are
+fair-queued from frontend connections and load-balanced between backend
+connections. Replies automatically return to the client that made the original
+request.
 
-This device is part of the 'request-reply' pattern.  The frontend speaks to clients and the backend speaks to services.  You should use 'ZMQ_QUEUE' with a 'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend.  Other combinations are not documented.
+This device is part of the 'request-reply' pattern.  The frontend speaks to
+clients and the backend speaks to services.  You should use 'ZMQ_QUEUE' with a
+'ZMQ_XREP' socket for the frontend and a 'ZMQ_XREQ' socket for the backend.
+Other combinations are not documented.
 
 Refer to linkzmq:zmq_socket[3] for a description of these socket types.
 
 
 FORWARDER DEVICE
 ----------------
-'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these to a set of subscribers.  You will generally use this to bridge networks, e.g. read on TCP unicast and forward on multicast.
+'ZMQ_FORWARDER' collects messages from a set of publishers and forwards these
+to a set of subscribers.  You will generally use this to bridge networks, e.g.
+read on TCP unicast and forward on multicast.
 
-This device is part of the 'publish-subscribe' pattern.  The frontend speaks to publishers and the backend speaks to subscribers.  You should use 'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket for the backend.  Other combinations are not documented.
+This device is part of the 'publish-subscribe' pattern.  The frontend speaks to
+publishers and the backend speaks to subscribers.  You should use
+'ZMQ_FORWARDER' with a 'ZMQ_SUB' socket for the frontend and a 'ZMQ_PUB' socket
+for the backend.  Other combinations are not documented.
 
 Refer to linkzmq:zmq_socket[3] for a description of these socket types.
 
 
 STREAMER DEVICE
 ---------------
-'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set of pullers.  You will generally use this to bridge networks.  Messages are fair-queued from pushers and load-balanced to pullers.
+'ZMQ_STREAMER' collects tasks from a set of pushers and forwards these to a set
+of pullers.  You will generally use this to bridge networks.  Messages are
+fair-queued from pushers and load-balanced to pullers.
 
-This device is part of the 'pipeline' pattern.  The frontend speaks to pushers and the backend speaks to pullers.  You should use 'ZMQ_STREAMER' with a 'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend.  Other combinations are not documented.
+This device is part of the 'pipeline' pattern.  The frontend speaks to pushers
+and the backend speaks to pullers.  You should use 'ZMQ_STREAMER' with a
+'ZMQ_PULL' socket for the frontend and a 'ZMQ_PUSH' socket for the backend.
+Other combinations are not documented.
 
 Refer to linkzmq:zmq_socket[3] for a description of these socket types.
 
 
 RETURN VALUE
 ------------
-The _zmq_device()_ function always returns `-1` and 'errno' set to *ETERM* (the 0MQ 'context' associated with either of the specified sockets was terminated).
+The _zmq_device()_ function always returns `-1` and 'errno' set to *ETERM* (the
+0MQ 'context' associated with either of the specified sockets was terminated).
 
 
 EXAMPLE
diff --git a/doc/zmq_deviced.txt b/doc/zmq_deviced.txt
index e5ba83f..fd94c96 100644
--- a/doc/zmq_deviced.txt
+++ b/doc/zmq_deviced.txt
@@ -14,22 +14,32 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Starts one or more 0MQ devices.  If you specify a DEVICE, FRONTEND, and BACKEND then _zmq_device_ starts a single device acting as a mini-broker.  If you specify a CONFIGFILE, you can configure _zmq_device_ to start multiple concurrent devices with arbitrary configurations.
+Starts one or more 0MQ devices.  If you specify a DEVICE, FRONTEND, and BACKEND
+then _zmq_device_ starts a single device acting as a mini-broker.  If you
+specify a CONFIGFILE, you can configure _zmq_device_ to start multiple
+concurrent devices with arbitrary configurations.
 
 *Note* - zmq_deviced is not yet implemented.  This is a design.
 
 MINI-BROKER USAGE
 -----------------
-Runs as a mini-broker that accepts connects to both frontend and backend. This creates a hub-and-spoke topology in which all peers connect to the device.  This is a robust and easy to manage topology.
+Runs as a mini-broker that accepts connects to both frontend and backend. This
+creates a hub-and-spoke topology in which all peers connect to the device. This
+is a robust and easy to manage topology.
 
-DEVICE is one of: *queue*, *forwarder*, or *streamer*. See linkzmq:zmq_device[3] for a specification of these device types.
+DEVICE is one of: *queue*, *forwarder*, or *streamer*. See
+linkzmq:zmq_device[3] for a specification of these device types.
 
-FRONTEND and BACKEND are endpoints in the format 'transport'`://`'address',  See linkzmq:zmq_bind[3] for a specification of valid transports and addresses.
+FRONTEND and BACKEND are endpoints in the format 'transport'`://`'address', See
+linkzmq:zmq_bind[3] for a specification of valid transports and addresses.
 
 
 CONFIGURED USAGE
 ----------------
-CONFIGFILE is the name of an XML file, readable by 'zmq_device'.  This file provides a specification of the devices to start and how to connect and/or bind their frontends and backends.  If CONFIGFILE is absent or *-* then the configuration is read from standard input.
+CONFIGFILE is the name of an XML file, readable by 'zmq_device'.  This file
+provides a specification of the devices to start and how to connect and/or bind
+their frontends and backends.  If CONFIGFILE is absent or *-* then the
+configuration is read from standard input.
 
 The configuration file has this general syntax:
 
@@ -52,19 +62,28 @@ The configuration file has this general syntax:
 ----
 
 *iothreads*::
-    specifies the number of I/O threads for the process.  Specify this only for high-volume scenarios. See linkzmq:zmq_init[3].
+    specifies the number of I/O threads for the process.  Specify this only for
+    high-volume scenarios. See linkzmq:zmq_init[3].
 *device*::
-    defines one device.  For each device element you define, 'zmq_device' will start a thread.
+    defines one device.  For each device element you define, 'zmq_device' will
+    start a thread.
 *frontend*::
-    defines the frontend for the device.  Occurs once per device element.  You may override the default socket type.
+    defines the frontend for the device.  Occurs once per device element.  You
+    may override the default socket type.
 *backend*::
-    defines the backend for the device.  Occurs once per device element. You may override the default socket type.
+    defines the backend for the device.  Occurs once per device element. You
+may    override the default socket type.
 *set*::
-    defines a socket option for the frontend or backend.  The valid names are *hwm*, *swap*, *identity*, *subscribe*, *unsubscribe*, *rate*, *recovery_ivl*, *mcast_loop*, *sndbuf*, and *rcvbuf*. See linkzmq:zmq_setsockopt[3].
+    defines a socket option for the frontend or backend.  The valid names are
+    *hwm*, *swap*, *identity*, *subscribe*, *unsubscribe*, *rate*,
+    *recovery_ivl*, *mcast_loop*, *sndbuf*, and *rcvbuf*. See
+    linkzmq:zmq_setsockopt[3].
 *bind*::
-    binds the frontend or backend to the specified endpoint.  See linkzmq:zmq_bind[3].
+    binds the frontend or backend to the specified endpoint.  See
+    linkzmq:zmq_bind[3].
 *connect*::
-    binds the frontend or backend to the specified endpoint.  See linkzmq:zmq_connect[3].
+    binds the frontend or backend to the specified endpoint.  See
+    linkzmq:zmq_connect[3].
 
 SOCKET TYPES
 ------------
@@ -78,9 +97,12 @@ By default 'zmq_device' uses these socket types:
 *streamer* device::
     frontend is *pull*, backend is *push*.
 
-You can override the socket type for frontend or backend.  The valid types are: *req*, *rep*, *xreq*, *xrep*, *sub*, *pub*, *pull*, *push*, and *pair*.  See linkzmq:zmq_socket[3].
+You can override the socket type for frontend or backend.  The valid types are:
+*req*, *rep*, *xreq*, *xrep*, *sub*, *pub*, *pull*, *push*, and *pair*.  See
+linkzmq:zmq_socket[3].
 
-*Note*: if you use a *sub* socket you must explicitly set a subscription filter or your socket will not receive any data.
+*Note*: if you use a *sub* socket you must explicitly set a subscription filter
+or your socket will not receive any data.
 
 
 EXAMPLE
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt
index e1cc014..3f131ba 100644
--- a/doc/zmq_getsockopt.txt
+++ b/doc/zmq_getsockopt.txt
@@ -70,7 +70,7 @@ ZMQ_SWAP: Retrieve disk offload size
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_SWAP' option shall retrieve the disk offload (swap) size for the
 specified 'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may
-exceed it's high water mark; in this case outstanding messages shall be
+exceed its high water mark; in this case outstanding messages shall be
 offloaded to storage on disk rather than held in memory.
 
 The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
index 862cbd6..abc943e 100644
--- a/doc/zmq_pgm.txt
+++ b/doc/zmq_pgm.txt
@@ -55,7 +55,7 @@ and a port number.
 An 'interface' may be specified by either of the following:
 
 * The interface name as defined by the operating system.
-* The primary IPv4 address assigned to the interface, in it's numeric
+* The primary IPv4 address assigned to the interface, in its numeric
   representation.
 
 NOTE: Interface names are not standardised in any way and should be assumed to
@@ -63,7 +63,7 @@ be arbitrary and platform dependent. On Win32 platforms no short interface
 names exist, thus only the primary IPv4 address may be used to specify an
 'interface'.
 
-A 'multicast address' is specified by an IPv4 multicast address in it's numeric
+A 'multicast address' is specified by an IPv4 multicast address in its numeric
 representation.
 
 
diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt
index 92c5efe..9761881 100644
--- a/doc/zmq_poll.txt
+++ b/doc/zmq_poll.txt
@@ -100,13 +100,13 @@ associated 0MQ 'context' was terminated.
 
 EXAMPLE
 -------
-.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
+.Polling indefinitely for input events on both a 0MQ socket and a TCP socket.
 ----
 zmq_pollitem_t items [2];
 /* First item refers to 0MQ socket 'socket' */
 items[0].socket = socket;
 items[0].events = ZMQ_POLLIN;
-/* Second item refers to standard socket 'fd' */
+/* Second item refers to TCP socket 'fd' */
 items[1].socket = NULL;
 items[1].fd = fd;
 items[1].events = ZMQ_POLLIN;
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index 9fef404..c612247 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -48,7 +48,7 @@ Applicable socket types:: all
 ZMQ_SWAP: Set disk offload size
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the specified
-'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed it's
+'socket'. A socket which has 'ZMQ_SWAP' set to a non-zero value may exceed its
 high water mark; in this case outstanding messages shall be offloaded to
 storage on disk rather than held in memory.
 
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
index 29d3543..1713eb4 100644
--- a/doc/zmq_tcp.txt
+++ b/doc/zmq_tcp.txt
@@ -31,7 +31,8 @@ colon and the TCP port number to use.
 An 'interface' may be specified by either of the following:
 
 * The interface name as defined by the operating system.
-* The primary IPv4 address assigned to the interface, in it's numeric representation.
+* The primary IPv4 address assigned to the interface, in its numeric
+  representation.
 * The wildcard `*`, meaning that the interface address is unspecified.
 
 NOTE: Interface names are not standardised in any way and should be assumed to
@@ -48,15 +49,15 @@ a colon and the TCP port number to use.
 A 'peer address' may be specified by either of the following:
 
 * The DNS name of the peer.
-* The IPv4 address of the peer, in it's numeric representation.
+* The IPv4 address of the peer, in its numeric representation.
 
 
 WIRE FORMAT
 -----------
 0MQ messages are transmitted over TCP in frames consisting of an encoded
-'payload length', followed by a 'flags' field and the message body. The 'payload
-length' is defined as the combined length in octets of the message body and the
-'flags' field.
+'payload length', followed by a 'flags' field and the message body. The
+'payload length' is defined as the combined length in octets of the message
+body and the 'flags' field.
 
 For frames with a 'payload length' not exceeding 254 octets, the 'payload
 length' shall be encoded as a single octet.  The minimum valid 'payload length'