peek.1: Rewrite man page to fit better with bonsai/coreutils.

peek/peek.1

@@ -12,68 +12,96 @@ peek
 .RB [ program
 .RB [ arguments... ]])
 
-.SH USAGE
+.SH DESCRIPTION
 
 Peek reads input from standard input with terminal echo disabled, which may be
 useful to prevent secrets being spied upon by adversaries watching a user's
 screen.
-.PP
+
-The
+.SH OPTIONS
+
 .B -1
-option limits input to a single line (stopping when the newline character is
+.RS
-input).
+Limits input to a single line (stopping when the newline character is read).
-.PP
+.RE
-The
+
+.B -e
+.RS
+Configures peek to output to standard error.
+.RE
+
 .B -n
-option prints ("iNcludes") the terminating character in output; this is only
+.RS
-useful when combined with the
+Prints ("iNcludes") the terminating character in outputs. This is nonsensical
+if not combined with the
 .B -1
 option.
-.PP
+.RE
-The
+
 .B -o
-and
+.RS
-.B -e
+Configures peek to output to standard output.
-options configure Peek to output to standard output and/or standard error
+.RE
-respectively and the
+
 .B -p
-option configures Peek to output to the standard input of an external program,
+.RS
-e.g. a password hashing utility.
+Configures peek to pipe output to an executed child program, e.g. a password
-The
+hashing utility. This is provided as a convenience and to avoid potential
-.B -p
+insecurities resulting from programmer error in scripts.
-option is provided as a convenience and to avoid potential insecure programmer
+.RE
-error in scripts.
+
-.PP
-The
 .B -t
-option makes peek exit if not run in a terminal.
+.RS
+Makes peek exit if not run within a terminal.
+.RE
 
 .SH DIAGNOSTICS
 
 Peek prints an error message and exits with the appropriate status from
-sysexits(3) if it encounters an error.
+sysexits.h(3) if it encounters an unrecoverable error.
+
+Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is
+still usable after premature termination; if the signal can't be handled, it
+prints an error message and continues. If peek is interrupted, it exits
+unsuccessfully, without an error message.
 
 .SH BUGS
 
 Accepting secrets in shell scripts is not adviseable in any context.
-.PP
+
-The user's environment passed through to the program used with the
-.B -p
-option and their PATH environment variable is used to locate the program.
 If used in a safety-critical application it must be ensured that the
-environment with which peek is used is not compromised. For example, using
+environment with which peek is used is not compromised.
-POSIX env(1) to set a known, safe PATH, and htpasswd(1) from Apache's utilities
+
-package to hash the input with bcrypt:
-.PP
-.R env -i PATH=/usr/bin peek -1p htpasswd -nBi '' | cut -d : -f 2
-.PP
 On systems that support it, the ioctl(2) command TIOCSTI can be used to insert
 characters into the standard input going to peek. This doesn't allow snooping
 but can be used for general mischief.
 
+.SH EXAMPLES
+
+This is a command line for POSIX sh(1), using POSIX env(1) to discard the
+environment except for PATH, and htpassword(1) from Apache's utilities to hash
+the input with the bcrypt algorithm, printing the resulting hash:
+
+.RS
+.R $ env -i PATH="$PATH" peek -1tp htpasswd -nBi _ | cut -d : -f 2
+.RE
+
+This is a POSIX sh(1) command line that lets a user blindly write into a text
+file, only able to see written lines. Some writers have the habit of
+prematurely revising their work and use tools like this to prevent it:
+
+.RS
+.R $ echo Input ^D to quit. && peek -eot >writing.txt
+.RE
+
+.SH AUTHOR
+
+Written by DTB <trinity@trinity.moe>.
+
 .SH COPYRIGHT
 
-Public domain.
+Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/gpl.html>.
 
 .SH SEE ALSO