Re: [PATCH RESEND] archive: rewrite description for compression level option
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 14, 2021, 16:51 UTC
- Message-ID
- <xmqqh7djczxr.fsf@gitster.g>
- In-Reply-To
- <20211014120233.7834-1-bagasdotme@gmail.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.
Show 29 quoted lines
> 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