Re: [PATCH 1/2] copyfilerange: (usage) correct the markup and improve the wording

On Mon, Mar 09, 2026 at 05:09:02PM +0100, Benno Schulenberg wrote:
> The <source>, <destination>, and <range> arguments are required,
> so do not mark them as optional (with the square brackets).
> Also, trim the redundant lines about the source and destination
> files, improve the explanation for the <range> argument, and
> keep the text within 80 columns.
> 
> Furthermore, list the short options first (as is custom), and
> match the indentaion of the -h and -V options to the others.
> 
> CC: Dick Marinus <[email protected]>
> Signed-off-by: Benno Schulenberg <[email protected]>
> ---
>  misc-utils/copyfilerange.c | 18 ++++++++----------
>  1 file changed, 8 insertions(+), 10 deletions(-)
> 
> diff --git a/misc-utils/copyfilerange.c b/misc-utils/copyfilerange.c
> index 20f0373bd..a72c81cd1 100644
> --- a/misc-utils/copyfilerange.c
> +++ b/misc-utils/copyfilerange.c
> @@ -55,25 +55,23 @@ static void __attribute__((__noreturn__)) usage(void)
>  	FILE *out = stdout;
>  	fputs(USAGE_HEADER, out);
>  	fprintf(out,
> -		_(" %1$s [options] [<source>] [<destination>] [<range>...]\n"),
> +		_(" %1$s [options] <source> <destination> <range>...\n"),
>  		program_invocation_short_name);
>  
>  	fputs(USAGE_SEPARATOR, out);
> -	fputsln(_("Copy file ranges from source to destination file."), out);
> +	fputsln(_("Copy the specified range(s) from source to destination file."), out);
>  
>  	fputs(USAGE_SEPARATOR, out);
> -	fputsln(_(" source                      source filename"), out);
> -	fputsln(_(" destination                 destination filename"), out);
> -	fputsln(_(" range                       source_offset:dest_offset:length, all values are in bytes"), out);
> -	fputsln(_("                             if length is set to 0 as much as available will be copied"), out);
> -	fputsln(_("                             when the offset is omitted the last file position is used"), out);
> +	fputsln(_("Each <range> is of the form <source_offset>:<destination_offset>:<length>,\n"
> +	          "with all values in bytes. If <length> is 0, as much data as available will\n"
> +	          "be copied. When an offset is omitted, the last file position is used."), out);

Hmm... for this purpose, we already have the USAGE_ARGUMENTS section
(usually after the OPTIONS section).

What about:

    fputs(USAGE_ARGUMENTS, out);
    fputsln(_(" <range> is of the form <source_offset>:<destination_offset>:<length>,\n"
              " with all values in bytes. If <length> is 0, as much data as available will\n"
              " be copied. When an offset is omitted, the last file position is used."), out);

  Karel


-- 
 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com