sd-id128: document everywhere that we treat all UUIDs as Variant 1

So in theory UUID Variant 2 (i.e. microsoft GUIDs) are supposed to be
displayed in native endian. That is of course a bad idea, and Linux
userspace generally didn't implement that, i.e. uuidd and similar.
Hence, let's not bother either, but let's document that we treat
everything the same as Variant 1, even if it declares something else.

1 files changed, 13 insertions, 12 deletions

diff --git a/man/sd-id128.xml b/man/sd-id128.xml
index 1890f6d6a5..716c62522d 100644
--- a/man/sd-id128.xml
+++ b/man/sd-id128.xml
@@ -50,13 +50,11 @@
   <refsect1>
     <title>Description</title>
 
-    <para><filename>sd-id128.h</filename> provides APIs to process and
-    generate 128-bit ID values. The 128-bit ID values processed and
-    generated by these APIs are a generalization of OSF UUIDs as
-    defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
-    4122</ulink> but use a simpler string format. These functions
-    impose no structure on the used IDs, much unlike OSF UUIDs or
-    Microsoft GUIDs, but are fully compatible with those types of IDs.
+    <para><filename>sd-id128.h</filename> provides APIs to process and generate 128-bit ID values. The
+    128-bit ID values processed and generated by these APIs are a generalization of OSF UUIDs as defined by
+    <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> but use a simpler string format. These
+    functions impose no structure on the used IDs, much unlike OSF UUIDs or Microsoft GUIDs, but are mostly
+    compatible with those types of IDs.
     </para>
 
     <para>See
@@ -101,8 +99,7 @@
 
 int main(int argc, char **argv) {
   puts("Match for coredumps: MESSAGE_ID=" SD_MESSAGE_COREDUMP_STR);
-}
-    </programlisting>
+}</programlisting>
 
     <para><function>SD_ID128_CONST_STR()</function> may be used to
     convert constant 128-bit IDs into constant strings for output. The
@@ -125,9 +122,13 @@ int main(int argc, char **argv) {
 }</programlisting>
 
     <para><constant>SD_ID128_UUID_FORMAT_STR</constant> is similar to
-    <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the
-    "<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
-    </para>
+    <constant>SD_ID128_FORMAT_STR</constant> but includes separating hyphens to conform to the "<ulink
+    url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical
+    representation</ulink>". This formats the string based on <ulink
+    url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
+    Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably
+    best to avoid UUIDs of other variants, in order to avoid unnecessary ambiguities. All 128-bit IDs
+    generated by the sd-id128 APIs strictly conform to Variant 1 Version 4 UUIDs, as per RFC 4122.</para>
 
     <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para>