finished proto open pages

36 files changed, 137 insertions, 145 deletions

diff --git a/docs/reference/book.toml b/docs/reference/book.toml
index 20529827..aeca51c3 100644
--- a/docs/reference/book.toml
+++ b/docs/reference/book.toml
@@ -14,13 +14,9 @@ fold.level = 1
 
 [preprocessor.indexing.see_instead]
 
-# "*PULL* protocol" = "protocol, *PULL*"
-
-#"protocol, PUB" = "PUB"
-# "_PAIR_‍" = "protocol, _PAIR_"
+# "*PUSH* (protocol)" = "protocol, *PUSH*"
 
 [preprocessor.indexing.nest_under]
-# hacks to allow us to also place some entries underneath
 "body" = "message"
 "header" = "message"
 
diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index 498511a4..82187252 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -58,6 +58,9 @@
     - [nng_pub_open](sock/nng_pub_open.md)
     - [nng_pull_open](sock/nng_pull_open.md)
     - [nng_push_open](sock/nng_push_open.md)
+    - [nng_respondent_open](sock/nng_respondent_open.md)
+    - [nng_rep_open](sock/nng_rep_open.md)
+    - [nng_req_open](sock/nng_req_open.md)
     - [nng_sub_open](sock/nng_sub_open.md)
     - [nng_surveyor_open](sock/nng_surveyor_open.md)
 
diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/reference/src/compat/nn_allocmsg.3compat.adoc
index a53da55c..a53da55c 100644
--- a/docs/man/nn_allocmsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_allocmsg.3compat.adoc
diff --git a/docs/man/nn_bind.3compat.adoc b/docs/reference/src/compat/nn_bind.3compat.adoc
index a4ca0043..a4ca0043 100644
--- a/docs/man/nn_bind.3compat.adoc
+++ b/docs/reference/src/compat/nn_bind.3compat.adoc
diff --git a/docs/man/nn_close.3compat.adoc b/docs/reference/src/compat/nn_close.3compat.adoc
index 1970b57d..1970b57d 100644
--- a/docs/man/nn_close.3compat.adoc
+++ b/docs/reference/src/compat/nn_close.3compat.adoc
diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/reference/src/compat/nn_cmsg.3compat.adoc
index 32d31810..32d31810 100644
--- a/docs/man/nn_cmsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_cmsg.3compat.adoc
diff --git a/docs/man/nn_connect.3compat.adoc b/docs/reference/src/compat/nn_connect.3compat.adoc
index e498f8d3..e498f8d3 100644
--- a/docs/man/nn_connect.3compat.adoc
+++ b/docs/reference/src/compat/nn_connect.3compat.adoc
diff --git a/docs/man/nn_device.3compat.adoc b/docs/reference/src/compat/nn_device.3compat.adoc
index c69e1e04..c69e1e04 100644
--- a/docs/man/nn_device.3compat.adoc
+++ b/docs/reference/src/compat/nn_device.3compat.adoc
diff --git a/docs/man/nn_errno.3compat.adoc b/docs/reference/src/compat/nn_errno.3compat.adoc
index a048543d..a048543d 100644
--- a/docs/man/nn_errno.3compat.adoc
+++ b/docs/reference/src/compat/nn_errno.3compat.adoc
diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/reference/src/compat/nn_freemsg.3compat.adoc
index 61127c3d..61127c3d 100644
--- a/docs/man/nn_freemsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_freemsg.3compat.adoc
diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/reference/src/compat/nn_get_statistic.3compat.adoc
index 89b11de2..89b11de2 100644
--- a/docs/man/nn_get_statistic.3compat.adoc
+++ b/docs/reference/src/compat/nn_get_statistic.3compat.adoc
diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/reference/src/compat/nn_getsockopt.3compat.adoc
index 0c476cca..0c476cca 100644
--- a/docs/man/nn_getsockopt.3compat.adoc
+++ b/docs/reference/src/compat/nn_getsockopt.3compat.adoc
diff --git a/docs/man/nn_poll.3compat.adoc b/docs/reference/src/compat/nn_poll.3compat.adoc
index c115fe49..c115fe49 100644
--- a/docs/man/nn_poll.3compat.adoc
+++ b/docs/reference/src/compat/nn_poll.3compat.adoc
diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/reference/src/compat/nn_reallocmsg.3compat.adoc
index d48b5d40..d48b5d40 100644
--- a/docs/man/nn_reallocmsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_reallocmsg.3compat.adoc
diff --git a/docs/man/nn_recv.3compat.adoc b/docs/reference/src/compat/nn_recv.3compat.adoc
index 2a71714d..2a71714d 100644
--- a/docs/man/nn_recv.3compat.adoc
+++ b/docs/reference/src/compat/nn_recv.3compat.adoc
diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/reference/src/compat/nn_recvmsg.3compat.adoc
index e0fcc758..e0fcc758 100644
--- a/docs/man/nn_recvmsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_recvmsg.3compat.adoc
diff --git a/docs/man/nn_send.3compat.adoc b/docs/reference/src/compat/nn_send.3compat.adoc
index 050bea17..050bea17 100644
--- a/docs/man/nn_send.3compat.adoc
+++ b/docs/reference/src/compat/nn_send.3compat.adoc
diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/reference/src/compat/nn_sendmsg.3compat.adoc
index b339bfe6..b339bfe6 100644
--- a/docs/man/nn_sendmsg.3compat.adoc
+++ b/docs/reference/src/compat/nn_sendmsg.3compat.adoc
diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/reference/src/compat/nn_setsockopt.3compat.adoc
index 860d522e..860d522e 100644
--- a/docs/man/nn_setsockopt.3compat.adoc
+++ b/docs/reference/src/compat/nn_setsockopt.3compat.adoc
diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/reference/src/compat/nn_shutdown.3compat.adoc
index 06a5cd5a..06a5cd5a 100644
--- a/docs/man/nn_shutdown.3compat.adoc
+++ b/docs/reference/src/compat/nn_shutdown.3compat.adoc
diff --git a/docs/man/nn_socket.3compat.adoc b/docs/reference/src/compat/nn_socket.3compat.adoc
index c4bbb70a..c4bbb70a 100644
--- a/docs/man/nn_socket.3compat.adoc
+++ b/docs/reference/src/compat/nn_socket.3compat.adoc
diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/reference/src/compat/nn_strerror.3compat.adoc
index 3fc2dc29..3fc2dc29 100644
--- a/docs/man/nn_strerror.3compat.adoc
+++ b/docs/reference/src/compat/nn_strerror.3compat.adoc
diff --git a/docs/man/nn_term.3compat.adoc b/docs/reference/src/compat/nn_term.3compat.adoc
index 79b6a1e3..79b6a1e3 100644
--- a/docs/man/nn_term.3compat.adoc
+++ b/docs/reference/src/compat/nn_term.3compat.adoc
diff --git a/docs/reference/src/sock/nng_bus_open.md b/docs/reference/src/sock/nng_bus_open.md
index 9b993f52..0d37e86c 100644
--- a/docs/reference/src/sock/nng_bus_open.md
+++ b/docs/reference/src/sock/nng_bus_open.md
@@ -17,7 +17,7 @@ int nng_bus0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_bus0_open()` function creates a [_BUS_][bus] version 0
+The `nng_bus0_open()` function creates a [{{i:*BUS*}}][bus] version 0
 [socket][socket] and returns it at the location pointed to by _s_.
 
 The `nng_bus0_open_raw()` function creates a _BUS_ version 0
@@ -34,7 +34,7 @@ These functions return 0 on success, and non-zero otherwise.
 
 ## SEE ALSO
 
-[BUS protocol][bus],
+[_BUS_ protocol][bus],
 [RAW mode][raw]
 
 {{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_pair_open.md b/docs/reference/src/sock/nng_pair_open.md
index df3c8b65..fe955df5 100644
--- a/docs/reference/src/sock/nng_pair_open.md
+++ b/docs/reference/src/sock/nng_pair_open.md
@@ -29,7 +29,7 @@ int nng_pair1_open_poly(nng_socktet *s);
 ## DESCRIPTION
 
 The `nng_pair0_open()` and `nng_pair1_open()` functions
-create a [_PAIR_][pair] version 0 or version 1
+create a [{{i:*PAIR*}}][pair] version 0 or version 1
 [socket][socket] and return it at the location pointed to by _s_.
 
 The `nng_pair0_open_raw()` and `nng_pair1_open_raw()` functions
diff --git a/docs/reference/src/sock/nng_pub_open.md b/docs/reference/src/sock/nng_pub_open.md
index e8b6bbd0..0969f4d9 100644
--- a/docs/reference/src/sock/nng_pub_open.md
+++ b/docs/reference/src/sock/nng_pub_open.md
@@ -17,7 +17,7 @@ int nng_pub0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_pub0_open()` function creates a [_PUB_][pub] version 0
+The `nng_pub0_open()` function creates a [{{i:*PUB*}}][pub] version 0
 [socket][socket] and returns it at the location pointed to by _s_.
 
 The `nng_pub0_open_raw()` function creates a _PUB_ version 0
