overgrown/docs/npc.1

.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023–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 NPC 1 2024-06-17 "Harakit 0.13.11"
.SH NAME
npc \(en show non-printing characters
.\"
.SH SYNOPSIS

npc
.RB ( -et )
.\"
.SH DESCRIPTION

Print normally non-printing characters.

The program reads from standard input and writes to standard output, replacing
non-printing characters with printable equivalents. Control characters print as
a carat ('^') followed by the character '@' through '_' corresponding to the
character replaced (e.g. control-X becomes '^X'). The delete character (0x7F)
becomes '^?'. Characters with the high bit set (>127) are printed as 'M-'
followed by the graphical representation for the same character without the
high bit set.
.\"
.SH OPTIONS

.IP \fB-e\fP
Prints a dollar sign ('$') before each newline.
.IP \fB-t\fP
Prints tab characters as '^I' rather than a literal horizontal tab.
.\"
.SH DIAGNOSTICS

In the event of an error, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH BUGS

The program operates in single-byte chunks regardless of intended encoding.
.\"
.SH RATIONALE

POSIX currently lacks a way to display non-printing characters in the terminal
using a standard tool. A popular extension to
.BR cat (1p),
the
.B -v
option, is the bandage solution GNU and other software suites use.

This functionality is included in a separate tool because its usefulness extends
beyond that of
.BR cat (1p).
.\"
.SH AUTHOR

Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT

Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR cat (1p),
.BR cat-v (1),
.I UNIX Style, or cat -v Considered Harmful
by Rob Pike