Organization changes abound.

3 files changed, 134 insertions, 0 deletions

diff --git a/docs/reference/src/tran/index.md b/docs/reference/src/tran/index.md
new file mode 100644
index 00000000..2e61d68d
--- /dev/null
+++ b/docs/reference/src/tran/index.md
@@ -0,0 +1,13 @@
+# Transports
+
+This chapter provides information about the various transports that _NNG_ supports. {{hi:transport}}
+Transports may be thought of as different underlying communications
+technologies, such as TCP, Websockets, and so forth.
+
+## INPROC
+
+The [{{i:*inproc* transport}}][inproc] provides {{i: intra-process}} communication within a single process.
+
+## TCP
+
+The [{{i:*tcp* transport}}][tcp] provides communication over {{i:TCP/IP}} networks.
diff --git a/docs/reference/src/tran/inproc.md b/docs/reference/src/tran/inproc.md
new file mode 100644
index 00000000..bf5ae8d6
--- /dev/null
+++ b/docs/reference/src/tran/inproc.md
@@ -0,0 +1,49 @@
+# INPROC Transport
+
+The {{i:*inproc* transport}}{{hi:*inproc*}}{{intra-process}} provides communication support between
+sockets within the same process.
+This may be used as an alternative
+to slower transports when data must be moved within the same process.
+
+This transport tries hard to avoid copying data, and thus is very
+light-weight.
+
+## URI Format
+
+This transport uses URIs using the scheme {{i:`inproc://`}}, followed by
+an arbitrary string of text, terminated by a `NUL` byte.
+
+Multiple URIs can be used within the
+same application, and they will not interfere with one another.
+
+Two applications may also use the same URI without interfering with each
+other, and they will be unable to communicate with each other using
+that URI.
+
+## Socket Address
+
+When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure,
+the actual structure is of type
+[`nng_sockaddr_inproc`](../api/nng_sockaddr_inproc.md).
+
+## Transport Options
+
+The _inproc_ transport has no special options.
+
+> [!NOTE]
+> While _inproc_ accepts the option [`NNG_OPT_RECVMAXSZ`] for
+> compatibility, the value of the option is ignored with no enforcement.
+> As _inproc_ peers are in the same address space, they are implicitly
+> trusted, so the protection afforded by `NNG_OPT_RECVMAXSZ` is unnecessary.
+
+## Mixing Implementations
+
+When mixing the _NNG_ library with other implementations of these
+protocols in the same process (such as the _mangos_
+or _libnanomsg_ implementations), it will not be possible to utilize
+the _inproc_ transport to communicate across this boundary.
+
+This limitation also extends to using different instances of the _NNG_
+library within the same process.
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/tran/tcp.md b/docs/reference/src/tran/tcp.md
new file mode 100644
index 00000000..8085a978
--- /dev/null
+++ b/docs/reference/src/tran/tcp.md
@@ -0,0 +1,72 @@
+# TCP transport
+
+The {{i:*tcp* transport}}{{hi:*tcp*}} provides communication support between
+sockets across a {{i:TCP/IP}} network.
+
+Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it.
+
+## URI Format
+
+This transport uses URIs using the scheme {{i:`tcp://`}}, followed by
+an IP address or hostname, followed by a colon and finally a
+TCP {{i:port number}}.
+For example, to contact port 80 on the localhost either of the following URIs
+could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`.
+
+A URI may be restricted to IPv6 using the scheme `tcp6://`, and may
+be restricted to IPv4 using the scheme `tcp4://`.
+
+> [!NOTE]
+> Specifying `tcp6://` may not prevent IPv4 hosts from being used with
+> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
+> listeners.
+> The details of this varies across operating systems.
+
+> [!NOTE]
+> Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not
+> be understood by other implementations.
+
+> [!TIP]
+> We recommend using either numeric IP addresses, or names that are
+> specific to either IPv4 or IPv6 to prevent confusion and surprises.
+
+When specifying IPv6 addresses, the address must be enclosed in
+square brackets (`[]`) to avoid confusion with the final colon
+separating the port.
+
+For example, the same port 80 on the IPv6 loopback address (`::1`) would
+be specified as `tcp://[::1]:80`.
+
+The special value of 0 ({{i:`INADDR_ANY`}})
+can be used for a listener to indicate that it should listen on all
+interfaces on the host.
+A short-hand for this form is to either omit the address, or specify
+the asterisk (`*`) character.
+For example, the following three URIs are all equivalent,
+and could be used to listen to port 9999 on the host:
+
+1. `tcp://0.0.0.0:9999`
+2. `tcp://*:9999`
+3. `tcp://:9999`
+
+The entire URI must be less than `NNG_MAXADDRLEN` bytes long.
+
+## Socket Address
+
+When using an [`nng_sockaddr`][sockaddr] structure,
+the actual structure is either of type
+[`nng_sockaddr_in`][sockaddr_in] (for IPv4) or
+[`nng_sockaddr_in6`][sockaddr_in6] (for IPv6).
+
+## Transport Options
+
+The following transport options are supported by this transport,
+where supported by the underlying platform.
+
+- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR]
+- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR]
+- [`NNG_OPT_TCP_KEEPALIVE`][NNG_OPT_TCP_KEEPALIVE]
+- [`NNG_OPT_TCP_NODELAY`][NNG_OPT_TCP_NODELAY]
+- [`NNG_OPT_URL`][NNG_OPT_URL]
+
+{{#include ../refs.md}}