peek(1): strip down to bare essentials, rewrite man page to match

docs/peek.1

@@ -12,52 +12,17 @@ peek \(en read from standard input, furtively
 .SH SYNOPSIS
 
 peek
-.RB ( -1enot )
-.RB ( -p
-.RB [ program
-.RB [ arguments... ]])
+.RB ( -i )
 
 .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.
+Peek reads input from standard input with terminal echo disabled.
 
 .SH OPTIONS
 
-.B -1
+.B -i
 .RS
-Limits input to a single line (stopping when the newline character is read).
-.RE
-
-.B -e
-.RS
-Configures peek to output to standard error.
-.RE
-
-.B -n
-.RS
-Prints ("iNcludes") the terminating character in outputs. This is nonsensical
-if not combined with the
-.B -1
-option.
-.RE
-
-.B -o
-.RS
-Configures peek to output to standard output.
-.RE
-
-.B -p
-.RS
-Configures peek to pipe output to an executed child program, e.g. a password
-hashing utility. This is provided as a convenience and to avoid potential
-insecurities resulting from programmer error in scripts.
-.RE
-
-.B -t
-.RS
-Makes peek exit if not run within a terminal.
+Allows input to come from sources other than terminals (i.e. a pipe).
 .RE
 
 .SH DIAGNOSTICS
@@ -70,36 +35,45 @@ 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 RATIONALE
+
+This tool was originally written to accept passwords in shell scripts, as an
+extremely simple alternative to the GNU Privacy Guard project's pinentry(1).
+Accepting input without showing what is being typed is useful when keying in
+secrets in public settings or places with installed surveillance cameras.
+
 .SH BUGS
 
-Accepting secrets in shell scripts is not adviseable in any context.
+This does nothing to prevent others seeing the keyboard being used to input
+secrets or mask the sound of typing. Audio or video recordings of typing can be
+used to determine what was input without needing to see the characters appear
+on the screen.
 
-If used in a safety-critical application it must be ensured that the
-environment with which peek is used is not compromised.
+Accepting secrets in shell scripts is probably not adviseable.
 
 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.
 
-Peek will happily run without outputs, slurping input and doing nothing with
-it.
-
 .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:
+This is an sh(1p) command line that hashes a given password. It uses head(1p)
+to only accept one line of input, xargs(1p) and printf(1p) to strip the
+trailing newline, htpasswd(1) from Apache's utilities to hash the input with
+the bcrypt algorithm, and cut(1p) to print only the resulting hash:
 
 .RS
-.R $ env -i PATH="$PATH" peek -1tp htpasswd -nBi _ | cut -d : -f 2
+.R $ peek | head -n 1 | xargs printf '%s' | 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:
+This is an sh(1p) 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. It uses mm(1) to
+pipe the output of peek to both the standard error and the regular file
+writing.txt.
 
 .RS
-.R $ echo Input ^D to quit. && peek -eot >writing.txt
+.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt
 .RE
 
 .SH AUTHOR
@@ -113,4 +87,4 @@ Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 
 .SH SEE ALSO
 
-env(1), ioctl(2), ioctl_tty(2), read(1), sh(1)
+ioctl(2), ioctl_tty(2), read(1), sh(1)