Re: dd(1) wording and style

2020-02-15 Thread Ingo Schwarze
Hi Jan,

Jan Stary wrote on Sat, Feb 15, 2020 at 10:51:28AM +0100:
> On Feb 14 17:37:27, schwa...@usta.de wrote:
>> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +:
>>> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

 -.It Cm seek= Ns Ar n
 +.It Cm seek Ns = Ns Ar n
  Seek
  .Ar n
  blocks from the beginning of the output before copying.
 -On non-tape devices, an
 -.Xr lseek 2
 -operation is used.
 -Otherwise, existing blocks are read and the data discarded.
 -If the user does not have read permission for the tape, it is positioned
 -using the tape
 +On a tape device, existing blocks are read and the data discarded;
 +if the user does not have read permission for the tape,
 +it is positioned using the tape
  .Xr ioctl 2
  function calls.
 +On all other devices devices, an
 +.Xr lseek 2
 +operation is used.
  If the seek operation is past the end of file, space from the current
  end of file to the specified offset is filled with blocks of NUL bytes.

>>> i think this change is ok. however i think non-tape is clearer than "on
>>> all other devices". it's not a biggie, but i think the current stress on
>>> non-tape devices is probably intentional.

>> The patch is misleading.  The sentence "If the seek operation is
>> past the end of file..." only applies to tape devices, so it must
>> not follow a sentence about lseek(2).

> Why does it only apply to tape devices?
> dd if=/dev/zero of=file bs=1 seek=10 count=1
> will seek 10 bytes into the output (filling it with zeros)
> and then write the 1 byte from input, as intended.
> -rw-r--r--  1 hans  wheel  11 Feb 15 10:50 file

You are right, lseek(2) also behaves that way, as documented:

  The lseek() function allows the file offset to be set beyond the end of
  the existing end-of-file of the file.  If data is later written at this
  point, subsequent reads of the data in the gap return bytes of zeros
  (until data is actually written into the gap).

However, the reordering is still unfortunate because it would no longer
be clear that filling the gap also applies to tape devices.  That's
what the dd(1) manual needs to explain because that's what dd(1)
actually implements.  Documenting lseek(2) in the dd(1) manual page,
on the other hand, isn't really needed.

I'm not convinced that the current text for seek= needs further
changes.

Yours,
  Ingo



Re: dd(1) wording and style

2020-02-15 Thread Jan Stary
Hi,

On Feb 14 17:37:27, schwa...@usta.de wrote:
> Hi,
> 
> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +:
> > On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
> 
> >> -.It Cm seek= Ns Ar n
> >> +.It Cm seek Ns = Ns Ar n
> >>  Seek
> >>  .Ar n
> >>  blocks from the beginning of the output before copying.
> >> -On non-tape devices, an
> >> -.Xr lseek 2
> >> -operation is used.
> >> -Otherwise, existing blocks are read and the data discarded.
> >> -If the user does not have read permission for the tape, it is positioned
> >> -using the tape
> >> +On a tape device, existing blocks are read and the data discarded;
> >> +if the user does not have read permission for the tape,
> >> +it is positioned using the tape
> >>  .Xr ioctl 2
> >>  function calls.
> >> +On all other devices devices, an
> >> +.Xr lseek 2
> >> +operation is used.
> >>  If the seek operation is past the end of file, space from the current
> >>  end of file to the specified offset is filled with blocks of NUL bytes.
> 
> > i think this change is ok. however i think non-tape is clearer than "on
> > all other devices". it's not a biggie, but i think the current stress on
> > non-tape devices is probably intentional.
> 
> The patch is misleading.  The sentence "If the seek operation is
> past the end of file..." only applies to tape devices, so it must
> not follow a sentence about lseek(2).

Why does it only apply to tape devices?
dd if=/dev/zero of=file bs=1 seek=10 count=1
will seek 10 bytes into the output (filling it with zeros)
and then write the 1 byte from input, as intended.
-rw-r--r--  1 hans  wheel  11 Feb 15 10:50 file

