docs: progress on socket document conversion

3 files changed, 106 insertions, 4 deletions

diff --git a/docs/ref/api/aio.md b/docs/ref/api/aio.md
index 58c8e4f9..1e6f76fa 100644
--- a/docs/ref/api/aio.md
+++ b/docs/ref/api/aio.md
@@ -290,7 +290,7 @@ void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov);
 ```
 
 {{hi:`nng_iov`}}
-Some asynchronous operations, such as those dealing with [streams], use {{i:scatter}} or {{i:gather}}
+Some asynchronous operations, such as those dealing with [streams][stream], use {{i:scatter}} or {{i:gather}}
 vectors, where data to be transferred is either gathered from multiple separate regions of memory, or
 scattered into separate regions of memory. For example a message may have a header located at one location
 in memory, and a payload located in another.
@@ -310,7 +310,7 @@ and if necessary resubmit the operation with a suitably updated vector of `nng_i
 
 [Synchronization][synchronization],
 [Threads][thread],
-[Streams][streams],
+[Streams][stream],
 [Time][time]
 
 {{#include ../xref.md}}
diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md
index afadcb42..59570240 100644
--- a/docs/ref/api/sock.md
+++ b/docs/ref/api/sock.md
@@ -49,6 +49,84 @@ or altered. It is guaranteed to remain valid while this library is present.
 The {{i:`nng_socket_raw`}} function determines whether the socket is in
 [raw mode][raw] or not, storing `true` in _raw_ if it is, or `false` if it is not.
 
+## Opening a Socket
+
+```c
+int nng_bus0_open(nng_socket *s);
+int nng_pub0_open(nng_socket *s);
+int nng_pull0_open(nng_socket *s);
+int nng_push0_open(nng_socket *s);
+int nng_rep0_open(nng_socket *s);
+int nng_req0_open(nng_socket *s);
+int nng_respondent0_open(nng_socket *s);
+int nng_sub0_open(nng_socket *s);
+int nng_surveyor0_open(nng_socket *s);
+```
+
+These functions open a socket, returning it in _s_.
+The constructors for sockets are protocol specific so please refer to protocol documentation
+for more specific information.
+
+The following functions open a socket in normal mode:
+
+- {{i:`nng_bus0_open`}} - [BUS][bus] version 0
+- {{i:`nng_pair0_open`}} - [PAIR][pair] version 0
+- {{i:`nng_pair1_open`}} - [PAIR][pair] version 1
+- {{i:`nng_pair1_open_poly`}} - [PAIR][pair] version 1, [polyamorous] mode
+- {{i:`nng_pub0_open`}} - [PUB][pub] version 0
+- {{i:`nng_pull0_open`}} - [PULL][pull] version 0
+- {{i:`nng_push0_open`}} - [PUSH][push] version 0
+- {{i:`nng_rep0_open`}} - [REP][rep] version 0
+- {{i:`nng_req0_open`}} - [REQ][req] version 0
+- {{i:`nng_respondent0_open`}} - [RESPONDENT][respondent] version 0
+- {{i:`nng_sub0_open`}} - [SUB][sub] version 0
+- {{i:`nng_surveyor0_open`}} - [SURVEYOR][surveyor] version 0
+
+## Raw Mode Sockets
+
+```c
+int nng_bus0_open_raw(nng_socket *s);
+int nng_pub0_open_raw(nng_socket *s);
+int nng_pull0_open_raw(nng_socket *s);
+int nng_push0_open_raw(nng_socket *s);
+int nng_rep0_open_raw(nng_socket *s);
+int nng_req0_open_raw(nng_socket *s);
+int nng_respondent0_open_raw(nng_socket *s);
+int nng_sub0_open_raw(nng_socket *s);
+int nng_surveyor0_open_raw(nng_socket *s);
+```
+
+{{hi:raw mode}}
+Raw mode sockets are used in circumstances when the application needs direct access
+to the message headers to control the protocol details.
+
+Such sockets require greater sophistication on the part of the application to use,
+as the application must process the protocol headers specifically.
+The details of the protocol headers, and requirements, are described in the protocol
+documentation for each protocol.
+
+Raw mode sockets do not have any kind of state machine associated with them, as all of
+the protocol specific processing must be performed by the application.
+
+> [!TIP]
+> Most applications do not need to use raw sockets.
+> The notable exception is when using [`nng_device`], which requires raw sockets.
+> To obtain asynchronous behavior, consider using [contexts][context] instead.
+
+The following functions open a socket in [raw] mode:
+
+- {{i:`nng_bus0_open_raw`}} - [BUS][bus] version 0, raw mode
+- {{i:`nng_pair0_open_raw`}} - [PAIR][pair] version 0, raw mode
+- {{i:`nng_pair1_open_raw`}} - [PAIR][pair] version 1, raw mode
+- {{i:`nng_pub0_open_raw`}} - [PUB][pub] version 0, raw mode
+- {{i:`nng_pull0_open_raw`}} - [PULL][pull] version 0, raw mode
+- {{i:`nng_push0_open_raw`}} - [PUSH][push] version 0, raw mode
+- {{i:`nng_rep0_open_raw`}} - [REP][rep] version 0, raw mode
+- {{i:`nng_req0_open_raw`}} - [REP][req] version 0, raw mode
+- {{i:`nng_respondent0_open_raw`}} - [RESPONDENT][respondent] version 0, raw mode
+- {{i:`nng_sub0_open_raw`}} - [SUB][sub] version 0, raw mode
+- {{i:`nng_surveyor0_open_raw`}} - [SURVEYOR][surveyor] version 0, raw mode
+
 ## Polling Socket Events
 
 ```c
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 15db26f5..12146752 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -114,6 +114,28 @@
 [`nng_sub0_ctx_unsubscribe`]: /TODO.md
 [`nng_sub0_socket_subscribe`]: /TODO.md
 [`nng_sub0_socket_unsubscribe`]: /TODO.md
+[`nng_bus0_open`]: /api/sock.md#opening-a-socket
+[`nng_pair0_open`]: /api/sock.md#opening-a-socket
+[`nng_pair1_open`]: /api/sock.md#opening-a-socket
+[`nng_pair1_poly_open`]: /api/sock.md#opening-a-socket
+[`nng_pub0_open`]: /api/sock.md#opening-a-socket
+[`nng_pull0_open`]: /api/sock.md#opening-a-socket
+[`nng_push0_open`]: /api/sock.md#opening-a-socket
+[`nng_rep0_open`]: /api/sock.md#opening-a-socket
+[`nng_req0_open`]: /api/sock.md#opening-a-socket
+[`nng_respondent0_open`]: /api/sock.md#opening-a-socket
+[`nng_sub0_open`]: /api/sock.md#opening-a-socket
+[`nng_surveyor0_open`]: /api/sock.md#opening-a-socket
+[`nng_bus0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_pub0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_pair0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_pair1_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_pull0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_push0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_rep0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_req0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_sub0_open_raw`]: /api/sock.md#raw-mode-sockets
+[`nng_surveyor0_open_raw`]: /api/sock.md#raw-mode-sockets
 [`nng_dialer_set_tls`]: /TODO.md
 [`nng_dialer_get_tls`]: /TODO.md
 [`nng_listener_set_tls`]: /TODO.md
@@ -134,6 +156,7 @@
 [`nng_tls_config`]: /TODO.md
 [`nng_tls_config_own_cert`]: /TODO.md
 [`nng_listener_set_security_descriptor`]: /TODO.md
+[`nng_device`]: /TODO.md
 
 <!-- Macros -->
 
@@ -214,14 +237,14 @@
 <!-- Concept index -->
 
 [aio]: /api/aio.md
-[raw]: /TODO.md
+[raw]: /api/sock.md#raw-mode-sockets
 [pipe]: /TODO.md
 [socket]: /TODO.md
 [context]: /TODO.md
 [dialer]: /TODO.md
 [listener]: /TODO.md
 [message]: /api/msg.md
-[streams]: /api/stream.md
+[stream]: /api/stream.md
 [message-body]: /api/msg.md#message-body
 [message-header]: /api/msg.md#message-header
 [synchronization]: /api/synch.md
@@ -232,3 +255,4 @@
 [time]: /api/time.md
 [error]: /api/errors.md
 [duration]: /api/time.md#duration-type
+[polyamorous]: /proto/pair.md#polyamorous-mode