{"thread":{"id":"56709","subject":"[PATCH RESEND] archive: rewrite description for compression level option","startedAt":"2021-10-14T12:03:17Z","lastAt":"2021-10-15T06:00:18Z","messageCount":5,"participants":["Bagas Sanjaya","Junio C Hamano","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"438753","messageId":"20211014120233.7834-1-bagasdotme@gmail.com","threadId":"56709","inReplyTo":null,"subject":"[PATCH RESEND] archive: rewrite description for compression level option","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-14T12:02:34Z","receivedAt":"2021-10-14T12:03:17Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Currently, the description of compression level option (`-` or\n`-#`) only specifies two level (`-0` and `-9`), giving the impression\nthat only both levels are accepted, although other level number can be\nspecified. Rewrite the description.\n\nSigned-off-by: Bagas Sanjaya \n---\n Documentation/git-archive.txt | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 9f8172828d..097b999bbd 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -93,12 +93,11 @@ BACKEND EXTRA OPTIONS\n \n zip\n ~~~\n--0::\n-\tStore the files instead of deflating them.\n--9::\n-\tHighest and slowest compression level. You can specify any\n-\tnumber from 1 to 9 to adjust compression speed and ratio.\n-\n+-::\n+\tSelect the compression level. Higher number indicates better\n+\tcompression at the expense of longer time to compress. Valid\n+\tvalues are from 0 to 9. If 0 is selected, the files will be\n+\tstored without compressing.\n \n CONFIGURATION\n -------------\n\nbase-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438763","messageId":"xmqqh7djczxr.fsf@gitster.g","threadId":"56709","inReplyTo":"20211014120233.7834-1-bagasdotme@gmail.com","subject":"Re: [PATCH RESEND] archive: rewrite description for compression level option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-14T16:51:28Z","receivedAt":"2021-10-14T16:51:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> Currently, the description of compression level option (`-` or\n> `-#`) only specifies two level (`-0` and `-9`), giving the impression\n> that only both levels are accepted, although other level number can be\n> specified. Rewrite the description.\n\nWhile I find that the updated description is more detailed [*], I am\nnot sure if the change to the heading is an improvement for readers,\nas I do not think of a case where users would choose to use anything\nother than to use (1) no compression level option, (2) '-0' for\nspeed, or (3) '-9' for size, and explicitly singling out `-0` and\n`-9` like the current text does would help those who wonder what the\noption, used in a script written by somebody else that they are\ngiven to maintain, mean, better than the updated text that does not\neven allow /-9 in their pager to look for the description, if you\nonly had `-` or `-#`.\n\nAlso, unless we take `-47`, I do not think it is a good idea to\nspell it as `-`. Perhaps `-` is OK, but it shares\nexactly the same issue as `-` I mentioned above.\n\nThanks.\n\n\n[Footnote]\n\n * Not that the original does not carry the same information; when\n \"-9\" is described as \"highest and slowest\", accompanied by \"any\n number from 1 to 9 to adjust\", the readers can easily read that\n \"Higher number indicates ...\" tradeoff without getting told.\n\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Documentation/git-archive.txt | 11 +++++------\n> 1 file changed, 5 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\n> index 9f8172828d..097b999bbd 100644\n> --- a/Documentation/git-archive.txt\n> +++ b/Documentation/git-archive.txt\n> @@ -93,12 +93,11 @@ BACKEND EXTRA OPTIONS\n> \n> zip\n> ~~~\n> --0::\n> -\tStore the files instead of deflating them.\n> --9::\n> -\tHighest and slowest compression level. You can specify any\n> -\tnumber from 1 to 9 to adjust compression speed and ratio.\n> -\n> +-::\n> +\tSelect the compression level. Higher number indicates better\n> +\tcompression at the expense of longer time to compress. Valid\n> +\tvalues are from 0 to 9. If 0 is selected, the files will be\n> +\tstored without compressing.\n> \n> CONFIGURATION\n> -------------\n>\n> base-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11\n"},{"id":"438809","messageId":"8e99fbef-32d0-9f19-4e57-1f28108c70cb@gmail.com","threadId":"56709","inReplyTo":"xmqqh7djczxr.fsf@gitster.g","subject":"Re: [PATCH RESEND] archive: rewrite description for compression level option","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-15T03:22:39Z","receivedAt":"2021-10-15T03:22:46Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 14/10/21 23.51, Junio C Hamano wrote:\n> Bagas Sanjaya writes:\n> \n>> Currently, the description of compression level option (`-` or\n>> `-#`) only specifies two level (`-0` and `-9`), giving the impression\n>> that only both levels are accepted, although other level number can be\n>> specified. Rewrite the description.\n> \n> While I find that the updated description is more detailed [*], I am\n> not sure if the change to the heading is an improvement for readers,\n> as I do not think of a case where users would choose to use anything\n> other than to use (1) no compression level option, (2) '-0' for\n> speed, or (3) '-9' for size, and explicitly singling out `-0` and\n> `-9` like the current text does would help those who wonder what the\n> option, used in a script written by somebody else that they are\n> given to maintain, mean, better than the updated text that does not\n> even allow /-9 in their pager to look for the description, if you\n> only had `-` or `-#`.\n> \n> Also, unless we take `-47`, I do not think it is a good idea to\n> spell it as `-`. Perhaps `-` is OK, but it shares\n> exactly the same issue as `-` I mentioned above.\n\nMaybe we can say `-0 ... -9` to indicate the syntax, while both the \nendpoints are common but special case.\n\nAlso, we don't mention default compression level (`-6`?).\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"438810","messageId":"87lf2vylj9.fsf@evledraar.gmail.com","threadId":"56709","inReplyTo":"8e99fbef-32d0-9f19-4e57-1f28108c70cb@gmail.com","subject":"Re: [PATCH RESEND] archive: rewrite description for compression level option","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-15T04:11:01Z","receivedAt":"2021-10-15T04:11:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Oct 15 2021, Bagas Sanjaya wrote:\n\n> On 14/10/21 23.51, Junio C Hamano wrote:\n>> Bagas Sanjaya writes:\n>> \n>>> Currently, the description of compression level option (`-` or\n>>> `-#`) only specifies two level (`-0` and `-9`), giving the impression\n>>> that only both levels are accepted, although other level number can be\n>>> specified. Rewrite the description.\n>> While I find that the updated description is more detailed [*], I am\n>> not sure if the change to the heading is an improvement for readers,\n>> as I do not think of a case where users would choose to use anything\n>> other than to use (1) no compression level option, (2) '-0' for\n>> speed, or (3) '-9' for size, and explicitly singling out `-0` and\n>> `-9` like the current text does would help those who wonder what the\n>> option, used in a script written by somebody else that they are\n>> given to maintain, mean, better than the updated text that does not\n>> even allow /-9 in their pager to look for the description, if you\n>> only had `-` or `-#`.\n>> Also, unless we take `-47`, I do not think it is a good idea to\n>> spell it as `-`. Perhaps `-` is OK, but it shares\n>> exactly the same issue as `-` I mentioned above.\n>\n> Maybe we can say `-0 ... -9` to indicate the syntax, while both the\n> endpoints are common but special case.\n>\n> Also, we don't mention default compression level (`-6`?).\n\nWhatever we do here maybe we'd do well to emulate what \"man gzip\" does,\nup to and including perhaps adding the --fast and --best synonyms to\n\"git archive\"?\n"},{"id":"438811","messageId":"xmqqpms6akup.fsf@gitster.g","threadId":"56709","inReplyTo":"87lf2vylj9.fsf@evledraar.gmail.com","subject":"Re: [PATCH RESEND] archive: rewrite description for compression level option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-15T06:00:14Z","receivedAt":"2021-10-15T06:00:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Whatever we do here maybe we'd do well to emulate what \"man gzip\" does,\n> up to and including perhaps adding the --fast and --best synonyms to\n> \"git archive\"?\n\nThis section of the documentation is not about describing .tar.gz\nbut about .zip, so emulating \"man gzip\" to replace the description\nunder discussion may not be an excellent idea. FWIW, \"zip -h\" on a\nsystem where \"zip\" is Info-ZIP gives\n\n\t$ zip -h\n\t...\n\t-0 store only -9 compress better\n\t...\n\nand the existing \"-0 or -9\" that hints intermediate numbers are\npossible matches its spirit.\n\nAt the implementation level, the parsing of - is shared\nacross archivers, but ARCHIVER_HIGH_COMPRESSION_LEVELS bit is only\nenabled in archive-tar, and not in archive-zip, which means that\narchive-tar can take -10 and higher compression levels while\narchive-zip would not, I think. If we are to add a separate\ndesciption for - to .tar.gz format, it would work well, as\nwe would not want to say it is limited to '-9' there.\n\nAs to --fast/--best, I am not sure how well it would work with\neither. Would \"tar\" take \"tar zcf - --fast .\" or \"tar zc9f - .\"?\n"}]}