Jan



Re: dd(1) wording and style

2020-02-14 Thread Jason McIntyre
On Fri, Feb 14, 2020 at 05:37:27PM +0100, Ingo Schwarze wrote:
> Hi,
> 
> Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +:
> > On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
> 
> >> -.It Cm seek= Ns Ar n
> >> +.It Cm seek Ns = Ns Ar n
> >>  Seek
> >>  .Ar n
> >>  blocks from the beginning of the output before copying.
> >> -On non-tape devices, an
> >> -.Xr lseek 2
> >> -operation is used.
> >> -Otherwise, existing blocks are read and the data discarded.
> >> -If the user does not have read permission for the tape, it is positioned
> >> -using the tape
> >> +On a tape device, existing blocks are read and the data discarded;
> >> +if the user does not have read permission for the tape,
> >> +it is positioned using the tape
> >>  .Xr ioctl 2
> >>  function calls.
> >> +On all other devices devices, an
> >> +.Xr lseek 2
> >> +operation is used.
> >>  If the seek operation is past the end of file, space from the current
> >>  end of file to the specified offset is filled with blocks of NUL bytes.
> 
> > i think this change is ok. however i think non-tape is clearer than "on
> > all other devices". it's not a biggie, but i think the current stress on
> > non-tape devices is probably intentional.
> 
> The patch is misleading.  The sentence "If the seek operation is
> past the end of file..." only applies to tape devices, so it must
> not follow a sentence about lseek(2).
> 
> I'm not convinced the text needs to be changed.
> 
> The existing order makes sense because the non-tape case can be
> handled quickly, and then all the remaining complicated explanations
> apply to tapes only.
> 
> Or what would you want to change, and why?
> 

i understand. so i agree with your assessment (i failed to read further
into the text!)

> 
> >> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
> >>  For pipes, the correct number of bytes is read.
> >>  For all other devices, the correct number of blocks is read without
> >>  distinguishing between a partial or complete block being read.
> >> -.It Xo
> >> -.Sm off
> >> -.Cm status= Ar value
> >> -.Sm on
> >> -.Xc
> >> -Where
> >> +.It Cm status Ns = Ns Ar value
> >> +where
> 
> > you're correct that "Where" doesn;t really start a sentence, but this is
> > sentence start position. using a small letter is also incorrect.
> > 
> > in all honesty i would leave this, because it is not easy to rewrite in
> > a way that sounds natural. but maybe
> > 
> > The
> > .Ar value
> > parameter is one of the symbols from the following list:
> 
> That would look ugly by causing the line to wrap, but what about
> the patch below?
>

line wrap?

anyway, i'm ok with your diff, but in all honesty, i'd just get over the
fact that it isn;t quite lovely, and just start

.Ar value
is...

but i'm fine with your approach too.
jmc

> Yours,
>   Ingo
> 
> 
> Index: dd.1
> ===
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.36
> diff -u -r1.36 dd.1
> --- dd.1  14 Feb 2020 15:55:57 -  1.36
> +++ dd.1  14 Feb 2020 16:33:23 -
> @@ -136,9 +136,9 @@
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
>  .It Cm status Ns = Ns Ar value
> -Where
> +The
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the symbols from the following list:
>  .Bl -tag -width unblock
>  .It Cm noxfer
>  Do not print the transfer statistics as the last line of status output.
> @@ -147,9 +147,9 @@
>  Error messages are shown; informational messages are not.
>  .El
>  .It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ...
> -Where
> +Each
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the symbols from the following list:
>  .Bl -tag -width unblock
>  .It Cm ascii
>  The same as the
> 



Re: dd(1) wording and style

