1 files changed, 156 insertions, 0 deletions
diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc
new file mode 100644
index 00000000..7b145a54
--- /dev/null
+++ b/docs/man/nng.7.adoc
@@ -0,0 +1,156 @@
+= nng(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 - nanomsg next generation
+
+== SYNOPSIS
+
+*cc* ['flags'] 'files' *-lnng* ['libraries']
+
+== DESCRIPTION
+
+The _nng_ library provides a common messaging framework intended to
+solve common communication problems in distributed applications.
+It offers a number of _protocols_, and also a number of _transports_.
+
+The _protocols_ implement the semantics associated with particular
+communications scenarios, such as RPC style services, service discovery,
+publish/subscribe, and so forth.
+
+The _transports_ provide support for underlying transport methods, such
+as TCP, IPC, websockets, and so forth.
+
+The _nng_ library is designed to permit easy creation of new _transports_ and,
+to a lesser extent, new _protocols_.
+
+The _nng_ library is wire compatible with the SP protocols described in
+the nanomsg project; projects using
+https://github.com/nanomsg/nanomsg[_libnanomsg_] can inter-operate with
+nng as well as other conforming implementations.  (One such implementation
+is https://github.com/go-mangos/mangos[_mangos_].)  Applications using _nng_
+which wish to communicate with older libraries must ensure that they only
+use protocols or transports offered by the earlier library.
+
+The _nng_ library also offers a compatible API, permitting legacy code to
+be recompiled or relinked against _nng_.  When doing this, support for
+certain enhancements or features will likely be absent, requiring the
+application developer to use the new-style API.
+
+The _nng_ library is implemented in pure C; if you need bindings for
+other languages please check the http://nanomsg.org/[website].
+
+== Protocols
+
+* <<nng_bus.7#,nng_bus(7)>> - Bus protocol
+* <<nng_pair.7#,nng_pair(7)>> - Pair protocol
+* <<nng_pub.7#,nng_pub(7)>> - Publisher side of publish/subscribe protocol
+* <<nng_pull.7#,nng_pull(7)>> - Pull side of pipeline protocol
+* <<nng_push.7#,nng_push(7)>> - Push side of pipeline protocol
+* <<nng_sub.7#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol
+* <<nng_rep.7#,nng_rep(7)>> - Reply side of request/reply protocol
+* <<nng_req.7#,nng_req(7)>> - Request side of request/reply protocol
+* <<nng_respondent.7#,nng_respondent(7)>> - Respondent side of survey protocol
+* <<nng_surveyor.7#,nng_surveyor(7)>> - Surveyor side of survey protocol
+
+== Transports
+
+* <<nng_inproc.7#,nng_inproc(7)>> - Intra-process transport
+* <<nng_ipc.7#,nng_ipc(7)>> - Inter-process transport
+* <<nng_tls.7#,nng_tls(7)>> - TLSv1.2 over TCP transport
+* <<nng_tcp.7#,nng_tcp(7)>> - TCP (and TCPv6) transport
+* <<nng_ws.7#,nng_ws(7)>> - WebSocket transport
+* <<nng_zerotier.7#,nng_zerotier(7)>> - ZeroTier transport
+
+== Conceptual Overview
+
+_nng_ presents a _socket_ view of networking.  The sockets are constructed
+using protocol-specific functions, as a given socket implements precisely
+one _nng_ protocol.
+
+Each socket can be used to send and receive messages (if the protocol)
+supports it, and implements the appropriate protocol semantics.  For
+example, <<nng_sub.7#,nng_sub(7)>> sockets automatically filter incoming
+messages to discard those for topics that have not been subscribed.
+
+_nng_ sockets are message oriented, so that messages are either delivered
+wholly, or not at all.  Partial delivery is not possible.  Furthermore,
+_nng_ does not provide any other delivery or ordering guarantees;
+messages may be dropped or reordered.  (Some protocols, such as
+<<nng_req.7#,nng_req(7)>> may offer stronger guarantees by
+performing their own retry and validation schemes.)
+
+Each socket can have zero, one, or many "endpoints", which are either
+_listeners_ or _dialers_. (A given socket may freely choose whether it uses
+listeners, dialers, or both.)  These "endpoints" provide access to
+underlying transports, such as TCP, etc.
+
+Each endpoint is associated with a URL, which is a service address.  For
+dialers, this will be the service address that will be contacted, whereas
+for listeners this is where the listener will bind and watch for new
+connections.
+
+Endpoints do not themselves transport data.  They are instead responsible
+for the creation of _pipes_, which can be thought of as message-oriented,
+connected, streams.  Pipes frequently correspond to a single underlying
+byte stream -- for example both IPC and TCP transports implement their
+pipes using a 1:1 relationship with a connected socket.
+
+Endpoints create pipes as needed.  Listeners will create them when a new
+client connection request arrives, and dialers will generally create one,
+then wait for it to disconnect before reconnecting.
+
+Most applications should not have to worry about endpoints or pipes at
+all; the socket abstraction should provide all the functionality needed
+other than in a few specific circumstances.
+
+=== URLs
+
+(((URL)))
+The _nng_ library uses ((universal resource locators)) (URLs)
+following the format specified in 
+https://tools.ietf.org/html/rfc3986[RFC 3986],
+including some schemes that are unique
+to SP.
+(((URL, canonicalized)))
+The URLs used in _nng_ are canonicalized as follows, mostly in
+accordance with
+https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]:
+
+  . The URL is parsed into scheme, userinfo, host, port, path, query and
+    fragment components.  (Not all of these members are necessarily present.)
+  . The scheme, hostname, and port if present, are converted to lower case.
+  . Percent-encoded values for
+    https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters]
+    converted to their unencoded forms.
+  . Additionally URL percent-encoded values for characters in the path
+    and with numeric values larger than 127 (i.e. not ASCII) are decoded.
+  . The resulting path is checked for invalid UTF-8 sequences, consisting
+    of surrogate pairs, illegal byte sequences, or overlong encodings.
+    If this check fails, then the entire URL is considered invalid.
+  . Path segments consisting of `.` and `..` are resolved as per 
+    https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3].
+  . Further, empty path segments are removed, meaning that duplicate
+    slash (`/`) separators are removed from the path.
+
+Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing
+them is believed to improve both the usability and security of _nng_
+applications, without violating RFC 3986 itself.
+
+== API
+
+The library API is documented at <<libnng.3#,libnng(3)>>.
+
+== SEE ALSO
+
+<<libnng.3#,libnng(3)>>,
+<<nng_compat.3compat#,nng_compat(3compat)>>