diff --git a/docs/reference/src/sock/nng_pull_open.md b/docs/reference/src/sock/nng_pull_open.md
index e10f66c0..53248207 100644
--- a/docs/reference/src/sock/nng_pull_open.md
+++ b/docs/reference/src/sock/nng_pull_open.md
@@ -17,7 +17,7 @@ int nng_pull0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_pull0_open()` function creates a [_PULL_][pull] version 0
+The `nng_pull0_open()` function creates a [{{i:*PULL*}}][pull] version 0
 [socket][socket] and returns it at the location pointed to by _s_.
 
 The `nng_pull0_open_raw()` function creates a _PULL_ version 0
diff --git a/docs/reference/src/sock/nng_push_open.md b/docs/reference/src/sock/nng_push_open.md
index aace8750..aed86f73 100644
--- a/docs/reference/src/sock/nng_push_open.md
+++ b/docs/reference/src/sock/nng_push_open.md
@@ -2,7 +2,7 @@
 
 ## NAME
 
-nng_push_open --- create push socket
+nng_push_open --- create _PUSH_ socket
 
 ## SYNOPSIS
 
@@ -17,7 +17,7 @@ int nng_push0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_push0_open()` function creates a [_PUSH_][push] version 0
+The `nng_push0_open()` function creates a [{{i:*PUSH*}}][push] version 0
 [socket][socket] and returns it at the location pointed to by _s_.
 
 The `nng_push0_open_raw()` function creates a _PUSH_ version 0 socket in