2020-02-14 Thread Ingo Schwarze
Hi,

Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +:
> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>> -.It Cm seek= Ns Ar n
>> +.It Cm seek Ns = Ns Ar n
>>  Seek
>>  .Ar n
>>  blocks from the beginning of the output before copying.
>> -On non-tape devices, an
>> -.Xr lseek 2
>> -operation is used.
>> -Otherwise, existing blocks are read and the data discarded.
>> -If the user does not have read permission for the tape, it is positioned
>> -using the tape
>> +On a tape device, existing blocks are read and the data discarded;
>> +if the user does not have read permission for the tape,
>> +it is positioned using the tape
>>  .Xr ioctl 2
>>  function calls.
>> +On all other devices devices, an
>> +.Xr lseek 2
>> +operation is used.
>>  If the seek operation is past the end of file, space from the current
>>  end of file to the specified offset is filled with blocks of NUL bytes.

> i think this change is ok. however i think non-tape is clearer than "on
> all other devices". it's not a biggie, but i think the current stress on
> non-tape devices is probably intentional.

The patch is misleading.  The sentence "If the seek operation is
past the end of file..." only applies to tape devices, so it must
not follow a sentence about lseek(2).

I'm not convinced the text needs to be changed.

The existing order makes sense because the non-tape case can be
handled quickly, and then all the remaining complicated explanations
apply to tapes only.

Or what would you want to change, and why?


>> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>>  For pipes, the correct number of bytes is read.
>>  For all other devices, the correct number of blocks is read without
>>  distinguishing between a partial or complete block being read.
>> -.It Xo
>> -.Sm off
>> -.Cm status= Ar value
>> -.Sm on
>> -.Xc
>> -Where
>> +.It Cm status Ns = Ns Ar value
>> +where

> you're correct that "Where" doesn;t really start a sentence, but this is
> sentence start position. using a small letter is also incorrect.
> 
> in all honesty i would leave this, because it is not easy to rewrite in
> a way that sounds natural. but maybe
> 
>   The
>   .Ar value
>   parameter is one of the symbols from the following list:

That would look ugly by causing the line to wrap, but what about
the patch below?

Yours,
  Ingo


Index: dd.1
===
RCS file: /cvs/src/bin/dd/dd.1,v
retrieving revision 1.36
diff -u -r1.36 dd.1
--- dd.114 Feb 2020 15:55:57 -  1.36
+++ dd.114 Feb 2020 16:33:23 -
@@ -136,9 +136,9 @@
 For all other devices, the correct number of blocks is read without
 distinguishing between a partial or complete block being read.
 .It Cm status Ns = Ns Ar value
-Where
+The
 .Ar value
-is one of the symbols from the following list.
+is one of the symbols from the following list:
 .Bl -tag -width unblock
 .It Cm noxfer
 Do not print the transfer statistics as the last line of status output.
@@ -147,9 +147,9 @@
 Error messages are shown; informational messages are not.
 .El
 .It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ...
-Where
+Each
 .Ar value
-is one of the symbols from the following list.
+is one of the symbols from the following list:
 .Bl -tag -width unblock
 .It Cm ascii
 The same as the



Re: dd(1) wording and style

2020-02-14 Thread Ingo Schwarze
Hi,

Jason McIntyre wrote on Fri, Feb 14, 2020 at 07:28:59AM +:
> On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:

>> * Fix a factual error in the description of bs: it does not
>>   supersede ibs/obs, dd will error out when both are specified.

> i don;t want to comment on this change

In fact, that's a bug in the code.  POSIX requires:

  bs=expr
Set both input and output block sizes to expr bytes,
superseding ibs= and obs=. 

  (see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/dd.html )

Yours,
  Ingo



Re: dd(1) wording and style

2020-02-13 Thread Jason McIntyre
On Thu, Feb 13, 2020 at 11:25:07PM +0100, Jan Stary wrote:
> This diff changes the dd(1) manpage in the following ways:
> 

morning.

> * Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
>   and similarly for others. The operand is "if", not "if=";
>   the "Ns = Ns" might be a slightly excessive markup,
>   but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
>   and is symmetric around the =
> 

yes, it is common. and preferred, i think.

