docs: master cross-reference table

docs/ref/api/id_map.md

@@ -31,7 +31,7 @@ themselves be much larger than this.}}
 
 > [!IMPORTANT]
 > The function available for `nng_id_map` are _not_ thread-safe.
-> Callers should use a [mutex][nng_mutex] or similar approach when thread-safety is needed.
+> Callers should use a [mutex] or similar approach when thread-safety is needed.
 
 ## Create ID Map
 
@@ -55,7 +55,7 @@ the same identifiers at the same time.
 If both _lo_ and _hi_ are zero, then the values `0` and `0xffffffff` are substituted
 in their place, giving a full range of 32-bit identifiers.
 
-This function can return `NNG_ENOMEM` if it is unable to allocate resources, otherwise
+This function can return [`NNG_ENOMEM`] if it is unable to allocate resources, otherwise
 it returns zero on success.
 
 ## Destroy Map
@@ -87,7 +87,7 @@ _value_.
 > The _value_ must not be `NULL`.
 
 If the table has to grow to accommodate this value, it may fail if insufficient
-memory is available, returning `NNG_ENOMEM`. OtherwiseG it returns zero.
+memory is available, returning [`NNG_ENOMEM`]. Otherwise it returns zero.
 
 ## Lookup a Value
 
@@ -115,11 +115,11 @@ when they were freed.{{footnote: The concern about possibly reusing a
 recently released identifier comes into consideration after the range has wrapped.
 Given a sufficiently large range, this is unlikely to be a concern.}}
 
-As with [`nng_id_set`][nng_id_set], this may need to allocate memory and can thus
-fail with `NNG_ENOMEM`.
+As with [`nng_id_set`], this may need to allocate memory and can thus
+fail with [`NNG_ENOMEM`].
 
 Additionally, if there are no more free identifiers within the range specified
-when _map_ was created, then it will return `NNG_ENOSPC`.
+when _map_ was created, then it will return [`NNG_ENOSPC`].
 
 Otherwise it returns zero, indicating success.
 
@@ -131,7 +131,7 @@ int nng_id_remove(nng_id_map *map, uint64_t id);
 
 The {{i:`nng_id_remove`}} removes the entry at index _id_ from _map_.
 
-If no such entry exist, it will return `NNG_ENOENT`. Otherwise it returns zero.
+If no such entry exist, it will return [`NNG_ENOENT`]. Otherwise it returns zero.
 
 ## Iterating IDs
 
@@ -155,5 +155,4 @@ iteration is undefined; entries may be repeated or omitted during such an iterat
 The caller must not attempt to derive any value of the _cursor_ as it refers to internal
 table indices.
 
