From d3cb41376ac0be31ed2b6649dd8d6b42674ebeaf Mon Sep 17 00:00:00 2001
From: EuAndreh <eu@euandre.org>
Date: Wed, 7 May 2025 07:02:57 -0300
Subject: Support UUIDv7, with -vN for choosing

---
 doc/uuid.en.1.adoc | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

(limited to 'doc/uuid.en.1.adoc')

diff --git a/doc/uuid.en.1.adoc b/doc/uuid.en.1.adoc
index 6366acb..dc6bc3e 100644
--- a/doc/uuid.en.1.adoc
+++ b/doc/uuid.en.1.adoc
@@ -4,12 +4,13 @@
 
 == NAME
 
-uuid - generate or validate a UUIDv4
+uuid - generate a UUID version 4 or 7, or validate a UUID string.
 
 
 
 == SYNOPSYS
 
+*uuid* [-v (4|7)]
 *uuid* [_STRING_]
 
 
@@ -17,16 +18,27 @@ uuid - generate or validate a UUIDv4
 == EXAMPLES
 
 
-=== Print a UUID on the terminal
+=== Print a (version 4) UUID on the terminal
 
+[source,sh]
 ....
 $ uuid
 d3891787-c952-af17-d697-0df3b85981e1
 ....
 
 
+=== Print a verson 7 UUID on the terminal
+
+[source,sh]
+....
+$ uuid -v 7
+d3891787-c952-af17-d697-0df3b85981e1
+....
+
+
 === Create a new UUID as part of a path
 
+[source,sh]
 ....
 dir="$PWD"/"$(uuid)"/data
 ....
@@ -34,6 +46,7 @@ dir="$PWD"/"$(uuid)"/data
 
 === Validate a given UUID
 
+[source,sh]
 ....
 ID="$(basename -- "$directory")"
 if ! uuid "$ID"; then
@@ -50,6 +63,17 @@ The *uuid* utility generates a new UUID when no _STRING_ is given and write it
 to _stdout_.  If a _STRING_ is given, *uuid* validates it and exits, and
 produces no output.
 
+The *-v* option allows for choosing which type of UUID to be emitted, either
+version 4 ("the random one") or version 7 ("the sortable one").  When omitted,
+version 4 is chosen as default.
+
+
+
+== OPTIONS
+
+*-v NUMBER*:: Choose the UUID version *NUMBER* to be generated.  Supported
+values are 4 (the default) and 7.
+
 
 
 == OPERANDS
@@ -75,12 +99,14 @@ Not used.
 The UUIDv4 format is made of byte blocks encoded as hexadecimals, using a
 <hyphen-minus>('`-`') as the block separator:
 
+[source,sh]
 ....
 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
 ....
 
 An example output is:
 
+[source,sh]
 ....
 cb46d0c0-b2aa-4a6c-a119-8deace2544a2
 ....
@@ -88,7 +114,15 @@ cb46d0c0-b2aa-4a6c-a119-8deace2544a2
 
 === STDERR
 
-Not used.
+Errors on UUID validation are sent to the standard error.  For instance:
+
+[source,sh]
+....
+$ uuid not-a-uuid-123 1>/dev/null
+uuid: str isn't of the correct length
+....
+
+When valid, validation emits nothing and exits with 0.
 
 
 === INPUT FILES
@@ -111,7 +145,7 @@ None.
 
 == CONFORMING TO
 
-The v4 UUID defined in *RFC 9562*.
+The versions 4 and 7 of the UUID defined in *RFC 9562*.
 
 
 
-- 
cgit v1.2.3