> * Fix a factual error in the description of bs: it does not
>   supersede ibs/obs, dd will error out when both are specified.
>  

i don;t want to comment on this change

i'll make some comments inline though:

> * "On non-tape devices ... Otherwise ..." is a convoluted way
>   to say "tape"; describe tape first and remove the double negative.
> 
> * Say "It Cm status Ns = Ns Ar value" instead of
> 
>   .It Xo
>   .Sm off
>   .Cm status= Ar value
>   .Sm on
>   .Xc
> 
> * "Where every value" is not a beginning of a sentence.
> 
> * Tweak the wording of osync: regular-sized output block
>   is enforced in every case, drop the "if not a multiple".
> 
>   Jan
> 
> 
> Index: dd.1
> ===
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.35
> diff -u -p -r1.35 dd.1
> --- dd.1  16 Feb 2019 17:01:24 -  1.35
> +++ dd.1  13 Feb 2020 21:45:56 -
> @@ -57,11 +57,11 @@ and truncated input records to the stand
>  .Pp
>  The following operands are available:
>  .Bl -tag -width of=file
> -.It Cm if= Ns Ar file
> +.It Cm if Ns = Ns Ar file
>  Read input from
>  .Ar file
>  instead of the standard input.
> -.It Cm of= Ns Ar file
> +.It Cm of Ns = Ns Ar file
>  Write output to
>  .Ar file
>  instead of the standard output.
> @@ -72,22 +72,24 @@ If an initial portion of the output file
>  .Cm seek
>  operand),
>  the output file is truncated at that point.
> -.It Cm ibs= Ns Ar n
> +.It Cm ibs Ns = Ns Ar n
>  Set the input block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm obs= Ns Ar n
> +.It Cm obs Ns = Ns Ar n
>  Set the output block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm bs= Ns Ar n
> +.It Cm bs Ns = Ns Ar n
>  Set both the input and output block size to
>  .Ar n
> -bytes, superseding the
> +bytes.
> +It is an error to specify both
> +.Cm bs
> +and either of
>  .Cm ibs
> -and
> -.Cm obs
> -operands.
> +or
> +.Cm obs .
>  If no conversion values other than
>  .Cm noerror ,
>  .Cm notrunc ,
> @@ -95,36 +97,36 @@ or
>  .Cm sync
>  are specified, then each input block is copied to the output as a
>  single block without any aggregation of short blocks.
> -.It Cm cbs= Ns Ar n
> +.It Cm cbs Ns = Ns Ar n
>  Set the conversion record size to
>  .Ar n
>  bytes.
>  The conversion record size is required by the record oriented conversion
>  values.
> -.It Cm count= Ns Ar n
> +.It Cm count Ns = Ns Ar n
>  Copy only
>  .Ar n
>  input blocks.
> -.It Cm files= Ns Ar n
> +.It Cm files Ns = Ns Ar n
>  Copy
>  .Ar n
>  input files before terminating.
>  This operand is only applicable when the input device is a tape.
> -.It Cm seek= Ns Ar n
> +.It Cm seek Ns = Ns Ar n
>  Seek
>  .Ar n
>  blocks from the beginning of the output before copying.
> -On non-tape devices, an
> -.Xr lseek 2
> -operation is used.
> -Otherwise, existing blocks are read and the data discarded.
> -If the user does not have read permission for the tape, it is positioned
> -using the tape
> +On a tape device, existing blocks are read and the data discarded;
> +if the user does not have read permission for the tape,
> +it is positioned using the tape
>  .Xr ioctl 2
>  function calls.
> +On all other devices devices, an
> +.Xr lseek 2
> +operation is used.

i think this change is ok. however i think non-tape is clearer than "on
all other devices". it's not a biggie, but i think the current stress on
non-tape devices is probably intentional.

