| Message ID | 20211014120233.7834-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [RESEND] archive: rewrite description for compression level option | expand |
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
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`?).
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"?
Æ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 - ."?
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 -------------
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(-) base-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11