[PATCH RESEND] archive: rewrite description for compression level option

[PATCH RESEND] archive: rewrite description for compression level option

[Bagas Sanjaya]

Currently, the description of compression level option (`-<number>` or
`-#`) only specifies two level (`-0` and `-9`), giving the impression
that only both levels are accepted, although other level number can be
specified. Rewrite the description.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/git-archive.txt | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 9f8172828d..097b999bbd 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -93,12 +93,11 @@ 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.
-
+-<number>::
+	Select the compression level. Higher number indicates better
+	compression at the expense of longer time to compress. Valid
+	values are from 0 to 9. If 0 is selected, the files will be
+	stored without compressing.
 
 CONFIGURATION
 -------------

base-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11
-- 
An old man doll... just what I always wanted! - Clara

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

[Junio C Hamano]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Currently, the description of compression level option (`-<number>` or
> `-#`) only specifies two level (`-0` and `-9`), giving the impression
> that only both levels are accepted, although other level number can be
> specified. Rewrite the description.

While I find that the updated description is more detailed [*], I am
not sure if the change to the heading is an improvement for readers,
as I do not think of a case where users would choose to use anything
other than to use (1) no compression level option, (2) '-0' for
speed, or (3) '-9' for size, and explicitly singling out `-0` and
`-9` like the current text does would help those who wonder what the
option, used in a script written by somebody else that they are
given to maintain, mean, better than the updated text that does not
even allow /-9 in their pager to look for the description, if you
only had `-<number>` or `-#`.

Also, unless we take `-47`, I do not think it is a good idea to
spell it as `-<number>`.  Perhaps `-<digit>` is OK, but it shares
exactly the same issue as `-<number>` I mentioned above.

Thanks.


[Footnote]

 * Not that the original does not carry the same information; when
   "-9" is described as "highest and slowest", accompanied by "any
   number from 1 to 9 to adjust", the readers can easily read that
   "Higher number indicates ..." tradeoff without getting told.

> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/git-archive.txt | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
> index 9f8172828d..097b999bbd 100644
> --- a/Documentation/git-archive.txt
> +++ b/Documentation/git-archive.txt
> @@ -93,12 +93,11 @@ 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.
> -
> +-<number>::
> +	Select the compression level. Higher number indicates better
> +	compression at the expense of longer time to compress. Valid
> +	values are from 0 to 9. If 0 is selected, the files will be
> +	stored without compressing.
>  
>  CONFIGURATION
>  -------------
>
> base-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11

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

[Bagas Sanjaya]

On 14/10/21 23.51, Junio C Hamano wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
>> Currently, the description of compression level option (`-<number>` or
>> `-#`) only specifies two level (`-0` and `-9`), giving the impression
>> that only both levels are accepted, although other level number can be
>> specified. Rewrite the description.
> 
> While I find that the updated description is more detailed [*], I am
> not sure if the change to the heading is an improvement for readers,
> as I do not think of a case where users would choose to use anything
> other than to use (1) no compression level option, (2) '-0' for
> speed, or (3) '-9' for size, and explicitly singling out `-0` and
> `-9` like the current text does would help those who wonder what the
> option, used in a script written by somebody else that they are
> given to maintain, mean, better than the updated text that does not
> even allow /-9 in their pager to look for the description, if you
> only had `-<number>` or `-#`.
> 
> Also, unless we take `-47`, I do not think it is a good idea to
> spell it as `-<number>`.  Perhaps `-<digit>` is OK, but it shares
> exactly the same issue as `-<number>` I mentioned above.

Maybe we can say `-0 ... -9` to indicate the syntax, while both the 
endpoints are common but special case.

Also, we don't mention default compression level (`-6`?).

-- 
An old man doll... just what I always wanted! - Clara

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

[Ævar Arnfjörð Bjarmason]

On Fri, Oct 15 2021, Bagas Sanjaya wrote:

> On 14/10/21 23.51, Junio C Hamano wrote:
>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>> 
>>> Currently, the description of compression level option (`-<number>` or
>>> `-#`) only specifies two level (`-0` and `-9`), giving the impression
>>> that only both levels are accepted, although other level number can be
>>> specified. Rewrite the description.
>> While I find that the updated description is more detailed [*], I am
>> not sure if the change to the heading is an improvement for readers,
>> as I do not think of a case where users would choose to use anything
>> other than to use (1) no compression level option, (2) '-0' for
>> speed, or (3) '-9' for size, and explicitly singling out `-0` and
>> `-9` like the current text does would help those who wonder what the
>> option, used in a script written by somebody else that they are
>> given to maintain, mean, better than the updated text that does not
>> even allow /-9 in their pager to look for the description, if you
>> only had `-<number>` or `-#`.
>> Also, unless we take `-47`, I do not think it is a good idea to
>> spell it as `-<number>`.  Perhaps `-<digit>` is OK, but it shares
>> exactly the same issue as `-<number>` I mentioned above.
>
> Maybe we can say `-0 ... -9` to indicate the syntax, while both the
> endpoints are common but special case.
>
> Also, we don't mention default compression level (`-6`?).

Whatever we do here maybe we'd do well to emulate what "man gzip" does,
up to and including perhaps adding the --fast and --best synonyms to
"git archive"?

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

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> Whatever we do here maybe we'd do well to emulate what "man gzip" does,
> up to and including perhaps adding the --fast and --best synonyms to
> "git archive"?

This section of the documentation is not about describing .tar.gz
but about .zip, so emulating "man gzip" to replace the description
under discussion may not be an excellent idea.  FWIW, "zip -h" on a
system where "zip" is Info-ZIP gives

	$ zip -h
	...
	-0    store only                -9 compress better
	...

and the existing "-0 or -9" that hints intermediate numbers are
possible matches its spirit.

At the implementation level, the parsing of -<number> is shared
across archivers, but ARCHIVER_HIGH_COMPRESSION_LEVELS bit is only
enabled in archive-tar, and not in archive-zip, which means that
archive-tar can take -10 and higher compression levels while
archive-zip would not, I think.  If we are to add a separate
desciption for -<number> to .tar.gz format, it would work well, as
we would not want to say it is limited to '-9' there.

As to --fast/--best, I am not sure how well it would work with
either.  Would "tar" take "tar zcf - --fast ." or "tar zc9f - ."?