Numerous link fixups - protocols now use xrefs.md properly.

11 files changed, 50 insertions, 102 deletions

diff --git a/docs/ref/proto/bus.md b/docs/ref/proto/bus.md
index aa9d55d5..2a2606b1 100644
--- a/docs/ref/proto/bus.md
+++ b/docs/ref/proto/bus.md
@@ -28,7 +28,7 @@ message cannot be delivered for any reason it is discarded.
 
 ## Socket Operations
 
-The [`nng_bus0_open`][nng_bus_open] functions create a bus socket.
+The [`nng_bus0_open`] functions create a bus socket.
 This socket may be used to send and receive messages.
 Sending messages will attempt to deliver to each directly connected peer.
 
@@ -44,11 +44,11 @@ The _BUS_ protocol has no protocol-specific options.
 ## Protocol Headers
 
 When using a _BUS_ socket in [raw mode][raw], received messages will
-contain the incoming [pipe][pipe] ID as the sole element in the header.
+contain the incoming [pipe] ID as the sole element in the header.
 If a message containing such a header is sent using a raw _BUS_ socket, then,
 the message will be delivered to all connected pipes _except_ the one
 identified in the header.
-This behavior is intended for use with [device][device]
+This behavior is intended for use with [device]
 configurations consisting of just a single socket.
 Such configurations are useful in the creation of rebroadcasters, and this
 capability prevents a message from being routed back to its source.
@@ -56,7 +56,4 @@ If no header is present, then a message is sent to all connected pipes.
 
 When using normal (cooked mode) _BUS_ sockets, no message headers are present.
 
-[nng_bus_open]: TODO.md
-[device]: TODO.md
-[pipe]: TODO.md
-[raw]: TODO.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/index.md b/docs/ref/proto/index.md
index e7a4619f..c51b29ce 100644
--- a/docs/ref/proto/index.md
+++ b/docs/ref/proto/index.md
@@ -30,13 +30,4 @@ of {{i:flow control}} to data production and consumption.
 
 ## Pair
 
-[bus]: bus.md
-[pair]: pair.md
-[push]: push.md
-[pull]: pull.md
-[req]: req.md
-[rep]: rep.md
-[sub]: sub.md
-[pub]: pub.md
-[respondent]: respondent.md
-[surveyor]: surveyor.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/pair.md b/docs/ref/proto/pair.md
index 13442f58..5c6e9c41 100644
--- a/docs/ref/proto/pair.md
+++ b/docs/ref/proto/pair.md
@@ -5,7 +5,7 @@ relationships between peers are one-to-one.
 
 ### Socket Operations
 
-The [`nng_pair_open`][nng_pair_open] functions create a _PAIR_ socket.
+The [`nng_pair0_open`] and [`nng_pair1_open`] functions create a _PAIR_ socket.
 
 Normally, this pattern will block when attempting to send a message if
 no peer is able to receive the message.
@@ -25,8 +25,7 @@ information, and is suitable when building simple one-to-one topologies.
 
 > [!TIP]
 > Use version 0 if you need to communicate with other implementations,
-> including the legacy [libnanomsg][nanomsg] library or
-> [mangos][mangos].
+> including the legacy [libnanomsg] library or [mangos].
 
 Version 1 of the protocol offers improved protection against loops when
 used with [devices][device].
@@ -45,7 +44,7 @@ peer.
 
 _Polyamorous_{{hi:polyamorous mode}} changes this, to allow a socket to communicate with
 multiple directly-connected peers.
-This mode is enabled by opening a socket using [`nng_pair1_open_poly`][nng_pair_open].
+This mode is enabled by opening a socket using [`nng_pair1_open_poly`].
 
 > [!TIP]
 > Polyamorous mode is only available when using pair version 1.
