Merge branch 'dj-formatting'

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 <http://creativecommons.org/licenses/by-sa/4.0/>.
 .\"
-.TH DJ 1 2024-07-03 "Harakit X.X.X"
+.TH DJ 1 2024-07-14 "Harakit X.X.X"
 .SH NAME
 dj \(en disk jockey
 .\"
@@ -56,9 +56,9 @@ bytes read to this point are discarded.
 .IP \fB-o\fP
 Takes a file path as an argument and opens it for use as an output.
 .IP \fB-B\fP\ \fIblock_size\fP
-Does the same as
-.B -b
-but for the output buffer.
+Takes a numeric argument as the size in bytes of the output buffer, the default
+being 1024. Note that this option only affects the size of output writes and not
+the amount of output data itself. See the CAVEATS section.
 .IP \fB-S\fP
 Takes a numeric argument as the index of the byte at which writing will
 commence; \(lqseeks\(rq that number of bytes. If the standard output is used,
@@ -68,8 +68,8 @@ Accepts a single literal byte with which the input buffer is padded in the event
 of an incomplete read from the input file. If the option argument is empty, the
 null byte is used.
 .IP \fB-c\fP
-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.
+Specifies a number of blocks to read. The default is 0, in which case the input
+is read until a partial or empty read is made.
 .IP \fB-H\fP
 Prints diagnostic messages in a human-readable manner as described in the
 DIAGNOSTICS section.
@@ -181,15 +181,22 @@ option is specified, this could make written data nonsensical.
 
 Existing files are not truncated on ouput and are instead overwritten.
 
-The options
-.B -b
-and
+Option variants that have lowercase and uppercase forms could be confused for
+each other. The former affects input and the latter affects output.
+
+The
 .B -B
-could be confused for each other, and so could
-.B -s
-and
-.BR -S .
-The lowercase option affects input and the capitalized option affects output.
+option could be mistaken for the count in bytes of data written to the output.
+This conception is intuitive but incorrect, as the
+.B -c
+option controls the number of blocks to read and the
+.B -b
+option sets the size of the blocks. The
+.B -B
+option is similar to the latter but sets the size of blocks to be written,
+regardless of the amount of data that will actually be written. In practice,
+this means the input buffer should be very large to make use of modern hardware
+input and output speeds.
 
 The skipped or sought bytes while processing irregular files, such as streams,
 are reported in the diagnostic output, because they were actually read or
@@ -216,3 +223,4 @@ Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
 .SH SEE ALSO
 .BR dd (1p)
 .BR lseek (3p)
+.BR mm (1)