diff --git a/docs/dj.1 b/docs/dj.1 index dd293f2..09f40c9 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-29 "Harakit X.X.X" +.TH DJ 1 2024-07-03 "Harakit X.X.X" .SH NAME dj \(en disk jockey .\" @@ -34,10 +34,17 @@ respectively. This language is inherited from the .BR dd (1p) 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. Seeks and skips aren\(cqt counted -in the output statistics because they're guaranteed to succeed (or the utility -will exit unsuccessfully). +The offset used when skipping or seeking refers to how many bytes are skipped +or sought. Running +.BR dj (1) +with a skip offset of 1 skips one byte into the input and reads from the second +byte onwards. A programmer may think of a file as a zero-indexed array of +bytes; in this analogy, the offset given is the index of the byte at which to +start reading or writing. + +Seeks and skips aren\(cqt counted in the output statistics because they're +guaranteed to succeed (or the utility will exit unsuccessfully, before it has +written any data). .\" .SH OPTIONS @@ -82,6 +89,54 @@ input file is \(lq-\(rq. The standard output shall be used as an output if no inputs are specified or if the output file is \(lq-\(rq. .\" +.SH EXAMPLES + +The following +.BR sh (1p) +line: + +.RS +printf 'Hello, world!\(rsn' | dj -c 1 -b 7 -s 7 2>/dev/null +.RE + +Produces the following output: + +.RS +world! +.RE + +The following +.BR sh (1p) +lines run sequentially: + +.RS +tr '\(rs0' 0