Converted condition variable docs to mdbook.

This also is implemented using a single unified manual page
that should be easier to reference.

11 files changed, 124 insertions, 402 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index c6c5b311..b787c7e8 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -283,12 +283,12 @@ as a convenience to aid in creating portable applications.
 
 |===
 // |xref:nng_clock.3supp.adoc[nng_clock()]|get time
-|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable
-|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable
-|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout
-|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition
-|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters
-|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter
+// |xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable
+// |xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable
+// |xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout
+// |xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition
+// |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters
+// |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter
 // |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table
 // |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds
 // |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex
diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc
deleted file mode 100644
index f87f70f8..00000000
--- a/docs/man/nng_cv_alloc.3supp.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-= nng_cv_alloc(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_alloc - allocate condition variable
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_cv nng_cv;
-
-int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx);
-----
-
-== DESCRIPTION
-
-The `nng_cv_alloc()` function allocates a condition variable, using
-the mutex _mtx_, and returns it in _cvp_.
-
-Every condition variable is associated with a mutex, which must be
-owned when a thread waits for the condition using
-xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or
-xref:nng_cv_until.3supp.adoc[`nng_cv_until()`].
-The mutex must also be owned when signaling the condition using the
-xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or
-xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] functions.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_free.3supp.adoc[nng_cv_free(3supp)],
-xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)],
-xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)],
-xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)],
-xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_cv_free.3supp.adoc b/docs/man/nng_cv_free.3supp.adoc
deleted file mode 100644
index 82eeb033..00000000
--- a/docs/man/nng_cv_free.3supp.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-= nng_cv_free(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_free - free condition variable
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_cv_free(nng_cv *cv);
-----
-
-== DESCRIPTION
-
-The `nng_cv_free()` function frees the condition variable _cv_.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc
deleted file mode 100644
index a168599d..00000000
--- a/docs/man/nng_cv_until.3supp.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-= nng_cv_until(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_until - wait for condition or timeout
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_cv_until(nng_cv *cv, nng_time when);
-----
-
-== DESCRIPTION
-
-The `nng_cv_until()` waits until either the condition variable _cv_ is signaled
-by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or
-xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`], or the system clock (as tracked
-by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_.
-
-The caller must have have ownership of the mutex that was used when
-_cv_ was allocated.
-This function will drop the ownership of that mutex, and reacquire it
-atomically just before returning to the caller.
-(The waiting is done without holding the mutex.)
-
-NOTE: Any condition may be used or checked, but the condition must be
-checked, as it is possible for this function to wake up spuriously.
-The best way to do this is inside a loop that repeats until the condition
-tests for true.
-
-== EXAMPLE
-
-The following example demonstrates use of this function:
-
-.Example 1: Waiting for the condition
-[source, c]
-----
-
-    expire = nng_clock() + 1000; // 1 second in the future
-    nng_mtx_lock(m);  // assume cv was allocated using m
-    while (!condition_true) {
-        if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
-            printf("Time out reached!\n");
-            break;
-        }
-    }
-    // condition_true is true
-    nng_mtx_unlock(m);
-----
-
-.Example 2: Signaling the condition
-[source, c]
-----
-    nng_mtx_lock(m);
-    condition_true = true;
-    nng_cv_wake(cv);
-    nng_mtx_unlock(m);
-----
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)],
-xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)],
-xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc
deleted file mode 100644
index 9078ac44..00000000
--- a/docs/man/nng_cv_wait.3supp.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-= nng_cv_wait(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_wait - wait for condition
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_cv_wait(nng_cv *cv);
-----
-
-== DESCRIPTION
-
-The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled
-by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or
-xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`].
-
-The caller must have have ownership of the mutex that was used when
-_cv_ was allocated.
-This function will drop the ownership of that mutex, and reacquire it
-atomically just before returning to the caller.
-(The waiting is done without holding the mutex.)
-
-NOTE: Any condition may be used or checked, but the condition must be
-checked, as it is possible for this function to wake up spuriously.
-The best way to do this is inside a loop that repeats until the condition
-tests for true.
-
-== EXAMPLE
-
-The following example demonstrates use of this function:
-
-.Example 1: Waiting for the condition
-[source, c]
-----
-
-    nng_mtx_lock(m);  // assume cv was allocated using m
-    while (!condition_true) {
-        nng_cv_wait(cv);
-    }
-    // condition_true is true
-    nng_mtx_unlock(m);
-----
-
-.Example 2: Signaling the condition
-[source, c]
-----
-    nng_mtx_lock(m);
-    condition_true = true;
-    nng_cv_wake(cv);
-    nng_mtx_unlock(m);
-----
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)],
-xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)],
-xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc
deleted file mode 100644
index a4fe2eca..00000000
--- a/docs/man/nng_cv_wake.3supp.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= nng_cv_wake(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_wake - wake all waiters
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_cv_wake(nng_cv *cv);
-----
-
-== DESCRIPTION
-
-The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_
-to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or
-xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions.
-
-The caller must have have ownership of the mutex that was used when
-_cv_ was allocated.
-
-NOTE: The caller should already have set the condition that the waiters
-will check, while holding the mutex.
-
-TIP: This function wakes all threads, which is generally safer but can
-lead to a performance problem when there are many waiters, as they are all
-woken simultaneously and may contend for resources.
-See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)],
-xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)],
-xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc
deleted file mode 100644
index de556698..00000000
--- a/docs/man/nng_cv_wake1.3supp.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= nng_cv_wake1(3supp)
-//
-// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
-
-== NAME
-
-nng_cv_wake1 - wake one waiter
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_cv_wake1(nng_cv *cv);
-----
-
-== DESCRIPTION
-
-The `nng_cv_wake1()` wakes at most one thread waiting for the condition
-variable _cv_
-to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or
-xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions.
-
-The caller must have have ownership of the mutex that was used when
-_cv_ was allocated.
-
-NOTE: The caller should already have set the condition that the waiters
-will check, while holding the mutex.
-
-NOTE: The caller cannot predict which waiter will be woken, and so the design must
-ensure that it is sufficient that _any_ waiter be woken.
-When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`].
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)],
-xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)],
-xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)],
-xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)],
-xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)],
-xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)],
-xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index ac627ee4..1d7065c2 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -4,6 +4,7 @@
 
   - [Threading Functions](./api/thr/index.md)
 
+    - [nng_cv](./api/thr/nng_cv.md)
     - [nng_mtx](./api/thr/nng_mtx.md)
 
   - [Utility Functions](./api/util/index.md)
diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md
index d9d168ac..6355cfef 100644
--- a/docs/ref/api/thr/index.md
+++ b/docs/ref/api/thr/index.md
@@ -1,3 +1,4 @@
 # Threading Functions
 
+- [nng_cv](nng_cv.md)
 - [nng_mtx](nng_mtx.md)
diff --git a/docs/ref/api/thr/nng_cv.md b/docs/ref/api/thr/nng_cv.md
new file mode 100644
index 00000000..29a149a0
--- /dev/null
+++ b/docs/ref/api/thr/nng_cv.md
@@ -0,0 +1,115 @@
+# nng_cv
+
+## NAME
+
+nng_cv --- condition variable
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_cv nng_cv;
+
+int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx);
+void nng_cv_free(nng_cv *cv);
+int nng_cv_until(nng_cv *cv, nng_time when);
+void nng_cv_wait(nng_cv *cv);
+void nng_cv_wake(nng_cv *cv);
+void nng_cv_wake1(nng_cv *cv);
+```
+
+## DESCRIPTION
+
+The {{i:`nng_cv`}} structure implements a {{i:condition variable}}, associated with the
+the [mutex][nng_mtx] _mtx_ which was supplied when it was created.
+
+Condition variables provide for a way to wait on an arbitrary condition, and to be woken
+when the condition is signaled.
+The mutex is dropped while the caller is asleep, and reacquired atomically when the caller
+is woken.
+
+> [!IMPORTANT]
+>
+> The caller of `nng_cv_until`, `nng_cv_wait`, `nng_cv_wake`, and `nng_cv_wake1` _must_
+> have ownership of the mutex _mtx_ when calling these functions.
+
+### Initialization and Teardown
+
+The {{i:`nng_cv_alloc`}} function allocates a condition variable, and associated with the mutex _mtx_,
+and returns a pointer to it in _cvp_.
+The {{i:`nng_cv_free`}} function deallocates the condition variable _cv_.
+
+### Waiting for the Condition
+
+The {{i:`nng_cv_until`}} and {{i:`nng_cv_wait`}} functions put the caller to sleep until the condition
+variable _cv_ is signaled, or (in the case of `nng_cv_until`), the specified time _when_
+(as determined by [`nng_clock`][nng_clock] is reached.
+
+While `nng_cv_wait` never fails and so has no return value, the `nng_cv_until` function can
+return `NNG_ETIMEDOUT` if the time is reached before condition _cv_ is signaled by
+either `nng_cv_wake` or `nng_cv_wake1`.
+
+### Signaling the Condition
+
+The {{i:`nng_cv_wake`}} and {{i:`nng_cv_wake1`}} functions wake threads waiting in
+`nng_cv_until` or `nng_cv_wake`. The difference between these functions is that
+`nng_cv_wake` will wake _every_ thread, whereas `nng_cv_wake1` will wake up exactly
+one thread (which may be chosen randomly).
+
+> [!TIP]
+> Use of `nng_cv_wake1` may be used to reduce the "thundering herd" syndrom of waking
+> all threads concurrently, but should only be used in circumstances where the application
+> does not depend on _which_ thread will be woken. When in doubt, `nng_cv_wake` is safer.
+
+## EXAMPLE
+
+### Example 1: Allocating the condition variable
+
+```c
+	nng_mtx *m;
+	nng_cv *cv;
+	nng_mtx_alloc(&m); // error checks elided
+	nng_cv_alloc(&cv, m);
+```
+
+### Example 2: Waiting for the condition
+
+```c
+    expire = nng_clock() + 1000; // 1 second in the future
+    nng_mtx_lock(m);  // assume cv was allocated using m
+    while (!condition_true) {
+        if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
+            printf("Time out reached!\n");
+            break;
+        }
+    }
+    // condition_true is true
+    nng_mtx_unlock(m);
+```
+
+### Example 3: Signaling the condition
+
+```c
+    nng_mtx_lock(m);
+    condition_true = true;
+    nng_cv_wake(cv);
+    nng_mtx_unlock(m);
+```
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_ENOMEM`: Insufficient free memory exists.
+- `NNG_ETIMEDOUT`: The time specified by _when_ is reached without the condition being signaled.
+
+## SEE ALSO
+
+[nng_clock][nng_clock],
+[nng_mtx][nng_mtx]
+
+[nng_clock]: ../util/nng_clock.md
+[nng_mtx]: ../thr/nng_mtx.md
diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md
index 37249e4f..02735423 100644
--- a/docs/ref/api/thr/nng_mtx.md
+++ b/docs/ref/api/thr/nng_mtx.md
@@ -1,4 +1,4 @@
-# nng_id_map
+# nng_mutex
 
 ## NAME