peek.1: updates to be more consistent with current documentation

docs/peek.1

@@ -1,90 +1,110 @@
 .\" Copyright (c) 2023-2024 DTB <trinity@trinity.moe>
+.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
 .\"
 .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
 .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
-
+.\"
-.TH PEEK 1
+.TH PEEK 1 2024-06-09 "Bonsai Core Utilites 0.13.9"
-
 .SH NAME
-
 peek \(en read from the standard input, furtively
-
+.\"
 .SH SYNOPSIS
 
 peek
 .RB ( -i )
-
+.\"
 .SH DESCRIPTION
 
-Peek reads input from the standard input with terminal echo disabled.
+Read input from the standard input with terminal echo disabled.
-
+.\"
 .SH OPTIONS
 
-.B -i
+.IP \fB-i\fP
-.RS
+Allows input to come from sources other than terminals (i.e., a pipe).
-Allows input to come from sources other than terminals (i.e. a pipe).
+.\"
-.RE
-
 .SH DIAGNOSTICS
 
-Peek prints an error message and exits with the appropriate status from
+In the event of an error, a debug message will be printed and the program will
-sysexits.h(3) if it encounters an unrecoverable error.
+exit with the appropriate
-
+.BR sysexits.h (3)
-Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is
+error code.
-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.
 
+In order to ensure the user\(cqs terminal is still usable after premature
+termination, the program attempts to handle the SIGINT signal; if it cannot,
+an error message is printed and execution continues. If the program is
+interrupted, it exits unsuccessfully without an error message.
+.\"
 .SH RATIONALE
 
-This tool was originally written to accept passwords in shell scripts, as an
+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).
+extremely simple alternative to the GNU Privacy Guard project\(cqs
+.BR pinentry (1)
+utility.
+
 Accepting input without showing what is being typed is useful when keying in
-secrets in public settings or places with installed surveillance cameras.
+secrets in public settings or in places where surveillance cameras are
+installed.
+.\"
+.SH CAVEATS
 
-.SH BUGS
+This program does nothing to prevent others from seeing the key presses input to
+a keyboard. It also does not protect against the sound of typing being analyzed
+to determine what was inputted without needing to see screen or keyboard.
 
-This does nothing to prevent others seeing the keyboard being used to input
+Accepting secrets in shell scripts is probably not advisable.
-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.
-
-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.
 
+On systems that support it, the
+.BR ioctl (2)
+command TIOCSTI can be used to insert characters into the standard input. This
+doesn't allow snooping but can be used for general mischief.
+.\"
 .SH EXAMPLES
 
-This is an sh(1p) command line that hashes a given password. It uses head(1p)
+This is an
-to only accept one line of input, xargs(1p) and printf(1p) to strip the
+.BR sh (1p)
-trailing newline, htpasswd(1) from Apache's utilities to hash the input with
+command line that hashes a given password. It uses
-the bcrypt algorithm, and cut(1p) to print only the resulting hash:
+.BR head (1p)
+to only accept one line of input,
+.BR xargs (1p)
+and
+.BR printf (1p)
+to strip the trailing newline,
+.BR htpasswd (1) 
+from Apache\(cqs utilities to hash the input with the bcrypt algorithm, and
+.BR cut (1p)
+to print only the resulting hash:
 
 .RS
-.R $ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
+$ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
 .RE
 
-This is an sh(1p) command line that lets a user blindly write into a text file,
+This is an
-only able to see written lines. Some writers have the habit of prematurely
+.BR sh (1p)
-revising their work and use tools like this to prevent it. It uses mm(1) to
+command line that allows a user to write blindly into a text file but displaying
-pipe the output of peek to both the standard error and the regular file
+only written lines. Some writers have the habit of prematurely revising their 
-writing.txt.
+work and use tools with functionality similar to this to prevent it. 
+It uses
+.BR mm (1)
+to pipe the output of the program to both the standard error and the regular
+file writing.txt:
 
 .RS
-.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt
+$ echo Input ^D to quit. && peek | mm -eo - >writing.txt
 .RE
-
+.\"
 .SH AUTHOR
 
-Written by DTB <trinity@trinity.moe>.
+Written by DTB
-
+.MT trinity@trinity.moe
+.ME .
+.\"
 .SH COPYRIGHT
 
-Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
+Copyright \(co 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
 <https://gnu.org/licenses/gpl.html>.
-
+.\"
 .SH SEE ALSO
-
+.BR ioctl (2),
-ioctl(2), ioctl_tty(2), read(1), sh(1)
+.BR ioctl_tty (2),
+.BR read (1),
+.BR sh (1)