docs: update some transport option docs

1 files changed, 21 insertions, 41 deletions

diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md
index 219f2abc..cba55a4b 100644
--- a/docs/ref/tran/socket.md
+++ b/docs/ref/tran/socket.md
@@ -4,32 +4,27 @@
 
 The {{i:*socket* transport}} supports communication between
 peers across arbitrary BSD sockets, such as those that are
-created with [`nng_socket_pair`][nng_socket_pair].
+created with [`nng_socket_pair`].
 
-This transport only supports [listeners][listener],
-using [`nng_listener_create`][nng_listener_create].
+This transport only supports [listeners][listener], using [`nng_listener_create`].
 
 > [!NOTE]
 > Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`.
 
 The socket file descriptor is passed to the listener using
 the {{i:`NNG_OPT_SOCKET_FD`}} option (as an integer).
-Setting this option will cause the listener to create a [pipe][pipe]
+Setting this option will cause the listener to create a [pipe]
 backed by the file descriptor.
 
 The protocol between peers using this transport is compatible with the protocol used
-for the [_tcp_][tcp] transport, but this is an implementation detail and subject to change without notice.
-{{footnote: Specifically it is not compatible with the [_ipc_][ipc] transport.}}
+for the _[tcp]_ transport, but this is an implementation detail and subject to change without notice.
+{{footnote: Specifically it is not compatible with the _[ipc]_ transport.}}
 
 > [!NOTE]
 > This transport is _experimental_, and at present is only supported on POSIX platforms.
 > {{footnote: Windows lacks a suitable `socketpair` equivalent function we could use.}}
 
-## Registration
-
-No special action is necessary to register this transport.
-
-## URI Format
+## URL Format
 
 This transport uses the URL {{i:`socket://`}}, without further qualification.
 
@@ -40,33 +35,18 @@ There are no further socket details available.
 
 ## Transport Options
 
-The following transport option is available:
-
-- {{i:`NNG_OPT_SOCKET_FD`}}: \
-  (int) \
-  \
-  This is a write-only option, that may be set multiple times on a listener.
-  Each time this is set, the listener will create a [pipe][pipe] backed by the given file
-  descriptor passed as an argument.
-
-Additionally, the following options may be supported on pipes when the platform supports them:
-
-- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID]
-- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID]
-- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID]
-- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID]
-
-[ipc]: [ipc.md]
-[tcp]: [tcp.md]
-[pipe]: [TODO.md]
-[listener]: [TODO.md]
-[dialer]: [TODO.md]
-[nng_sockaddr]: [TODO.md]
-[nng_listener_create]: [TODO.md]
-[nng_socket_pair]: ../../api/misc.md#create-socket-pair
-[NNG_OPT_LOCADDR]: [TODO.md]
-[NNG_OPT_REMADDR]: [TODO.md]
-[NNG_OPT_PEER_GID]: [TODO.md]
-[NNG_OPT_PEER_PID]: [TODO.md]
-[NNG_OPT_PEER_UID]: [TODO.md]
-[NNG_OPT_PEER_ZONEID]: [TODO.md]
+The following transport options are supported by this transport.
+
+| Option                | Type       | Description                                                                                                                                                                          |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `NNG_OPT_SOCKET_FD`   | `int`      | Write-only option, that may be set multiple times on a listener. Each time this is set, the listener will create a [pipe] backed by the given file descriptor passed as an argument. |
+| `NNG_OPT_PEER_GID`    | `uint64_t` | Read only option, returns the group ID of the process at the other end of the socket, if platform supports it.                                                                       |
+| `NNG_OPT_PEER_PID`    | `uint64_t` | Read only option, returns the processed ID of the process at the other end of the socket, if platform supports it.                                                                   |
+| `NNG_OPT_PEER_UID`    | `uint64_t` | Read only option, returns the user ID of the process at the other end of the socket, if platform supports it.                                                                        |
+| `NNG_OPT_PEER_ZONEID` | `uint64_t` | Read only option, returns the zone ID of the process at the other end of the socket, if platform supports it.                                                                        |
+
+> [!NOTE]
+> The `NNG_OPT_PEER_GID`, `NNG_OPT_PEER_PID`, `NNG_OPT_PEER_UID`, and `NNG_OPT_PEER_ZONEID` options depend on platform support.
+> These behave in exactly the same fashion as for the _[ipc]_ transport.
+
+{{#include ../xref.md}}