@@ -53,19 +52,18 @@ This mode is enabled by opening a socket using [`nng_pair1_open_poly`][nng_pair_
 In polyamorous mode a socket can support many one-to-one connections.
 In this mode, the application must
 choose the remote peer to receive an outgoing message by setting the
-[`nng_pipe`][pipe] to use for the outgoing message using
-[`nng_msg_set_pipe`][nng_msg_pipe].
+[`nng_pipe`] to use for the outgoing message using [`nng_msg_set_pipe`].
 
 If no remote peer is specified by the sender, then the protocol will select
 any available connected peer.
 
 Most often the value of the outgoing pipe will be obtained from an incoming
-message using [`nng_msg_get_pipe`][nng_msg_pipe],
+message using [`nng_msg_get_pipe`].
 such as when replying to an incoming message.
 
 > [!NOTE]
 > Directed send _only_ works with directly connected peers.
-> It will not function across [device][device] proxies.
+> It will not function across [device] proxies.
 
 In order to prevent head-of-line blocking, if the peer on the given pipe
 is not able to receive (or the pipe is no longer available, such as if the
@@ -76,13 +74,13 @@ to the sender.
 
 The following protocol-specific options are available.
 
-- [`NNG_OPT_MAXTTL`][NNG_OPT_MAXTTL]:
+- [`NNG_OPT_MAXTTL`]:
   (`int`, version 1 only). Maximum time-to-live.
 
 - `NNG_OPT_PAIR1_POLY`:
   (`bool`, version 1 only) This option is no longer supported.
   Formerly it was used to configure _polyamorous_ mode, but that mode
-  is now established by using the `nng_pair1_open_poly` function.
+  is now established by using the [`nng_pair1_open_poly`] function.
 
 ### Protocol Headers
 
@@ -90,17 +88,9 @@ Version 0 of the pair protocol has no protocol-specific headers.
 
 Version 1 of the pair protocol uses a single 32-bit unsigned value. The
 low-order (big-endian) byte of this value contains a "hop" count, and is
-used in conjunction with the
-[`NNG_OPT_MAXTTL`][NNG_OPT_MAXTTL] option to guard against
+used in conjunction with the [`NNG_OPT_MAXTTL`] option to guard against
 device forwarding loops.
 This value is initialized to 1, and incremented each time the message is
 received by a new node.
 
-[nng_pair_open]: TODO.md
-[NNG_OPT_MAXTTL]: TODO.md
-[device]: TODO.md
-[nanomsg]: TODO.md
-[mangos]: TODO.md
-[pipe]: TODO.md
-[nng_msg_pipe]: ../api/msg/nng_msg_pipe.md
-[req]: ./req.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/pub.md b/docs/ref/proto/pub.md
index 55292f7a..40fccb24 100644
--- a/docs/ref/proto/pub.md
+++ b/docs/ref/proto/pub.md
@@ -22,9 +22,9 @@ Applications should construct their messages accordingly.
 
 ## Socket Operations
 
-The [`nng_pub0_open`][nng_pub_open] functions create a publisher socket.
+The [`nng_pub0_open`] function creates a publisher socket.
 This socket may be used to send messages, but is unable to receive them.
-Attempts to receive messages will result in `NNG_ENOTSUP`.
+Attempts to receive messages will result in [`NNG_ENOTSUP`].
 
 ## Protocol Versions
 
@@ -39,4 +39,4 @@ The _PUB_ protocol has no protocol-specific options.
 
 The _PUB_ protocol has no protocol-specific headers.
 
-[nng_pub_open]: TODO.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/pull.md b/docs/ref/proto/pull.md
index 9946a887..1ada5514 100644
--- a/docs/ref/proto/pull.md
+++ b/docs/ref/proto/pull.md
@@ -13,8 +13,7 @@ This property makes this pattern useful in {{i:load-balancing}} scenarios.
 
 ### Socket Operations
 
-The [`nng_pull0_open`][nng_pull_open] functions create a
-_PULL_ socket.
+The [`nng_pull0_open`] function creates a _PULL_ socket.
 This socket may be used to receive messages, but is unable to send them.
 Attempts to send messages will result in `NNG_ENOTSUP`.
 
@@ -36,5 +35,4 @@ The _PULL_ protocol has no protocol-specific options.
 
 The _PULL_ protocol has no protocol-specific headers.
 
-[nng_pull_open]: TODO.md
-[push]: ./push.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/push.md b/docs/ref/proto/push.md
index e0218bbd..65ec0d22 100644
--- a/docs/ref/proto/push.md
+++ b/docs/ref/proto/push.md
@@ -13,7 +13,7 @@ This property makes this pattern useful in {{i:load-balancing}} scenarios.
 
 ### Socket Operations
 
-The [`nng_push0_open`][nng_push_open] call creates a _PUSH_ socket.
+The [`nng_push0_open`] function creates a _PUSH_ socket.
 This socket may be used to send messages, but is unable to receive them.
 Attempts to receive messages will result in `NNG_ENOTSUP`.
 
@@ -36,7 +36,7 @@ Only version 0 of this protocol is supported.
 
 ### Protocol Options
 
-- [`NNG_OPT_SENDBUF`][NNG_OPT_SENDBUF]:
+- [`NNG_OPT_SENDBUF`]:
   (`int`, 0 - 8192)
   Normally this is set to zero, indicating that send operations are unbuffered.
   In unbuffered operation, send operations will wait until a suitable peer is available to receive the message.
@@ -51,7 +51,4 @@ Only version 0 of this protocol is supported.
 
 The _PUSH_ protocol has no protocol-specific headers.
 
-[nng_push_open]: TODO.md
-[NNG_OPT_SENDBUF]: TODO.md
-[pull]: ./pull.md
-[req]: ./req.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/rep.md b/docs/ref/proto/rep.md
index e7fe27ed..066011d8 100644
--- a/docs/ref/proto/rep.md
+++ b/docs/ref/proto/rep.md
@@ -16,7 +16,7 @@ The _REP_ protocol is the replier side, and the
 
 ## Socket Operations
 
-The [`nng_rep0_open`][nng_rep_open] functions create a replier socket.
+The [`nng_rep0_open`] functions create a replier socket.
 This socket may be used to receive messages (requests), and then to send
 replies.
 
@@ -33,7 +33,7 @@ Any additional concurrent receive operations will result in `NNG_ESTATE`.
 ## Context Operations
 
 This protocol supports the creation of [contexts][context] for concurrent
-use cases using [`nng_ctx_open`][nng_ctx_open].
+use cases using [`nng_ctx_open`].
 
 Each context may have at most one outstanding request, and operates
 independently of the others.
@@ -55,8 +55,4 @@ The _REP_ protocol has no protocol-specific options.
 The _REP_ protocol uses a {{ii:backtrace}} in the header.
 This is more fully documented in the [_REQ_][req] chapter.
 
-[nng_rep_open]: TODO.md
-[nng_ctx_open]: TODO.md
-[raw]: TODO.md
-[context]: TODO.md
-[req]: ./req.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/req.md b/docs/ref/proto/req.md
index e50662c3..0fa62451 100644
--- a/docs/ref/proto/req.md
+++ b/docs/ref/proto/req.md
@@ -23,15 +23,14 @@ in [raw mode][raw],
 and it will generally attempt to spread work requests to different peer repliers.
 
 > [!TIP]
-> This property, when combined with a [device][device]
-> can help provide a degree of load-balancing.
+> This property, when combined with a [device] can help provide a degree of load-balancing.
 
 The _REQ_ protocol is the requester side, and the [_REP_][rep] protocol
 is the replier side.
 
 ### Socket Operations
 
-The [`nng_req0_open`][nng_req_open] functions create a _REQ_ socket.
+The [`nng_req0_open`] function creates a _REQ_ socket.
 This socket may be used to send messages (requests), and then to receive replies.
 
 Generally a reply can only be received after sending a request.
@@ -53,7 +52,7 @@ that has already been placed on the wire.
 ### Context Operations
 
 This protocol supports the creation of [contexts][context] for concurrent
-use cases using [`nng_ctx_open`][nng_ctx_open].
+use cases using [`nng_ctx_open`].
 
 The `NNG_OPT_REQ_RESENDTIME` value may be configured differently
 on contexts created this way.
@@ -75,7 +74,7 @@ Only version 0 of this protocol is supported.
 The following protocol-specific option is available.
 
 - {{i:`NNG_OPT_REQ_RESENDTIME`}}: \
-  ([`nng_duration`][duration]) \
+  ([`nng_duration`]) \
   When a new request is started, a timer of this duration is also started.
   If no reply is received before this timer expires, then the request will
   be resent. \
@@ -85,11 +84,11 @@ The following protocol-specific option is available.
   \
   Resending may be deferred up to the value of the `NNG_OPT_RESENDTICK` parameter. \
   \
-  If the value is set to [`NNG_DURATION_INFINITE`][duration], then resends are disabled
+  If the value is set to [`NNG_DURATION_INFINITE`], then resends are disabled
   altogether. This should be used when the request is not idemptoent.
 
 - {{i:`NNG_OPT_REQ_RESENDTICK`}}: \
-  ([`nng_duration`][duration]) \
+  ([`nng_duration`]) \
   This is the granularity of the clock that is used to check for resending.
   The default is a second. Setting this to a higher rate will allow for
   more timely resending to occur, but may incur significant additional
@@ -111,7 +110,7 @@ There may be additional **peer ID**s preceding the request ID.
 These will be distinguishable from the request ID by having their most
 significant bit clear.
 
-When a request message is received by a forwarding node (such as a [device][device]),
+When a request message is received by a forwarding node (such as a [device]),
 the forwarding node prepends a
 32-bit peer ID (which _must_ have the most significant bit clear),
 which is the forwarder's way of identifying the directly connected
@@ -135,10 +134,4 @@ When the reply finally arrives back at the initiating requester, it
 should have only a single element in the message, which will be the
 request ID it originally used for the request.
 
-[nng_req_open]: TODO.md
-[nng_ctx_open]: TODO.md
-[raw]: TODO.md
-[device]: TODO.md
-[context]: TODO.md
-[rep]: ./rep.md
-[duration]: ../api/util/nng_duration.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/respondent.md b/docs/ref/proto/respondent.md
index 0f101550..ada44928 100644
--- a/docs/ref/proto/respondent.md
+++ b/docs/ref/proto/respondent.md
@@ -17,7 +17,7 @@ The _RESPONDENT_ protocol is the respondent side, and the
 
 ### Socket Operations
 
-The [`nng_respondent0_open`][nng_respondent_open] functions create a
+The [`nng_respondent0_open`] functions create a
 respondent socket.
 This socket may be used to receive messages, and then to send replies.
 A reply can only be sent after receiving a survey, and generally the
@@ -30,7 +30,7 @@ Respondents may discard a survey by simply not replying to it.
 ### Context Operations
 
 This protocol supports the creation of [contexts][context] for concurrent
-use cases using [`nng_ctx_open`][nng_ctx_open].
+use cases using [`nng_ctx_open`].
 
 Incoming surveys will be routed to and received by only one context.
 Additional surveys may be received by other contexts in parallel.
@@ -45,7 +45,7 @@ a separate socket.
 Only version 0 of this protocol is supported.
 At the time of writing, no other versions of this protocol have been defined.
 {{footnote: An earlier and incompatible version of the protocol was used in older
-pre-releases of [nanomsg][nanomsg], but was not released in any production version.}}
+pre-releases of [libnanomsg], but was not released in any production version.}}
 
 ### Protocol Options
 