diff --git a/docs/reference/src/sock/nng_rep_open.3.adoc b/docs/reference/src/sock/nng_rep_open.3.adoc
deleted file mode 100644
index 3b56c541..00000000
--- a/docs/reference/src/sock/nng_rep_open.3.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-# nng_rep_open(3)
-
-## NAME
-
-nng_rep_open - create rep socket
-
-## SYNOPSIS
-
-```
-#include <nng/nng.h>
-#include <nng/protocol/reqrep0/rep.h>
-
-int nng_rep0_open(nng_socket *s);
-
-int nng_rep0_open_raw(nng_socket *);
-```
-
-## DESCRIPTION
-
-The `nng_rep0_open()` function creates a xref:nng_rep.7.adoc[_rep_] version 0
-xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_.
-
-The `nng_rep0_open_raw()` function creates a xref:nng_rep.7.adoc[_rep_] version 0
-xref:nng_socket.5.adoc[socket]
-in xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_.
-
-## RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-## ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol is not supported.
-
-## SEE ALSO
-
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng_rep.7.adoc[nng_rep(7)],
-xref:nng_req.7.adoc[nng_req(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/sock/nng_rep_open.md b/docs/reference/src/sock/nng_rep_open.md
new file mode 100644
index 00000000..8472da7b
--- /dev/null
+++ b/docs/reference/src/sock/nng_rep_open.md
@@ -0,0 +1,41 @@
+# nng_rep_open
+
+## NAME
+
+nng_rep_open --- create _REP_ socket
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+#include <nng/protocol/reqrep0/rep.h>
+
+int nng_rep0_open(nng_socket *s);
+
+int nng_rep0_open_raw(nng_socket *);
+```
+
+## DESCRIPTION
+
+The `nng_rep0_open()` function creates a [{{i:*REP*}}][rep] version 0
+[socket][socket] and returns it at the location pointed to by _s_.
+
+The `nng_rep0_open_raw()` function creates a _REP_ version 0
+socket in [raw mode][raw] and returns it at the location pointed to by _s_.
+
+## RETURN VALUES
+
+These functions return 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol is not supported.
+
+## SEE ALSO
+
+[Sockets][socket],
+[_REP_ Protocol][rep],
+[_REQ_ Protocol][req]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_req_open.3.adoc b/docs/reference/src/sock/nng_req_open.3.adoc
deleted file mode 100644
index 51d1df8a..00000000
--- a/docs/reference/src/sock/nng_req_open.3.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-# nng_req_open(3)
-
-## NAME
-
-nng_req_open - create req socket
-
-## SYNOPSIS
-
-```
-#include <nng/nng.h>
-#include <nng/protocol/reqrep0/req.h>
-
-int nng_req0_open(nng_socket *s);
-
-int nng_req0_open_raw(nng_socket *s);
-```
-
-## DESCRIPTION
-
-The `nng_req0_open()` function creates a xref:nng_req.7.adoc[_req_] version 0
-xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_.
-
-The `nng_req0_open_raw()` function creates a xref:nng_req.7.adoc[_req_] version 0
-xref:nng_socket.5.adoc[socket] in
-xref:nng.7.adoc#raw_mode[raw] mode
-and returns it at the location pointed to by _s_.
-
-## RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-## ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol is not supported.
-
-## SEE ALSO
-
-xref:nng_options.5.adoc[nng_options(5)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng_rep.7.adoc[nng_rep(7)],
-xref:nng_req.7.adoc[nng_req(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/sock/nng_req_open.md b/docs/reference/src/sock/nng_req_open.md
new file mode 100644
index 00000000..6763c00b
--- /dev/null
+++ b/docs/reference/src/sock/nng_req_open.md
@@ -0,0 +1,41 @@
+# nng_req_open
+
+## NAME
+
+nng_req_open --- create req socket
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+#include <nng/protocol/reqrep0/req.h>
+
+int nng_req0_open(nng_socket *s);
+
+int nng_req0_open_raw(nng_socket *s);
+```
+
+## DESCRIPTION
+
+The `nng_req0_open()` function creates a [{{i:*REQ*}}][req] version 0
+[socket][socket] and returns it at the location pointed to by _s_.
+
+The `nng_req0_open_raw()` function creates a _REQ_ version 0
+socket in [raw mode][raw] and returns it at the location pointed to by _s_.
+
+## RETURN VALUES
+
+These functions return 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol is not supported.
+
+## SEE ALSO
+
+[Sockets][socket],
+[_REP_ Protocol][rep],
+[_REQ_ Protocol][req]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_respondent_open.3.adoc b/docs/reference/src/sock/nng_respondent_open.3.adoc
deleted file mode 100644
index 7a1fd6d9..00000000
--- a/docs/reference/src/sock/nng_respondent_open.3.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-# nng_respondent_open(3)
-
-## NAME
-
-nng_respondent_open - create respondent socket
-
-## SYNOPSIS
-
-```
-#include <nng/nng.h>
-#include <nng/protocol/survey0/respond.h>
-
-int nng_respondent0_open(nng_socket *s);
-
-int nng_respondent0_open_raw(nng_socket *s);
-```
-
-## DESCRIPTION
-
-The `nng_respondent0_open()` function creates a
-xref:nng_respondent.7.adoc[_respondent_]
-version 0 xref:nng_socket.5.adoc[socket] and returns it at the location
-pointed to by _s_.
-
-The `nng_respondent0_open_raw()` function creates a
-xref:nng_respondent.7.adoc[_respondent_]
-version 0 xref:nng_socket.5.adoc[socket] in
-xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_.
-
-## RETURN VALUES
-
-These functions return 0 on success, and non-zero otherwise.
-
-## ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol is not supported.
-
-## SEE ALSO
-
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng_respondent.7.adoc[nng_respondent(7)],
-xref:nng_surveyor.7.adoc[nng_surveyor(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/sock/nng_respondent_open.md b/docs/reference/src/sock/nng_respondent_open.md
new file mode 100644
index 00000000..b8883d8d
--- /dev/null
+++ b/docs/reference/src/sock/nng_respondent_open.md
@@ -0,0 +1,42 @@
+# nng_respondent_open
+
+## NAME
+
+nng_respondent_open --- create _RESPONDENT_ socket
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+#include <nng/protocol/survey0/respond.h>
+
+int nng_respondent0_open(nng_socket *s);
+
+int nng_respondent0_open_raw(nng_socket *s);
+```
+
+## DESCRIPTION
+
+The `nng_respondent0_open()` function creates a [{{i:*RESPONDENT*}}][respondent]
+version 0 [socket][socket] and returns it at the location
+pointed to by _s_.
+
+The `nng_respondent0_open_raw()` function creates a _RESPONDENT_
+version 0 socket in [raw mode][raw] and returns it at the location pointed to by _s_.
+
+## RETURN VALUES
+
+These functions return 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol is not supported.
+
+## SEE ALSO
+
+[Sockets][socket],
+[_RESPONDENT_ Protocol][respondent],
+[_SURVEYOR_ Protocol][surveyor]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_sub_open.md b/docs/reference/src/sock/nng_sub_open.md
index d98ecb7f..47adb00b 100644
--- a/docs/reference/src/sock/nng_sub_open.md
+++ b/docs/reference/src/sock/nng_sub_open.md
@@ -17,7 +17,7 @@ int nng_sub0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_sub0_open()` function creates a [_SUB_][sub] version 0
+The `nng_sub0_open()` function creates a [{{i:*SUB*}}][sub] version 0
 [socket][socket] and returns it at the location pointed to by _s_.
 
 The `nng_sub0_open_raw()` function creates a _SUB_ version 0
diff --git a/docs/reference/src/sock/nng_surveyor_open.md b/docs/reference/src/sock/nng_surveyor_open.md
index 77ac08ae..a09325ba 100644
--- a/docs/reference/src/sock/nng_surveyor_open.md
+++ b/docs/reference/src/sock/nng_surveyor_open.md
@@ -17,7 +17,7 @@ int nng_surveyor0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_surveyor0_open()` function creates a [_SURVEYOR_][surveyor]
+The `nng_surveyor0_open()` function creates a [{{i:*SURVEYOR*}}][surveyor]
 version 0 [socket][socket] and returns it at the location
 pointed to by _s_.