From e6eff86ef39d2ec46e08ff6c2f664971bb190dc4 Mon Sep 17 00:00:00 2001
From: Bob Polis <bob.polis@gmail.com>
Date: Tue, 15 Jul 2025 16:30:33 +0200
Subject: [PATCH] Add relevant help text

---
 man/man1/ranlin.1 | 29 ++++++++++++-----------------
 1 file changed, 12 insertions(+), 17 deletions(-)

diff --git a/man/man1/ranlin.1 b/man/man1/ranlin.1
index c750237..c12bca2 100644
--- a/man/man1/ranlin.1
+++ b/man/man1/ranlin.1
@@ -1,12 +1,9 @@
-.Dd $Mdocdate$
+.Dd July 15, 2025
 .Dt ranlin 1
 .Os
 .Sh NAME
 .Nm ranlin
-.Nd one line about what it does
-.\" .Sh LIBRARY
-.\" For sections 2, 3, and 9	only.
-.\" Not used in OpenBSD.
+.Nd select one line randomly from a text file
 .Sh SYNOPSIS
 .Nm
 .Fl h
@@ -17,7 +14,8 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility processes files ...
+utility randomly chooses a single line from a text file, where the chance a
+specific line is chosen is equal for all lines.
 When no file arguments are given,
 .Nm
 will read from the standard input.
@@ -29,30 +27,27 @@ Print help text and exit.
 .It Fl \-version
 Print version info and exit.
 .El
-.\" .Sh CONTEXT
-.\" For section 9 functions only.
-.\" .Sh IMPLEMENTATION NOTES
-.\" Not used in OpenBSD.
-.\" .Sh RETURN VALUES
-.\" For sections 2, 3, and 9 function return values only.
 .\" .Sh ENVIRONMENT
 .\" For sections 1, 6, 7, and 8 only.
 .\" .Sh FILES
 .Sh EXIT STATUS
-.\" For sections 1, 6, and 8 only.
 .Nm
 exits 0 on success, and 1 if an error occurs.
 .\" .Sh EXAMPLES
 .\" .Sh DIAGNOSTICS
 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
-.\" .Sh ERRORS
-.\" For sections 2, 3, 4, and 9 errno settings only.
 .\" .Sh SEE ALSO
 .\" .Xr foobar 1
 .\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Sh HISTORY
+The algorithm used by
+.Nm
+is very clever, and will never have more than two lines in memory, at all times.
+It has been taken from
+.Dq The Perl Cookbook ,
+and implemented in C++ for this tool.
 .Sh AUTHORS
-Bob Polis
+.An Bob Polis
 .\" .Sh CAVEATS
 .\" .Sh BUGS
 .\" .Sh SECURITY CONSIDERATIONS