@@ -56,9 +56,4 @@ The _respondent_ protocol has no protocol-specific options.
 The _RESPONDENT_ protocol uses a {{ii:backtrace}} in the header.
 This is more fully documented in the [_SURVEYOR_][surveyor] manual.
 
-[nng_respondent_open]: TODO.md
-[nng_ctx_open]: TODO.md
-[nanomsg]: TODO.md
-[context]: TODO.md
-[raw]: TODO.md
-[surveyor]: ./surveyor.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/sub.md b/docs/ref/proto/sub.md
index dd9e0363..5234b6fb 100644
--- a/docs/ref/proto/sub.md
+++ b/docs/ref/proto/sub.md
@@ -19,9 +19,9 @@ Applications should construct their messages accordingly.
 
 ### Socket Operations
 
-The [`nng_sub0_open`][nng_sub_open] functions create a _SUB_ socket.
+The [`nng_sub0_open`] functions create a _SUB_ socket.
 This socket may be used to receive messages, but is unable to send them.
-Attempts to send messages will result in `NNG_ENOTSUP`.
+Attempts to send messages will result in [`NNG_ENOTSUP`].
 
 ### Protocol Versions
 
@@ -43,6 +43,4 @@ The following protocol-specific option is available.
 
 The _SUB_ protocol has no protocol-specific headers.
 