>  If the seek operation is past the end of file, space from the current
>  end of file to the specified offset is filled with blocks of NUL bytes.
> -.It Cm skip= Ns Ar n
> +.It Cm skip Ns = Ns Ar n
>  Skip
>  .Ar n
>  blocks from the beginning of the input before copying.
> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>  For pipes, the correct number of bytes is read.
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
> -.It Xo
> -.Sm off
> -.Cm status= Ar value
> -.Sm on
> -.Xc
> -Where
> +.It Cm status Ns = Ns Ar value
> +where

you're correct that "Where" doesn;t really start a sentence, but this is
sentence start position. using a small letter is also incorrect.

in all honesty i would leave this, because it is not easy to rewrite in
a way that sounds natural. but maybe

The
.Ar value
parameter is one of the symbols from the following list:

>  .Ar value
> -is one of the symbols from the 

Re: dd(1) wording and style

2020-02-13 Thread Jan Stary
On Feb 13 23:25:07, h...@stare.cz wrote:
> This diff changes the dd(1) manpage in the following ways:
> 
> * Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
>   and similarly for others. The operand is "if", not "if=";
>   the "Ns = Ns" might be a slightly excessive markup,
>   but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
>   and is symmetric around the =
> 
> * Fix a factual error in the description of bs: it does not
>   supersede ibs/obs, dd will error out when both are specified.
>  
> * "On non-tape devices ... Otherwise ..." is a convoluted way
>   to say "tape"; describe tape first and remove the double negative.
> 
> * Say "It Cm status Ns = Ns Ar value" instead of
> 
>   .It Xo
>   .Sm off
>   .Cm status= Ar value
>   .Sm on
>   .Xc
> 
> * "Where every value" is not a beginning of a sentence.
> 
> * Tweak the wording of osync: regular-sized output block
>   is enforced in every case, drop the "if not a multiple".
> 
>   Jan
> 
> 
> Index: dd.1
> ===
> RCS file: /cvs/src/bin/dd/dd.1,v
> retrieving revision 1.35
> diff -u -p -r1.35 dd.1
> --- dd.1  16 Feb 2019 17:01:24 -  1.35
> +++ dd.1  13 Feb 2020 21:45:56 -
> @@ -57,11 +57,11 @@ and truncated input records to the stand
>  .Pp
>  The following operands are available:
>  .Bl -tag -width of=file
> -.It Cm if= Ns Ar file
> +.It Cm if Ns = Ns Ar file
>  Read input from
>  .Ar file
>  instead of the standard input.
> -.It Cm of= Ns Ar file
> +.It Cm of Ns = Ns Ar file
>  Write output to
>  .Ar file
>  instead of the standard output.
> @@ -72,22 +72,24 @@ If an initial portion of the output file
>  .Cm seek
>  operand),
>  the output file is truncated at that point.
> -.It Cm ibs= Ns Ar n
> +.It Cm ibs Ns = Ns Ar n
>  Set the input block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm obs= Ns Ar n
> +.It Cm obs Ns = Ns Ar n
>  Set the output block size to
>  .Ar n
>  bytes instead of the default 512.
> -.It Cm bs= Ns Ar n
> +.It Cm bs Ns = Ns Ar n
>  Set both the input and output block size to
>  .Ar n
> -bytes, superseding the
> +bytes.
> +It is an error to specify both
> +.Cm bs
> +and either of
>  .Cm ibs
> -and
> -.Cm obs
> -operands.
> +or
> +.Cm obs .
>  If no conversion values other than
>  .Cm noerror ,
>  .Cm notrunc ,
> @@ -95,36 +97,36 @@ or
>  .Cm sync
>  are specified, then each input block is copied to the output as a
>  single block without any aggregation of short blocks.
> -.It Cm cbs= Ns Ar n
> +.It Cm cbs Ns = Ns Ar n
>  Set the conversion record size to
>  .Ar n
>  bytes.
>  The conversion record size is required by the record oriented conversion
>  values.
> -.It Cm count= Ns Ar n
> +.It Cm count Ns = Ns Ar n
>  Copy only
>  .Ar n
>  input blocks.
> -.It Cm files= Ns Ar n
> +.It Cm files Ns = Ns Ar n
>  Copy
>  .Ar n
>  input files before terminating.
>  This operand is only applicable when the input device is a tape.
> -.It Cm seek= Ns Ar n
> +.It Cm seek Ns = Ns Ar n
>  Seek
>  .Ar n
>  blocks from the beginning of the output before copying.
> -On non-tape devices, an
> -.Xr lseek 2
> -operation is used.
> -Otherwise, existing blocks are read and the data discarded.
> -If the user does not have read permission for the tape, it is positioned
> -using the tape
> +On a tape device, existing blocks are read and the data discarded;
> +if the user does not have read permission for the tape,
> +it is positioned using the tape
>  .Xr ioctl 2
>  function calls.
> +On all other devices devices, an