-[nng_id_set]: #store-a-value
-[nng_mutex]: synch.md#mutual-exclusion-lock
+{{#include ../xref.md}}

docs/ref/api/memory.md

@@ -17,11 +17,11 @@ The memory will be 64-bit aligned.
 Note that the memory may have random data in it, just like with `malloc`.
 
 If memory cannot be allocated for any reason, then `NULL` will be returned.
-Applications that experience this should treat this like `NNG_ENOMEM`.
+Applications that experience this should treat this like [`NNG_ENOMEM`].
 
 Memory returned by `nng_alloc` can be used to hold message buffers, in which
-case it can be directly passed to [`nng_send`][nng_send] using the flag `NNG_FLAG_ALLOC`.
-Alternatively, it can be freed when no longer needed using [`nng_free`][nng_free].
+case it can be directly passed to [`nng_send`] using the flag `NNG_FLAG_ALLOC`.
+Alternatively, it can be freed when no longer needed using [`nng_free`].
 
 > [!IMPORTANT]
 > Do not use the system `free` function (or the C++ `delete` operator) to release this memory.
@@ -34,10 +34,10 @@ Alternatively, it can be freed when no longer needed using [`nng_free`][nng_free
 void nng_free(void *ptr, size_t size);
 ```
 
-The {{i:`nng_free`}} function deallocates memory previously allocated by [`nng_alloc`][nng_alloc].
+The {{i:`nng_free`}} function deallocates memory previously allocated by [`nng_alloc`].
 
 The _size_ argument must exactly match the _size_ argument that was supplied to
-`nng_alloc` when the memory was allocated.
+[`nng_alloc`] when the memory was allocated.
 
 ## Duplicate String
 
@@ -47,14 +47,14 @@ char *nng_strdup(const char *src);
 
 The {{i:`nng_strdup`}} duplicates the string _src_ and returns it.
 
-This is logically equivalent to using [`nng_alloc`][nng_alloc]
+This is logically equivalent to using [`nng_alloc`]
 to allocate a region of memory of `strlen(s) + 1` bytes, and then
 using `strcpy` to copy the string into the destination before
 returning it.
 
 The returned string should be deallocated with
-[`nng_strfree`][nng_strfree], or may be deallocated using the
-[`nng_free`][nng_free] using the length of the returned string plus
+[`nng_strfree`], or may be deallocated using the
+[`nng_free`] using the length of the returned string plus
 one (for the `NUL` terminating byte).
 
 ## Free String
@@ -64,12 +64,8 @@ void nng_strfree(char *str);
 ```
 
 The {{i:`nng_strfree`}} function is a convenience function that
-can be used to deallocate strings allocated with [`nng_strdup`][nng_strdup].
+can be used to deallocate strings allocated with [`nng_strdup`].
 
 It is effectively the same as `nng_free(strlen(str) + 1)`.
 
-[nng_alloc]: #allocate-memory
-[nng_free]: #deallocate-memory
-[nng_strdup]: #duplicate-string
-[nng_strfree]: #free-string
-[nng_send]: TODO.md
+{{#include ../xref.md}}

docs/ref/api/misc.md

@@ -22,7 +22,7 @@ int nng_socket_pair(int fds[2]);
 
 The `nng_socket_pair` function creates a pair of connected file descriptors.
 These file descriptors, which are returned in the _fds_ array, are suitable for
-use with the [Socket transport][socket].
+use with the [Socket transport][socktran].
 
 On POSIX platforms, this is a thin wrapper around the standard `socketpair` function,
 using the {{i:`AF_UNIX`}} family and the `SOCK_STREAM` socket type.
@@ -58,4 +58,4 @@ the version numbers reported refer to both the API and the library itself.
 library and the application is controlled in a similar, but different
 manner depending upon the link options and how the library is built.)
 
-[socket]: ../tran/socket.md
+{{#include ../xref.md}}

docs/ref/api/msg.md

@@ -30,7 +30,7 @@ The {{i:`nng_msg_alloc`}} function allocates a new message.
 It takes a _size_ argument, and returns a message
 with a preallocated body of that size in the _msgp_ parameter.
 
-If it succeeds, it returns zero, otherwise this function may return `NNG_ENOMEM`,
+If it succeeds, it returns zero, otherwise this function may return [`NNG_ENOMEM`],
 indicating that insufficient memory is available to allocate a new message.
 
 ### Destroy a Message
@@ -48,7 +48,7 @@ int nng_msg_dup(nng_msg **dup, nng_msg *msg);
 ```
 
 The {{i:`nng_msg_dup`}} function duplicates the message _msg_, storing a pointer
-to the new duplicate in _dup_. This function also returns zero on succes, or `NNG_ENOMEM`
+to the new duplicate in _dup_. This function also returns zero on succes, or [`NNG_ENOMEM`]
 if memory is exhausted.
 
 ## Message Size and Capacity
@@ -79,14 +79,13 @@ preserving contents while doing so.
 If the new size is smaller than the original message, it will
 truncate the message, but not perform any allocations.
 If reallocation fails due to insufficient memory, then the original is left intact.
-This function returns either zero, or `NNG_ENOMEM`.
 
 The {{i:`nng_msg_reserve`}} function ensures that the total message capacity
 is at least _capacity_ bytes. Use of this function to ensure the total anticipated
 capacity is present in the message may help prevent many small allocations.
 
 Both `nng_msg_realloc` and `nng_msg_reserve` return zero on success, or may return
-`NNG_ENOMEM` if insufficient memory exists to preform allocation.
+[`NNG_ENOMEM`] if insufficient memory exists to preform allocation.
 
 > [!IMPORTANT]
 > Any pointers to message content obtained before a call to `nng_msg_realloc` or
@@ -205,16 +204,16 @@ The {{i:`nng_msg_header_clear`}} simply resets the total message header length t
 Appending data to a message header is done by using the {{i:`nng_msg_header_append`}} functions,
 and inserting data in the header is done using the {{i:`nng_msg_header_insert`}} functions.
 
-These functions act just like the [`nng_msg_append`][nng_msg_append] and [`nng_msg_insert`][nng_msg_insert]
-functions, except that they operate on the message header rather than the message body.
+These functions act just like the [`nng_msg_append`] and [`nng_msg_insert`] functions,
+except that they operate on the message header rather than the message body.
 
 ### Consume from Header
 
 The {{i:`nng_msg_header_trim`}} functions remove data from the beginning of the message header,
 and the {{i:`nng_msg_header_chop`}} functions remove data from the end of the message header.
 
-These functions act just like the [`nng_msg_trim`][nng_msg_trim] and [`nng_msg_chop`][nng_msg_chop]
-functions, except that they operate the message header rather than the message body.
+These functions act just like the [`nng_msg_trim`] and [`nng_msg_chop`] functions,
+except that they operate the message header rather than the message body.
 
 ## Message Pipe
 
@@ -223,7 +222,7 @@ nng_pipe nng_msg_get_pipe(nng_msg *msg);
 void nng_msg_get_pipe(nng_msg *msg, nng_pipe p);
 ```
 
-The {{i:`nng_msg_set_pipe`}} function sets the [pipe][pipe] associated with _msg_ to _p_.
+The {{i:`nng_msg_set_pipe`}} function sets the [pipe] associated with _msg_ to _p_.
 This is most often useful when used with protocols that support directing
 a message to a specific peer.
 For example the [_PAIR_][pair] version 1 protocol can do
@@ -262,13 +261,4 @@ either directly by the application, or when the message was received by the prot
     }
 ```
 
-[nng_msg_body]: #message-body
-[nng_msg_header]: #message-header
-[nng_msg_append]: #add-to-body
-[nng_msg_insert]: #add-to-body
-[nng_msg_trim]: #consume-from-body
-[nng_msg_chop]: #consume-from-body
-[nng_msg_header_append]: #append-or-insert-header
-[raw]: TODO.md
-[pair]: ../proto/pair.md
-[pipe]: TODO.md
+{{#include ../xref.md}}

docs/ref/api/stats.md

@@ -36,7 +36,7 @@ int nng_stats_get(nng_stat **statsp);
 
 The {{i:`nng_stats_get`}} function takes a snapshot of the statistics for
 the system and returns it through the pointer _statsp_.
-This function may return `NNG_ENOMEM` if memory is exhausted, or `NNG_ENOTSUP` if the statistics
+This function may return [`NNG_ENOMEM`] if memory is exhausted, or [`NNG_ENOTSUP`] if the statistics
 support is not enabled in the build, but is otherwise expected to return zero.
 
 ## Freeing a Snapshot
@@ -77,8 +77,8 @@ const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
 ```
 
 Sometimes it is easiest to search for a specific statistic, matching by name,
-or possibly to find the tree of statistics associated iwth a specific [socket][nng_socket],
-[dialer][nng_dialer], or [listener][nng_listener].
+or possibly to find the tree of statistics associated iwth a specific [socket],
+[dialer], or [listener].
 
 The `nng_stat_find` functions are provided for this purpose.
 
@@ -121,31 +121,31 @@ function can be used to obtain that value.
   The statistic is a counter that only increments.
   Usually the change in the value of the statistic is more interesting
   (as a rate) than the absolute value at any given time. The value should
-  be obtained using [`nng_stat_value`][nng_stat_value].
-  The units will be given by the value returned from [`nng_stat_unit`][nng_stat_unit].
+  be obtained using [`nng_stat_value`].
+  The units will be given by the value returned from [`nng_stat_unit`].
 
 - {{i:`NNG_STAT_LEVEL`}}: <a name="NNG_STAT_LEVEL"></a>
   The statistic represnts a measured value which corresponds
   to a specific value at a specific time. For example, this may represent the
   number of messages currently queued for some operation, or the link speed
   of a network interface. Most often the absolute value is more interesting
   than the change in the value over time. Again the value can be obtained with
-  [`nng_stat_value`][nng_stat_value], and any appropriate unit of measurement
-  with [`nng_stat_unit`][nng_stat_unit].
+  [`nng_stat_value`], and any appropriate unit of measurement
+  with [`nng_stat_unit`].
 
 - {{i:`NNG_STAT_STRING`}}: <a name="NNG_STAT_STRING"></a>
   The statistic is a string, such as a name. The value
-  of the string can be obtained with [`nng_stat_string`][nng_stat_string].
+  of the string can be obtained with [`nng_stat_string`].
   The value of this string
-  will remain valid until the snapshot is deallocated with [`nng_stats_free`][nng_stats_free].
+  will remain valid until the snapshot is deallocated with [`nng_stats_free`].
 
 - {{i:`NNG_STAT_BOOLEAN`}}: <a name="NNG_STAT_BOOLEAN"></a>
   The value of the statistic is a truth value (either `true`
-  or `false`) and can be obtained with [`nng_stat_bool`][nng_stat_bool].
+  or `false`) and can be obtained with [`nng_stat_bool`].
 
 - {{i:`NNG_STAT_ID`}}: <a name="NNG_STAT_ID"></a>
   The value of the statistic is a numeric identifier, such as a socket
-  identifier. The value can be obtained with [`nng_stat_value`][nng_stat_value],
+  identifier. The value can be obtained with [`nng_stat_value`],
   and will be fixed for the life of the statistic.
 
 ## Statistic Value
@@ -159,15 +159,15 @@ bool nng_stat_bool(const nng_stat *stat);
 These functions return the value associated with the statistic.
 
 The {{i:`nng_stat_value`}} function returns the the numeric value for the statistic _stat_
-of type [`NNG_STAT_COUNTER`][NNG_STAT_COUNTER], [`NNG_STAT_LEVEL`][NNG_STAT_LEVEL], or [`NNG_STAT_ID`][NNG_STAT_ID].
+of type [`NNG_STAT_COUNTER`], [`NNG_STAT_LEVEL`], or [`NNG_STAT_ID`].
 If _stat_ is not one of these types, then it returns zero.
 
 The {{i:`nng_stat_bool`}} function returns the Boolean value (either `true` or `false`) for the statistic _stat_ of
-type [`NNG_STAT_BOOLEAN`][NNG_STAT_BOOLEAN]. If the statistics is not of this type, then it returns `false`.
+type [`NNG_STAT_BOOLEAN`]. If the statistics is not of this type, then it returns `false`.
 
 The {{i:`nng_stat_string`}} function returns a pointer to a string value for the statistic _stat_,
-of type [`NNG_STAT_STRING`][NNG_STAT_STRING]. This string will remain valud until the snapshot that
-_stat_ was collected with is deallocated with [`nng_stats_free`][nng_stats_free]. If the statistic
+of type [`NNG_STAT_STRING`]. This string will remain valud until the snapshot that
+_stat_ was collected with is deallocated with [`nng_stats_free`]. If the statistic
 is not of type `NNG_STAT_STRING`, then `NULL` is returned.
 
 ## Statistic Units
@@ -176,7 +176,7 @@ is not of type `NNG_STAT_STRING`, then `NULL` is returned.
 int nng_stat_unit(const nng_stat *stat);
 ```
 
-For statistics of type [`NNG_STAT_COUNTER`][NNG_STAT_COUNTER] or [`NNG_STAT_LEVEL`][NNG_STAT_LEVEL],
+For statistics of type [`NNG_STAT_COUNTER`] or [`NNG_STAT_LEVEL`],
 it is often useful to know what that quantity being reported measures.
 The following units may be returned from {{i:`nng_stat_unit`}} for such a statistic:
 
@@ -195,25 +195,10 @@ uint64_t nng_stat_timestamp(const nng_stat *stat);
 Statistics have a timestamp indicating when the value was sampled,
 obtained via {{i:`nng_stat_timestamp`}}. The timestamp is given in
 in milliseconds since a reference time, and the reference time used
-here is the same reference time used for [`nng_clock`][nng_clock].
+here is the same reference time used for [`nng_clock`].
 
 ## See Also
 
-[`nng_clock`][nng_clock]
-
-[nng_stat_type]: #statistic-type
-[nng_stats_free]: #freeing-a-snapshot
-[nng_stat_value]: #statistic-value
-[nng_stat_bool]: #statistic-value
-[nng_stat_string]: #statistic-value
-[nng_stat_unit]: #statistic-units
-[NNG_STAT_ID]: #NNG_STAT_ID
-[NNG_STAT_COUNTER]: #NNG_STAT_COUNTER
-[NNG_STAT_LEVEL]: #NNG_STAT_LEVEL
-[NNG_STAT_SCOPE]: #NNG_STAT_SCOPE
-[NNG_STAT_STRING]: #NNG_STAT_STRING
-[NNG_STAT_BOOLEAN]: #NNG_STAT_BOOLEAN
-[nng_clock]: ./time.md#getting-the-current-time
-[nng_socket]: TODO.md
-[nng_dialer]: TODO.md
-[nng_listener]: TODO.md
+[`nng_clock`]
+
+{{#include ../xref.md}}