-[nng_sub_open]: TODO.md
-[nng_socket_set]: TODO.md
-[pub]: ./pub.md
+{{#include ../xref.md}}
diff --git a/docs/ref/proto/surveyor.md b/docs/ref/proto/surveyor.md
index 5222b629..d0a882f2 100644
--- a/docs/ref/proto/surveyor.md
+++ b/docs/ref/proto/surveyor.md
@@ -17,7 +17,7 @@ The _SURVEYOR_ protocol is the surveyor side, and the
 
 ### Socket Operations
 
-The [`nng_surveyor0_open`][nng_surveyor_open]
+The [`nng_surveyor0_open`]
 functions create a surveyor socket.
 This socket may be used to send messages (surveys), and then to receive replies.
 A reply can only be received after sending a survey.
@@ -26,9 +26,9 @@ A surveyor can normally expect to receive at most one reply from each responder.
 so there is no guarantee of this.)
 
 Attempts to receive on a socket with no outstanding survey will result
-in `NNG_ESTATE`.
+in [`NNG_ESTATE`].
 If the survey times out while the surveyor is waiting
-for replies, then the result will be `NNG_ETIMEDOUT`.
+for replies, then the result will be [`NNG_ETIMEDOUT`].
 
 Only one survey can be outstanding at a time; sending another survey will
 cancel the prior one, and any responses from respondents from the prior
@@ -39,7 +39,7 @@ survey that arrive after this will be discarded.
 ### Context Operations
 
 This protocol supports the creation of [contexts][context] for concurrent
-use cases using [`nng_ctx_open`][nng_ctx_open].
+use cases using [`nng_ctx_open`].
 
 Each context can initiate its own surveys, and it will receive only
 responses to its own outstanding surveys.
@@ -62,14 +62,14 @@ survey on the same context.
 Only version 0 of this protocol is supported.
 At the time of writing, no other versions of this protocol have been defined.
 {{footnote: An earlier and incompatible version of the protocol was used in older
-pre-releases of [nanomsg][nanomsg], but was not released in any production version.}}
+pre-releases of [libnanomsg], but was not released in any production version.}}
 
 ### Protocol Options
 
 The following protocol-specific option is available.
 
 - {{i:`NNG_OPT_SURVEYOR_SURVEYTIME`}}: \
-   ([`nng_duration`][duration]) \
+   ([`nng_duration`]) \
    \
    When a new survey is started, a timer of this duration is started.
   Any responses arriving this time will be discarded.
@@ -91,8 +91,7 @@ There may be additional **peer ID**s preceding the survey ID.
 These will be distinguishable from the survey ID by having their most
 significant bit clear.
 
-When a survey message is received by a forwarding node (such as a
-[device][device]),
+When a survey message is received by a forwarding node (such as a [device]),
 the forwarding node prepends a
 32-bit peer ID (which _must_ have the most significant bit clear),
 which is the forwarder's way of identifying the directly connected
@@ -118,12 +117,6 @@ survey ID it originally used for the request.
 
 More detail can be found in the [sp-surveyor-01 RFC][survey_rfc] document.
 
-[nng_surveyor_open]: TODO.md
-[nng_ctx_open]: TODO.md
-[context]: TODO.md
-[nanomsg]: TODO.md
-[raw]: TODO.md
+{{#include ../xref.md}}
+
 [survey_rfc]: TODO.md
-[device]: TODO.md
-[duration]: ../api/util/nng_duration.md
-[respondent]: ./respondent.md