From 29c576de63a3de6da6a2f4909f151b3d5d157060 Mon Sep 17 00:00:00 2001
From: Rutger Broekhoff
Date: Tue, 30 Apr 2024 02:20:00 +0200
Subject: Improve man pages

Added an explanation on the type of key that is expected. Also tried to
fix layout of the path structure explanation in gitolfs3-server(1), so
that it also looks okay when rendered as a PDF. (On the PDF generated
using mandoc it still looks a bit weird, but I don't think I'll try to
solve that right now.)
---
 docs/man/gitolfs3-authenticate.1 | 10 ++++++++++
 docs/man/gitolfs3-server.1       | 32 +++++++++++++++++++++-----------
 2 files changed, 31 insertions(+), 11 deletions(-)

(limited to 'docs/man')

diff --git a/docs/man/gitolfs3-authenticate.1 b/docs/man/gitolfs3-authenticate.1
index 3a9951e..3f44312 100644
--- a/docs/man/gitolfs3-authenticate.1
+++ b/docs/man/gitolfs3-authenticate.1
@@ -31,3 +31,13 @@ Must end with a slash.
 .B Required.
 The path to the key which is used to authorize the request to the Gitolfs3
 server.
+The key must be 128-character hexadecimal string, i.e., a 64-byte number.
+Such a key can, for example, be generated using OpenSSL, with the following
+command:
+
+	openssl rand -hex 64
+
+Note that the Gitolfs3 server must be configured to use exactly the same key
+for
+.B gitolfs3-authenticate
+to function.
diff --git a/docs/man/gitolfs3-server.1 b/docs/man/gitolfs3-server.1
index f141bce..30f8cb5 100644
--- a/docs/man/gitolfs3-server.1
+++ b/docs/man/gitolfs3-server.1
@@ -15,18 +15,22 @@ Otherwise, repositories will not be recognized (and nothing will work).
 
 The Gitolfs3 server uses S3-compatible services as backing storage.
 In the configured S3 bucket, a familiar structure is used:
-.in +2
-lfs-test.git/ ................. repository name
-.in +2
-lfs/objects/ ................ namespace
-.in +2
-4e/ ....................... first byte of the object ID (OID)
-.in +2
-7b/ ..................... second byte of the OID
-.in +2
-4e7bfdb[...]11ce013 ... OID (SHA256)
-.in -10
+.IP
+.TS
+tab(%);
+l l
+l l
+l l
+l l
+l l.
+lfs-test.git/ % repository name
+  lfs/objects/ % namespace
+    4e/ % first byte of the object ID (OID)
+      7b/ % second byte of the OID
+        4e7bfdb[...]11ce013 % OID (SHA256)
+.TE
 
+.P
 Public and private repositories are distinguished using the presence of a
 \fIgit-daemon-export-ok\fR file in the bare repository.
 Unauthenticated users accessing the service over the public internet are
@@ -80,6 +84,12 @@ itself.
 .B GITOLFS3_KEY_PATH
 .B Required.
 Path to the key that is used to generate and verify tags (MACs) for requests.
+The key must be 128-character hexadecimal string, i.e., a 64-byte number.
+Such a key can, for example, be generated using OpenSSL, with the following
+command:
+
+	openssl rand -hex 64
+
 Must correspond with the key used by
 .BR gitolfs3-authenticate (1),
 if using.
-- 
cgit v1.2.3