Re: [PATCH v2] archive: rewrite description for compression level option

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

 SYNOPSIS
 --------
 [verse]
-'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
+'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [-#]
 	      [-o <file> | --output=<file>] [--worktree-attributes]
 	      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
 	      [<path>...]

@@ -65,10 +65,6 @@ OPTIONS
 	Look for attributes in .gitattributes files in the working tree
 	as well (see <<ATTRIBUTES>>).
 
-<extra>::
-	This can be any options that the archiver backend understands.
-	See next section.
-
 --remote=<repo>::
 	Instead of making a tar archive from the local repository,
 	retrieve a tar archive from a remote repository. Note that the

@@ -88,17 +84,13 @@ OPTIONS
 	of the current working directory are included in the archive.
 	If one or more paths are specified, only these are included.
 
-BACKEND EXTRA OPTIONS
----------------------
-
-zip
-~~~
--0::
-	Store the files instead of deflating them.
--9::
-	Highest and slowest compression level.  You can specify any
-	number from 1 to 9 to adjust compression speed and ratio.
-
+-#::
+	Select the compression level. The supported levels and default
+	value (if none is selected) are depending on compression command
+	backend configured for the selected format (either explicitly with
+	`--format` or inferred from file name specified with `-o`). Common
+	values are `-0` for only storing files (zip only), `-1` for fastest
+	compression time, and `-9` for best compression ratio.

This is getting there, but I think we really should not have a -# in the
synopsis, since that's not how we refer to a digit-wildcard in any other
context. And users might assume that a literal -# is meant, some
commonly used tools even support that, e.g. try:

    curl -L -o /dev/null -# https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-11.1.0-amd64-DVD-1.iso

Let's just use "[-<0..9 digit>[", or "[-<digit>]" in the SYNOPSIS and
explain that it's 0..9 below in this section..

I agree with you about `-#`.

I do not think it is a good idea to remove the backend-specific
option section like this patch does, as the next archiver may not
even support `-<digit>`.  Even with the existing two backends, the
description of it need to be different (cf. the other response I
sent you last night on "--fast/--best"?).  Rather, the first thing
to improve would be to _add_ a section for `tar` format, next to the
`zip` format, I would think, as those who wants to write `tar` do
not have to read `zip` specific options, and vice versa.

The new paragraph on `-#` in the patch may work as a replacement for
existing explanation for `zip`-specific extra options, but it needs
to drop the changes made to make it applicable to any format, like
"depending on ... backend" and "(zip only)" if we want to take it.

Thanks.