{"thread":{"id":"59140","subject":"[PATCH] Documentation: render dash correctly","startedAt":"2023-01-22T16:56:35Z","lastAt":"2023-01-23T18:52:24Z","messageCount":7,"participants":["Andrei Rybak","Junio C Hamano","Martin Ågren"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"470886","messageId":"20230122165628.1601062-1-rybak.a.v@gmail.com","threadId":"59140","inReplyTo":null,"subject":"[PATCH] Documentation: render dash correctly","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-01-22T16:56:28Z","receivedAt":"2023-01-22T16:56:35Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"Three hyphens are rendered verbatim in documentation, so \"--\" has to be\nused to produce a dash.  Fix asciidoc output for dashes.  This is\nsimilar to previous commits f0b922473e (Documentation: render special\ncharacters correctly, 2021-07-29) and de82095a95 (doc\nhash-function-transition: fix asciidoc output, 2021-02-05).\n\nSigned-off-by: Andrei Rybak <rybak.a.v@gmail.com>\n---\n Documentation/git-apply.txt                          | 2 +-\n Documentation/git-read-tree.txt                      | 2 +-\n Documentation/git.txt                                | 2 +-\n Documentation/technical/hash-function-transition.txt | 2 +-\n 4 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 1d478cbe9b..5e16e6db7e 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -208,7 +208,7 @@ behavior:\n * `warn` outputs warnings for a few such errors, but applies the\n   patch as-is (default).\n * `fix` outputs warnings for a few such errors, and applies the\n-  patch after fixing them (`strip` is a synonym --- the tool\n+  patch after fixing them (`strip` is a synonym -- the tool\n   used to consider only trailing whitespace characters as errors, and the\n   fix involved 'stripping' them, but modern Gits do more).\n * `error` outputs warnings for a few such errors, and refuses\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 7567955bad..b09707474d 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -219,7 +219,7 @@ see which of the \"local changes\" that you made were carried forward by running\n `git diff-index --cached $M`.  Note that this does not\n necessarily match what `git diff-index --cached $H` would have\n produced before such a two tree merge.  This is because of cases\n-18 and 19 --- if you already had the changes in $M (e.g. maybe\n+18 and 19 -- if you already had the changes in $M (e.g. maybe\n you picked it up via e-mail in a patch form), `git diff-index\n --cached $H` would have told you about the change before this\n merge, but it would not show in `git diff-index --cached $M`\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex f9a7a4554c..74973d3cc4 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -613,7 +613,7 @@ The file parameters can point at the user's working file\n (e.g. `new-file` in \"git-diff-files\"), `/dev/null` (e.g. `old-file`\n when a new file is added), or a temporary file (e.g. `old-file` in the\n index).  `GIT_EXTERNAL_DIFF` should not worry about unlinking the\n-temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.\n+temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits.\n +\n For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1\n parameter, <path>.\ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex e2ac36dd21..ed57481089 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -562,7 +562,7 @@ hash re-encode during clone and to encourage peers to modernize.\n The design described here allows fetches by SHA-1 clients of a\n personal SHA-256 repository because it's not much more difficult than\n allowing pushes from that repository. This support needs to be guarded\n-by a configuration option --- servers like git.kernel.org that serve a\n+by a configuration option -- servers like git.kernel.org that serve a\n large number of clients would not be expected to bear that cost.\n \n Meaning of signatures\n-- \n2.39.0\n\n"},{"id":"470892","messageId":"xmqqcz76qizp.fsf@gitster.g","threadId":"59140","inReplyTo":"20230122165628.1601062-1-rybak.a.v@gmail.com","subject":"Re: [PATCH] Documentation: render dash correctly","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-22T22:53:14Z","receivedAt":"2023-01-22T22:53:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andrei Rybak <rybak.a.v@gmail.com> writes:\n\n> Three hyphens are rendered verbatim in documentation, so \"--\" has to be\n> used to produce a dash.\n\nSad but true.  I suspect folks with TeX background were so\naccustomed to type three dashes to obtain em dash, but with AsciiDoc\n(and asciidoctor), sadly, two dashes is a way to ask for em dash.\n\nThe changes in your patch look all reasonable to me at the source\nlevel; I didn't do Documentation/doc-diff to verify, though.\n\nThanks.\n"},{"id":"470900","messageId":"CAN0heSo6poJMNSmJ2Vwy2ecrW3YRc0E5VYLH22fXUgnqfx_TAA@mail.gmail.com","threadId":"59140","inReplyTo":"xmqqcz76qizp.fsf@gitster.g","subject":"Re: [PATCH] Documentation: render dash correctly","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-01-23T08:19:11Z","receivedAt":"2023-01-23T08:19:25Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 22 Jan 2023 at 23:55, Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Andrei Rybak <rybak.a.v@gmail.com> writes:\n>\n> > Three hyphens are rendered verbatim in documentation, so \"--\" has to be\n> > used to produce a dash.\n>\n> Sad but true.  I suspect folks with TeX background were so\n> accustomed to type three dashes to obtain em dash, but with AsciiDoc\n> (and asciidoctor), sadly, two dashes is a way to ask for em dash.\n>\n> The changes in your patch look all reasonable to me at the source\n> level; I didn't do Documentation/doc-diff to verify, though.\n\ndoc-diff looks good.\n\nI suspect these were identified by greping for \" --- \", spaces included.\nWe seem to have some \"---\" that aren't surrounded by spaces. They're\nperhaps a bit more tedious to find, but I see there are two in\ngitformat-signature.txt and technical/rerere.txt. Maybe it would be\nworthwhile addressing them too in this patch.\n\nMartin\n"},{"id":"470902","messageId":"20230123090114.429844-1-rybak.a.v@gmail.com","threadId":"59140","inReplyTo":"20230122165628.1601062-1-rybak.a.v@gmail.com","subject":"[PATCH v2] Documentation: render dash correctly","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-01-23T09:01:14Z","receivedAt":"2023-01-23T09:01:23Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"Three hyphens are rendered verbatim in documentation, so \"--\" has to be\nused to produce a dash.  Fix asciidoc output for dashes.  This is\nsimilar to previous commits f0b922473e (Documentation: render special\ncharacters correctly, 2021-07-29) and de82095a95 (doc\nhash-function-transition: fix asciidoc output, 2021-02-05).\n\nSigned-off-by: Andrei Rybak <rybak.a.v@gmail.com>\n---\n\nOn 2023-01-23T09:19, Martin Ågren wrote:\n> I suspect these were identified by greping for \" --- \", spaces included.\n\nIndeed.\n\n> We seem to have some \"---\" that aren't surrounded by spaces. They're\n> perhaps a bit more tedious to find,\n\nNot really:\n\n    git grep -P -i '[^-][a-z0-9]+---[a-z0-9]+[^-]' -- Documentation/\n\nThe \"[^-]\" part is needed to exclude many examples of commit graphs.\n\nThe following:\n\n    The horizontal line of history A---Q is taken to be the first parent of each\n    merge.\n\nalso comes up in 'Documentation/rev-list-options.txt', but it might be better to\nleave \"A---Q\" as is to be similar to the commit graph example above it (there\nare commits between A and Q in the graph, but still).\n\n> but I see there are two in\n> gitformat-signature.txt and technical/rerere.txt. Maybe it would be\n> worthwhile addressing them too in this patch.\n> \n> Martin\n\nThank you for review, here's v2.\n\nChanges from v1:\n\n - Added two fixes in gitformat-signature.txt and technical/rerere.txt, as\n   suggested by Martin Ågren.\n\n Documentation/git-apply.txt                          | 2 +-\n Documentation/git-read-tree.txt                      | 2 +-\n Documentation/git.txt                                | 2 +-\n Documentation/gitformat-signature.txt                | 2 +-\n Documentation/technical/hash-function-transition.txt | 2 +-\n Documentation/technical/rerere.txt                   | 2 +-\n 6 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 1d478cbe9b..5e16e6db7e 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -208,7 +208,7 @@ behavior:\n * `warn` outputs warnings for a few such errors, but applies the\n   patch as-is (default).\n * `fix` outputs warnings for a few such errors, and applies the\n-  patch after fixing them (`strip` is a synonym --- the tool\n+  patch after fixing them (`strip` is a synonym -- the tool\n   used to consider only trailing whitespace characters as errors, and the\n   fix involved 'stripping' them, but modern Gits do more).\n * `error` outputs warnings for a few such errors, and refuses\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 7567955bad..b09707474d 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -219,7 +219,7 @@ see which of the \"local changes\" that you made were carried forward by running\n `git diff-index --cached $M`.  Note that this does not\n necessarily match what `git diff-index --cached $H` would have\n produced before such a two tree merge.  This is because of cases\n-18 and 19 --- if you already had the changes in $M (e.g. maybe\n+18 and 19 -- if you already had the changes in $M (e.g. maybe\n you picked it up via e-mail in a patch form), `git diff-index\n --cached $H` would have told you about the change before this\n merge, but it would not show in `git diff-index --cached $M`\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex f9a7a4554c..74973d3cc4 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -613,7 +613,7 @@ The file parameters can point at the user's working file\n (e.g. `new-file` in \"git-diff-files\"), `/dev/null` (e.g. `old-file`\n when a new file is added), or a temporary file (e.g. `old-file` in the\n index).  `GIT_EXTERNAL_DIFF` should not worry about unlinking the\n-temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits.\n+temporary file -- it is removed when `GIT_EXTERNAL_DIFF` exits.\n +\n For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1\n parameter, <path>.\ndiff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.txt\nindex a249869faf..d8e3eb1bac 100644\n--- a/Documentation/gitformat-signature.txt\n+++ b/Documentation/gitformat-signature.txt\n@@ -37,7 +37,7 @@ line.\n This is even true for an originally empty line.  In the following\n examples, the end of line that ends with a whitespace letter is\n highlighted with a `$` sign; if you are trying to recreate these\n-example by hand, do not cut and paste them---they are there\n+example by hand, do not cut and paste them--they are there\n primarily to highlight extra whitespace at the end of some lines.\n \n The signed payload and the way the signature is embedded depends\ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex e2ac36dd21..ed57481089 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -562,7 +562,7 @@ hash re-encode during clone and to encourage peers to modernize.\n The design described here allows fetches by SHA-1 clients of a\n personal SHA-256 repository because it's not much more difficult than\n allowing pushes from that repository. This support needs to be guarded\n-by a configuration option --- servers like git.kernel.org that serve a\n+by a configuration option -- servers like git.kernel.org that serve a\n large number of clients would not be expected to bear that cost.\n \n Meaning of signatures\ndiff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.txt\nindex 35d4541433..be58f1bee3 100644\n--- a/Documentation/technical/rerere.txt\n+++ b/Documentation/technical/rerere.txt\n@@ -99,7 +99,7 @@ conflict to leave line D means that the user declares:\n     compatible with what AB and AC wanted to do.\n \n So the conflict we would see when merging AB into ACAB should be\n-resolved the same way---it is the resolution that is in line with that\n+resolved the same way--it is the resolution that is in line with that\n declaration.\n \n Imagine that similarly previously a branch XYXZ was forked from XY,\n-- \n2.39.0\n\n"},{"id":"470905","messageId":"CAN0heSogz0cdhVJdiZhCc2_fcHzJggPjbS0wCAQkRh1uZMxLig@mail.gmail.com","threadId":"59140","inReplyTo":"20230123090114.429844-1-rybak.a.v@gmail.com","subject":"Re: [PATCH v2] Documentation: render dash correctly","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-01-23T11:04:21Z","receivedAt":"2023-01-23T11:04:36Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:\n\n>  highlighted with a `$` sign; if you are trying to recreate these\n> -example by hand, do not cut and paste them---they are there\n> +example by hand, do not cut and paste them--they are there\n>  primarily to highlight extra whitespace at the end of some lines.\n\nOK, so this is one of the new ones compared to v1. I can see the\nargument for adding some spaces around the \"--\" for consistency and to\nmake this a bit easier to read in the resulting manpage (which can of\ncourse be very subjective), but then I can also see that kind of change\nbeing left out as orthogonal to this patch.\n\nThis v2 patch looks good to me.\n\nMartin\n"},{"id":"470939","messageId":"xmqqzga9m9pp.fsf@gitster.g","threadId":"59140","inReplyTo":"CAN0heSogz0cdhVJdiZhCc2_fcHzJggPjbS0wCAQkRh1uZMxLig@mail.gmail.com","subject":"Re: [PATCH v2] Documentation: render dash correctly","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-01-23T17:39:30Z","receivedAt":"2023-01-23T17:39:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren <martin.agren@gmail.com> writes:\n\n> On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:\n>\n>>  highlighted with a `$` sign; if you are trying to recreate these\n>> -example by hand, do not cut and paste them---they are there\n>> +example by hand, do not cut and paste them--they are there\n>>  primarily to highlight extra whitespace at the end of some lines.\n>\n> OK, so this is one of the new ones compared to v1. I can see the\n> argument for adding some spaces around the \"--\" for consistency and to\n> make this a bit easier to read in the resulting manpage (which can of\n> course be very subjective), but then I can also see that kind of change\n> being left out as orthogonal to this patch.\n>\n> This v2 patch looks good to me.\n\nThanks, both.  Will queue.\n"},{"id":"470946","messageId":"e3f57ef0-7544-8f35-fd97-fdcbe1144e7e@gmail.com","threadId":"59140","inReplyTo":"CAN0heSogz0cdhVJdiZhCc2_fcHzJggPjbS0wCAQkRh1uZMxLig@mail.gmail.com","subject":"Re: [PATCH v2] Documentation: render dash correctly","fromName":"Andrei Rybak","fromEmail":"rybak.a.v@gmail.com","sentAt":"2023-01-23T18:52:16Z","receivedAt":"2023-01-23T18:52:24Z","isPatch":true,"sender":{"key":"rybak.a.v@gmail.com","avatar":"https://avatars.githubusercontent.com/u/624072?v=4"},"body":"On 23/01/2023 12:04, Martin Ågren wrote:\n> On Mon, 23 Jan 2023 at 10:01, Andrei Rybak <rybak.a.v@gmail.com> wrote:\n> \n>>   highlighted with a `$` sign; if you are trying to recreate these\n>> -example by hand, do not cut and paste them---they are there\n>> +example by hand, do not cut and paste them--they are there\n>>   primarily to highlight extra whitespace at the end of some lines.\n> \n> OK, so this is one of the new ones compared to v1. I can see the\n> argument for adding some spaces around the \"--\" for consistency and to\n> make this a bit easier to read in the resulting manpage (which can of\n> course be very subjective), but then I can also see that kind of change\n\nThere are some less subjective guidelines.  Asciidoc turns \"--\" into an\nem-dash.[1]  In English, em-dash is almost always not surrounded by\nspaces (it is in French, for example), while en-dash is spaced in\nEnglish when used instead of an em-dash.[2][3][4]\n\nThis means that it's all the other places that use \" -- \" with spaces\nthat are incorrect.\n\nReferences:\n\n1. https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#text-replacements\n\n2. English Wikipedia is clear about its usage of en- and em-dashes:\n    https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Dashes\n\n3. Chicago Manual of Style FAQ doesn't spell out the spacing, but it's\n    clear from examples:\n    https://www.chicagomanualofstyle.org/qanda/data/faq/topics/HyphensEnDashesEmDashes/faq0002.html\n\n4. More confirmation on English Language and Usage Q&A website on Stack\n    Exchange network: https://english.stackexchange.com/a/154998/54197\n\n> being left out as orthogonal to this patch.\n\nIndeed, correcting spacing around dashes is orthogonal.  Also, it might\nnot be very desirable to have so much churn for spacing issues.\n  \n> This v2 patch looks good to me.\n\nThank you for review.\n  \n> Martin\n\n"}]}