devices devices
sorry

> +.Xr lseek 2
> +operation is used.
>  If the seek operation is past the end of file, space from the current
>  end of file to the specified offset is filled with blocks of NUL bytes.
> -.It Cm skip= Ns Ar n
> +.It Cm skip Ns = Ns Ar n
>  Skip
>  .Ar n
>  blocks from the beginning of the input before copying.
> @@ -135,14 +137,10 @@ Otherwise, input data is read and discar
>  For pipes, the correct number of bytes is read.
>  For all other devices, the correct number of blocks is read without
>  distinguishing between a partial or complete block being read.
> -.It Xo
> -.Sm off
> -.Cm status= Ar value
> -.Sm on
> -.Xc
> -Where
> +.It Cm status Ns = Ns Ar value
> +where
>  .Ar value
> -is one of the symbols from the following list.
> +is one of following.
>  .Bl -tag -width unblock
>  .It Cm noxfer
>  Do not print the transfer statistics as the last line of status output.
> @@ -150,15 +148,10 @@ Do not print the transfer statistics as 
>  Do not print the status output.
>  Error messages are shown; informational messages are not.
>  .El
> -.It Xo
> -.Sm off
> -.Cm conv= Ar value Oo ,
> -.Sm on
> -.Ar value ... Oc
> -.Xc
> -Where
> +.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value , Ns ...
> +where every
>  .Ar value
> -is one of the symbols from the following list.
> +is one of the following.
>  .Bl -tag -width unblock
>  .It Cm ascii
>  The same as the
> @@ -235,13 +228,11 @@ 

dd(1) wording and style

2020-02-13 Thread Jan Stary
This diff changes the dd(1) manpage in the following ways:

* Replace "It Cm if= Ns Ar file" with "It Cm if Ns = Ns Ar file"
  and similarly for others. The operand is "if", not "if=";
  the "Ns = Ns" might be a slightly excessive markup,
  but common: grep -Fr 'Ns = Ns' /usr/share/man | wc -l
  and is symmetric around the =

* Fix a factual error in the description of bs: it does not
  supersede ibs/obs, dd will error out when both are specified.
 
* "On non-tape devices ... Otherwise ..." is a convoluted way
  to say "tape"; describe tape first and remove the double negative.

* Say "It Cm status Ns = Ns Ar value" instead of

.It Xo
.Sm off
.Cm status= Ar value
.Sm on
.Xc

* "Where every value" is not a beginning of a sentence.

* Tweak the wording of osync: regular-sized output block
  is enforced in every case, drop the "if not a multiple".

Jan


Index: dd.1
===
RCS file: /cvs/src/bin/dd/dd.1,v
retrieving revision 1.35
diff -u -p -r1.35 dd.1
--- dd.116 Feb 2019 17:01:24 -  1.35
+++ dd.113 Feb 2020 21:45:56 -
@@ -57,11 +57,11 @@ and truncated input records to the stand
 .Pp
 The following operands are available:
 .Bl -tag -width of=file
-.It Cm if= Ns Ar file
+.It Cm if Ns = Ns Ar file
 Read input from
 .Ar file
 instead of the standard input.
