diff --git a/docs/stris.1 b/docs/stris.1 index bd4288e..a80d18f 100644 --- a/docs/stris.1 +++ b/docs/stris.1 @@ -1,118 +1,104 @@ .\" Copyright (c) 2023–2024 DTB -.\" Copyright (c) 2023 Emma Tebibyte +.\" Copyright (c) 2023–2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.TH STRIS 1 - +.\" +.TH STRIS 1 2024-10-22 "Harakit X.X.X" .SH NAME - stris \(en test the character types of string arguments - +.\" .SH SYNOPSIS stris -.RB ( -7bcdlu ) -.RB ( -i [ inclusions ]) -.RB [ strings... ] - +.RB [ -7bcdlu ] +.RB [ -i\ inclusions ] +.RB strings... +.\" .SH DESCRIPTION -Stris tests each rune in an arbitrary quantity of string arguments, ensuring -each meets any of the parameters specified in the program options. - +Test each character in any number of string arguments, ensuring each meets any +of the parameters specified by program options. +.\" .SH OPTIONS -.B -7 -.RS -Tests to see if runes are fit within seven bits; that is, that they are encoded -with ASCII. -.RE - -.B -b -.RS -Tests to see if runes are blank or "whitespace"; characters that do not print -but fill a predictable amount of space. -.RE - -.B -c -.RS -Tests to see if runes are control characters; characters that are not printing -or graphical. -.RE - -.B -d -.RS -Tests to see if runes are numeric. This test does not only allow the ASCII -digits but any numeric symbol. -.RE - -.B -i -.RS -Permits, in addition to the given specified parameters, all of the runes -supplied in its option argument. -.RE - -.B -l -.RS -Tests to see if runes are in their lower case. -.RE - -.B -u -.RS -Tests to see if runes are in their upper case, or capitalized. -.RE - +.IP \fB-7\fP +Tests if the character encoding is ASCII. +.IP \fB-b\fP +Tests if characters are whitespace. +.IP \fB-c\fP +Tests if characters are control characters. +.IP \fB-d\fP +Tests if characters are numeric. +.IP \fB-i\fP \fIinclusions...\fP +In addition to specified options, also permits characters in +.IR inclusions . +.IP \fB-l\fP +Tests if characters are in lower case. +.IP \fB-u\fP +Tests if characters are in upper case. +.\" .SH DIAGNOSTICS -Stris exits successfully if all runes in all given strings meet any of the -specified parameters, or if no parameters were specified but all given strings -were legibly encoded. It exits unsuccessfully if the previous is untrue, and if -invalid options were given, or if no strings were given, a usage synopsis will -be printed to the standard error. +If no test cases pass for a character in +.IR strings , +the program will exit unsuccessfully. -.SH BUGS +.SH CAVEATS -There's no way of knowing which argument failed the test without re-testing -arguments individually. +If no options are specified, the program will exit successfully as long as the +input +.I strings +are legibly encoded. -Some runes that can losslessly be encoded into ASCII from UTF-8 but in an -"overlong encoding", where the rune was encoded with unnecessary leading -zeroes causing it to span multiple bytes, won't be detected as ASCII. +Neither which test failed nor which of the +.I strings +failed a test cannot be known without further invocations of the program. +Characters that can be encoded losslessly into ASCII from UTF-8 but which +are in an \(lqoverlong encoding\(rq, where the character was encoded with +unnecessary leading zeroes causing it to span multiple bytes, won\(cqt be +detected as ASCII. +.\" .SH EXAMPLES -This is an sh(1p) snippet that checks to see if an environment variable is an -ASCII digit. +This is an +.BR sh (1p) +snippet which tests if an environment variable is an ASCII digit. .RS -.R stris -7 "$v" && stris -d "$v" && echo ASCII digit. +stris -7 "$v" && stris -d "$v" && echo ASCII digit. .RE -This is an sh(1p) snippet that checks to see if an environment variable is a -hexadecimal number. +This is an +.BR sh (1p) +snippet that tests if an environment variable is a hexadecimal number. .RS -.R stris -7 "$v" && stris -di ABCDEFabcdef "$v" && echo Hexadecimal number. +stris -7 "$v" && stris -di ABCDEFabcdef "$v" && echo Hexadecimal number. .RE - +.\" .SH AUTHOR -Written by DTB . - +Written by DTB +.MT trinity@trinity.moe +.ME . +.\" .SH HISTORY -Stris replaces the former str(1) which took the name of a function from -ctype(3) as its first argument and checked the following strings against it; -str(1) exited unsuccessfully when it encountered any non-ASCII runes and could +This program replaces the former str(1) which took the name of a function from +.BR ctype (3p) +as its first argument and checked the following strings against it; +.BR str (1) +exited unsuccessfully when it encountered any non-ASCII characters and could only have one parameter specified. - +.\" .SH COPYRIGHT -Copyright © 2023–2024 DTB. License AGPLv3+: GNU AGPL version 3 or later +Copyright \(co 2023\(en2024 DTB. License AGPLv3+: GNU AGPL version 3 or later . - +.\" .SH SEE ALSO - -ascii(7), ctype(3p), strcmp(1) +.BR ascii (7), +.BR ctype (3p), +.BR strcmp (1)