From 6814111ad1a6d14ac5b514212f5a9e1a9a7c6947 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 23:36:52 -0600 Subject: [PATCH] dj.1: fixes many clunky sentences --- docs/dj.1 | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/dj.1 b/docs/dj.1 index 1572991..6073fc6 100644 --- a/docs/dj.1 +++ b/docs/dj.1 @@ -4,7 +4,7 @@ .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .\" -.TH DJ 1 2024-06-06 "Bonsai Core Utilites 0.13.8" +.TH DJ 1 2024-06-17 "Bonsai Core Utilites 0.13.8" .SH NAME dj \(en disk jockey .\" @@ -34,13 +34,13 @@ dj .SH DESCRIPTION Perform precise read and write operations on files. This utility is useful for -reading and writing binary data to and from disks, hence the name. +reading and writing binary data to and from disks. This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving to a specified byte by index in the input and output of the program respectively. This language is inherited from the .BR dd (1p) -utility and is used here to decrease ambiguity. +utility and used here to decrease ambiguity. When seeking or skipping to a byte, writing or reading starts at the byte immediately subsequent to the specified byte. @@ -50,8 +50,8 @@ immediately subsequent to the specified byte. .IP \fB-i\fP Takes a file path as an argument and opens it for use as an input. .IP \fB-b\fP -Takes a numeric argument as the size in bytes of the input buffer, with the -default being 1024. +Takes a numeric argument as the size in bytes of the input buffer, the default +being 1024. .IP \fB-s\fP Takes a numeric argument as the number of bytes to skip into the input before starting to read. If the standard input is used, bytes read to this point @@ -66,25 +66,25 @@ but for the output buffer. Seeks a number of bytes through the output before starting to write from the input. If the output is a stream, null characters are printed. .IP \fB-a\fP -Accepts a single literal byte with which input buffer is padded in the event +Accepts a single literal byte with which the input buffer is padded in the event of an incomplete read from the input file. .IP \fB-A\fP Specifying this option pads the input buffer with null bytes in the event of an -incomplete read. Equivalent to specifying +incomplete read. This is equivalent to specifying .B -a with a null byte instead of a character. .IP \fB-c\fP -Specifies a number of reads to make. The default is zero, in which case the +Specifies a number of reads to make. The default is 0, in which case the input is read until a partial or empty read is made. .IP \fB-d\fP Prints invocation information before program execution as described in the -DIAGNOSTICS section below. Each invocation increments the debug level of the +DIAGNOSTICS section. Each invocation increments the debug level of the program. .IP \fB-H\fP Prints diagnostics messages in a human-readable manner as described in the -DIAGNOSTICS section below. +DIAGNOSTICS section. .IP \fB-n\fP -Retries failed reads once more before exiting. +Retries failed reads once before exiting. .IP \fB-q\fP Suppresses error messages which print when a read or write is partial or empty. Each invocation decrements the debug level of the program. @@ -94,13 +94,18 @@ empty. Each invocation decrements the debug level of the program. The standard input shall be used as an input if no inputs are specified or if one or more of the input files is \(lq-\(rq. .\" +.SH STANDARD OUTPUT +The standard output shall be used as an output if no inputs are specified or if +one or more of the input files is \(lq-\(rq. +.\" .SH DIAGNOSTICS -On a partial or empty read, a diagnostic message is printed (unless the +On a partial or empty read, unless the .B -q -option is specified) and the program exits (unless the +option is specified, a diagnostic message is printed. Then, the program exits +unless the .B -n -option is specified). +option is specified. By default, statistics are printed for input and output to the standard error in the following format: @@ -125,9 +130,9 @@ option may be specified. In this event, the following format is used instead: If the .B -d -option is specified, debug output will be printed at the beginning of -execution. This debug information contains information regarding how the program -was invoked. The following example is the result of running the program with +option is specified, debug information will be printed at the beginning of +execution. This output contains information regarding how the program was +invoked. The following example is the result of running the program with .B -d as the only argument: @@ -148,12 +153,12 @@ If .B -n is specified along with the .B -c -option and a count, actual byte output may be lower than expected (the product -of the count and the input block size). If the +option and a count, actual byte output is the product of the count and the input +block size and therefore may be lower than expected. If the .B -a or .B -A -options are used, this could make data written nonsensical. +options are specified, this could make written data nonsensical. .\" .SH CAVEATS