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

---
 man/man1/valid-utf8.1 | 36 +++++++++++++++++++-----------------
 1 file changed, 19 insertions(+), 17 deletions(-)

diff --git a/man/man1/valid-utf8.1 b/man/man1/valid-utf8.1
index cb201bd..55a614c 100644
--- a/man/man1/valid-utf8.1
+++ b/man/man1/valid-utf8.1
@@ -1,12 +1,9 @@
-.Dd $Mdocdate$
+.Dd July 15, 2025
 .Dt valid-utf8 1
 .Os
 .Sh NAME
 .Nm valid-utf8
-.Nd one line about what it does
-.\" .Sh LIBRARY
-.\" For sections 2, 3, and 9	only.
-.\" Not used in OpenBSD.
+.Nd check whether text is utf-8 encoded or not
 .Sh SYNOPSIS
 .Nm
 .Fl h
@@ -17,11 +14,24 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility processes files ...
+utility reads the files given as arguments, and sets its exit status to 0 when
+the text has been detected to be valid UTF-8, or to 1 otherwise.
 When no file arguments are given,
 .Nm
 will read from the standard input.
 .Pp
+.Nm
+will not write anything to the standard output, and will only write error
+messages, if any, to the standard error output.
+.Pp
+This behaviour makes
+.Nm
+useful as a
+.Ar -exec
+criterion for the
+.Xr find 1
+tool.
+.Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl h, \-help
@@ -29,31 +39,23 @@ 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.
+exits 0 when the text is encoded in valid UTF-8, and 1 otherwise, or 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 AUTHORS
-Bob Polis
+.An Bob Polis
 .\" .Sh CAVEATS
 .\" .Sh BUGS
 .\" .Sh SECURITY CONSIDERATIONS
-.\" Not used in OpenBSD.