-.It Cm of= Ns Ar file
+.It Cm of Ns = Ns Ar file
 Write output to
 .Ar file
 instead of the standard output.
@@ -72,22 +72,24 @@ If an initial portion of the output file
 .Cm seek
 operand),
 the output file is truncated at that point.
-.It Cm ibs= Ns Ar n
+.It Cm ibs Ns = Ns Ar n
 Set the input block size to
 .Ar n
 bytes instead of the default 512.
-.It Cm obs= Ns Ar n
+.It Cm obs Ns = Ns Ar n
 Set the output block size to
 .Ar n
 bytes instead of the default 512.
-.It Cm bs= Ns Ar n
+.It Cm bs Ns = Ns Ar n
 Set both the input and output block size to
 .Ar n
-bytes, superseding the
+bytes.
+It is an error to specify both
+.Cm bs
+and either of
 .Cm ibs
-and
-.Cm obs
-operands.
+or
+.Cm obs .
 If no conversion values other than
 .Cm noerror ,
 .Cm notrunc ,
@@ -95,36 +97,36 @@ or
 .Cm sync
 are specified, then each input block is copied to the output as a
 single block without any aggregation of short blocks.
-.It Cm cbs= Ns Ar n
+.It Cm cbs Ns = Ns Ar n
 Set the conversion record size to
 .Ar n
 bytes.
 The conversion record size is required by the record oriented conversion
 values.
-.It Cm count= Ns Ar n
+.It Cm count Ns = Ns Ar n
 Copy only
 .Ar n
 input blocks.
-.It Cm files= Ns Ar n
+.It Cm files Ns = Ns Ar n
 Copy
 .Ar n
 input files before terminating.
 This operand is only applicable when the input device is a tape.
-.It Cm seek= Ns Ar n
+.It Cm seek Ns = Ns Ar n
 Seek
 .Ar n
 blocks from the beginning of the output before copying.
-On non-tape devices, an
-.Xr lseek 2
-operation is used.
-Otherwise, existing blocks are read and the data discarded.
-If the user does not have read permission for the tape, it is positioned
-using the tape
+On a tape device, existing blocks are read and the data discarded;
+if the user does not have read permission for the tape,
+it is positioned using the tape
 .Xr ioctl 2
 function calls.
+On all other devices devices, an
+.Xr lseek 2
+operation is used.
 If the seek operation is past the end of file, space from the current
 end of file to the specified offset is filled with blocks of NUL bytes.
-.It Cm skip= Ns Ar n
+.It Cm skip Ns = Ns Ar n
 Skip
 .Ar n
 blocks from the beginning of the input before copying.
@@ -135,14 +137,10 @@ Otherwise, input data is read and discar
 For pipes, the correct number of bytes is read.
 For all other devices, the correct number of blocks is read without
 distinguishing between a partial or complete block being read.
-.It Xo
-.Sm off
-.Cm status= Ar value
-.Sm on
-.Xc
-Where
+.It Cm status Ns = Ns Ar value
+where
 .Ar value
-is one of the symbols from the following list.
+is one of following.
 .Bl -tag -width unblock
 .It Cm noxfer
 Do not print the transfer statistics as the last line of status output.
@@ -150,15 +148,10 @@ Do not print the transfer statistics as 
 Do not print the status output.
 Error messages are shown; informational messages are not.
 .El
-.It Xo
-.Sm off
-.Cm conv= Ar value Oo ,
-.Sm on
-.Ar value ... Oc
-.Xc
-Where
+.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value , Ns ...
+where every
 .Ar value
-is one of the symbols from the following list.
+is one of the following.
 .Bl -tag -width unblock
 .It Cm ascii
 The same as the
@@ -235,13 +228,11 @@ The
 value is not supported for tapes.
 .It Cm osync
 Pad the final output block to the full output block size.
-If the input file is not a multiple of the output block size
-after conversion, this conversion forces the final output block
-to be the same size as preceding blocks for use on devices that require
+This forces the final output block to be the same size
+as preceding