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

[Junio C Hamano <gitster@pobox.com>]

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