{"thread":{"id":"55164","subject":"[PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph","startedAt":"2021-02-17T19:57:22Z","lastAt":"2021-02-19T06:34:31Z","messageCount":12,"participants":["Martin Ågren","Junio C Hamano","Chris Torek","Patrick Steinhardt","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"417200","messageId":"888eca4c3544864fbe222de43b50d4fa25700fea.1613590761.git.martin.agren@gmail.com","threadId":"55164","inReplyTo":"cover.1613590761.git.martin.agren@gmail.com","subject":"[PATCH 1/3] rev-list-options.txt: fix rendering of bonus paragraph","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-17T19:56:04Z","receivedAt":"2021-02-17T19:57:22Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"In git-log(1) -- but not in git-shortlog(1) or git-rev-list(1) -- we\ninclude a bonus paragraph in the description of `--first-parent`. But\nwe forgot to add a lone \"+\" for a list continuation, and we shouldn't\nbe indenting this second paragraph. As a result, we get a different\nindentation and the `backticks` render literally.\n\nSigned-off-by: Martin Ågren \n---\n doc-diff:\n --- a/.../man/man1/git-log.1\n +++ b/.../man/man1/git-log.1\n @@ -264,8 +264,8 @@ OPTIONS\n time, and this option allows you to ignore the individual commits\n brought in to your history by such a merge.\n\n - This option also changes default diff format for merge commits\n - to `first-parent`, see `--diff-merges=first-parent` for details.\n + This option also changes default diff format for merge commits to\n + first-parent, see --diff-merges=first-parent for details.\n\n --not\n Reverses the meaning of the ^ prefix (or lack thereof) for all\n\n Documentation/rev-list-options.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 96cc89d157..2fa1629f1e 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -129,10 +129,10 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).\n \tadjusting to updated upstream from time to time, and\n \tthis option allows you to ignore the individual commits\n \tbrought in to your history by such a merge.\n-\n ifdef::git-log[]\n-\tThis option also changes default diff format for merge commits\n-\tto `first-parent`, see `--diff-merges=first-parent` for details.\n++\n+This option also changes default diff format for merge commits\n+to `first-parent`, see `--diff-merges=first-parent` for details.\n endif::git-log[]\n \n --not::\n-- \n2.30.0.284.gd98b1dd5ea\n\n"},{"id":"417201","messageId":"cover.1613590761.git.martin.agren@gmail.com","threadId":"55164","inReplyTo":null,"subject":"[PATCH 0/3] fix some doc rendering issues since v2.30.0","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-17T19:56:03Z","receivedAt":"2021-02-17T19:57:22Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"These three patches fix some rendering issues I came across in the\noutput of\n\n ./doc-diff v2.30.0 master\n\nThe original topics are so/log-diff-merge, ps/config-env-pairs and\nab/mailmap.\n\nMartin Ågren (3):\n rev-list-options.txt: fix rendering of bonus paragraph\n git.txt: fix monospace rendering\n gitmailmap.txt: fix rendering of e-mail addresses\n\n Documentation/git.txt | 2 +-\n Documentation/gitmailmap.txt | 8 ++++----\n Documentation/rev-list-options.txt | 6 +++---\n 3 files changed, 8 insertions(+), 8 deletions(-)\n\n-- \n2.30.0.284.gd98b1dd5ea\n\n"},{"id":"417202","messageId":"97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6.1613590761.git.martin.agren@gmail.com","threadId":"55164","inReplyTo":"cover.1613590761.git.martin.agren@gmail.com","subject":"[PATCH 2/3] git.txt: fix monospace rendering","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-17T19:56:05Z","receivedAt":"2021-02-17T19:57:22Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"When we write ``s with the \"s\" tucked on to the closing backtick,\nwe end up rendering the backticks literally. Rephrase this sentence\nslightly to render this as monospace.\n\nSigned-off-by: Martin Ågren \n---\n doc-diff:\n --- a/.../man/man1/git.1\n +++ b/.../man/man1/git.1\n @@ -77,8 +77,8 @@ OPTIONS\n setting the value to an empty string, instead the environment\n variable itself must be set to the empty string. It is an error if\n the does not exist in the environment. may not\n - contain an equals sign to avoid ambiguity with ``s which\n - contain one.\n + contain an equals sign to avoid ambiguity with containing\n + one.\n \n This is useful for cases where you want to pass transitory\n configuration options to git, but are doing so on OS’s where other\n Documentation/git.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex d36e6fd482..3a9c44987f 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n \tempty string, instead the environment variable itself must be\n \tset to the empty string. It is an error if the `` does not exist\n \tin the environment. `` may not contain an equals sign\n-\tto avoid ambiguity with ``s which contain one.\n+\tto avoid ambiguity with `` containing one.\n +\n This is useful for cases where you want to pass transitory\n configuration options to git, but are doing so on OS's where\n-- \n2.30.0.284.gd98b1dd5ea\n\n"},{"id":"417203","messageId":"ee0422ac399daf43a7adcc2b662b50312da04631.1613590761.git.martin.agren@gmail.com","threadId":"55164","inReplyTo":"cover.1613590761.git.martin.agren@gmail.com","subject":"[PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-17T19:56:06Z","receivedAt":"2021-02-17T19:57:22Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Both AsciiDoc and Asciidoctor are eager to pick up the e-mail addresses\nin this document and turn them into references at the bottom of the\nmanpage / clickable links. We don't really need that for these dummy\naddresses. Spell \"@\" as \"@\" to make them not do this. In the open\nblock, we can instead avoid this by indenting the contents, similar to\nthe earlier blocks.\n\nFix a backtick which should have been a single quote mark. With all the\nquoting that is going on around here, this mistake trips up the parsing\nand rendering quite a bit.\n\nBefore this commit, we have the same failure mode with AsciiDoc 8.6.10\nand Asciidoctor 1.5.5, and this change makes both of them happy.\n\nSigned-off-by: Martin Ågren \n---\n doc-diff:\n --- a/97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6-asciidoctor-cut-footer/home/martin/share/man/man5/gitmailmap.5\n +++ b/ee0422ac399daf43a7adcc2b662b50312da04631-asciidoctor-cut-footer/home/martin/share/man/man5/gitmailmap.5\n @@ -40,9 +40,9 @@ SYNTAX\n matching both the specified commit name and email address.\n \n Both E-Mails and names are matched case-insensitively. For example this\n - would also match the Commit Name above:\n + would also match the Commit Name above:\n \n - Proper Name CoMmIt NaMe \n + Proper Name CoMmIt NaMe \n \n EXAMPLES\n Your history contains commits by two authors, Jane and Joe, whose names\n @@ -62,11 +62,10 @@ EXAMPLES\n Jane Doe \n Jane Doe \n \n - Note that there’s no need to map the name for jane@laptop.(none) to\n + Note that there’s no need to map the name for to\n only correct the names. However, leaving the obviously broken\n - ' and '' E-Mails as-is is\n - usually not what you want. A `.mailmap file which also corrects those\n - is:\n + and E-Mails as-is is usually\n + not what you want. A .mailmap file which also corrects those is:\n \n Joe R. Developer \n Jane Doe \n @@ -93,13 +92,3 @@ SEE ALSO\n \n GIT\n Part of the git(1) suite\n -\n -NOTES\n - 1. commit@email.xx\n - mailto:commit@email.xx\n -\n - 2. proper@email.xx\n - mailto:proper@email.xx\n -\n - 3. CoMmIt@EmAiL.xX\n - mailto:CoMmIt@EmAiL.xX\n Documentation/gitmailmap.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt\nindex 052209b33b..3fb39f801f 100644\n--- a/Documentation/gitmailmap.txt\n+++ b/Documentation/gitmailmap.txt\n@@ -50,9 +50,9 @@ which allows mailmap to replace both the name and the email of a\n commit matching both the specified commit name and email address.\n \n Both E-Mails and names are matched case-insensitively. For example\n-this would also match the 'Commit Name ' above:\n+this would also match the 'Commit Name ' above:\n --\n-Proper Name CoMmIt NaMe \n+\tProper Name CoMmIt NaMe \n --\n \n EXAMPLES\n@@ -79,9 +79,9 @@ Jane Doe \n Jane Doe \n ------------\n \n-Note that there's no need to map the name for 'jane@laptop.(none)' to\n+Note that there's no need to map the name for '' to\n only correct the names. However, leaving the obviously broken\n-`' and '' E-Mails as-is is\n+'' and '' E-Mails as-is is\n usually not what you want. A `.mailmap` file which also corrects those\n is:\n \n-- \n2.30.0.284.gd98b1dd5ea\n\n"},{"id":"417223","messageId":"xmqqeehejsot.fsf@gitster.g","threadId":"55164","inReplyTo":"cover.1613590761.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/3] fix some doc rendering issues since v2.30.0","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-17T21:22:10Z","receivedAt":"2021-02-17T21:23:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> These three patches fix some rendering issues I came across in the\n> output of\n>\n> ./doc-diff v2.30.0 master\n>\n> The original topics are so/log-diff-merge, ps/config-env-pairs and\n> ab/mailmap.\n>\n> Martin Ågren (3):\n> rev-list-options.txt: fix rendering of bonus paragraph\n> git.txt: fix monospace rendering\n> gitmailmap.txt: fix rendering of e-mail addresses\n>\n> Documentation/git.txt | 2 +-\n> Documentation/gitmailmap.txt | 8 ++++----\n> Documentation/rev-list-options.txt | 6 +++---\n> 3 files changed, 8 insertions(+), 8 deletions(-)\n\nAll of them look \"obviously correct\". Thanks.\n"},{"id":"417240","messageId":"CAPx1GvdcFGmAi_zJ9H0+40uZw49qhTs8C_afnMMVj32EFJXqBQ@mail.gmail.com","threadId":"55164","inReplyTo":"97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6.1613590761.git.martin.agren@gmail.com","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Chris Torek","fromEmail":"chris.torek@gmail.com","sentAt":"2021-02-17T22:47:34Z","receivedAt":"2021-02-17T22:49:22Z","isPatch":true,"sender":{"key":"chris.torek@gmail.com","avatar":"https://avatars.githubusercontent.com/u/16826774?v=4"},"body":"On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren wrote:\n>\n> When we write ``s with the \"s\" tucked on to the closing backtick,\n> we end up rendering the backticks literally. Rephrase this sentence\n> slightly to render this as monospace.\n\nThat seems fine, but one question (diff trimmed way down to\nmake it clearer I hope):\n\n> + contain an equals sign to avoid ambiguity with containing\n\n> + to avoid ambiguity with `` containing one.\n\nOne replacement drops the backquotes entirely. The other keeps\nthem. Surely these two shouldn't be *different*...?\n\nChris\n"},{"id":"417284","messageId":"YC4I20bQ0jeNLO+M@ncase","threadId":"55164","inReplyTo":"97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6.1613590761.git.martin.agren@gmail.com","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2021-02-18T06:27:39Z","receivedAt":"2021-02-18T06:35:13Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Feb 17, 2021 at 08:56:05PM +0100, Martin Ågren wrote:\n> When we write ``s with the \"s\" tucked on to the closing backtick,\n> we end up rendering the backticks literally. Rephrase this sentence\n> slightly to render this as monospace.\n> \n> Signed-off-by: Martin Ågren \n> ---\n> doc-diff:\n> --- a/.../man/man1/git.1\n> +++ b/.../man/man1/git.1\n> @@ -77,8 +77,8 @@ OPTIONS\n> setting the value to an empty string, instead the environment\n> variable itself must be set to the empty string. It is an error if\n> the does not exist in the environment. may not\n> - contain an equals sign to avoid ambiguity with ``s which\n> - contain one.\n> + contain an equals sign to avoid ambiguity with containing\n> + one.\n\nOver here you're also dropping the backticks, while...\n\n> This is useful for cases where you want to pass transitory\n> configuration options to git, but are doing so on OS’s where other\n> Documentation/git.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index d36e6fd482..3a9c44987f 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> \tempty string, instead the environment variable itself must be\n> \tset to the empty string. It is an error if the `` does not exist\n> \tin the environment. `` may not contain an equals sign\n> -\tto avoid ambiguity with ``s which contain one.\n> +\tto avoid ambiguity with `` containing one.\n\n... here you don't. Is this on purpose?\n\nPatrick\n\n> This is useful for cases where you want to pass transitory\n> configuration options to git, but are doing so on OS's where\n> -- \n> 2.30.0.284.gd98b1dd5ea\n> \n"},{"id":"417285","messageId":"CAN0heSoZJgdKHmWcm3BF2-eWtWMPvSf9YSsKuE7+PaBY4LMKtA@mail.gmail.com","threadId":"55164","inReplyTo":"CAPx1GvdcFGmAi_zJ9H0+40uZw49qhTs8C_afnMMVj32EFJXqBQ@mail.gmail.com","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-18T06:28:29Z","receivedAt":"2021-02-18T06:38:31Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Wed, 17 Feb 2021 at 23:47, Chris Torek wrote:\n>\n> On Wed, Feb 17, 2021 at 1:21 PM Martin Ågren wrote:\n> >\n> > When we write ``s with the \"s\" tucked on to the closing backtick,\n> > we end up rendering the backticks literally. Rephrase this sentence\n> > slightly to render this as monospace.\n>\n> That seems fine, but one question (diff trimmed way down to\n> make it clearer I hope):\n>\n> > + contain an equals sign to avoid ambiguity with containing\n>\n> > + to avoid ambiguity with `` containing one.\n>\n> One replacement drops the backquotes entirely. The other keeps\n> them. Surely these two shouldn't be *different*...?\n\nI included the output of our \"doc-diff\" script below the double-dash\nline. The patch applies just as fine anyway, but I did wonder if it\nwould trip up human readers. :-/\n\nQuoting my original, slightly less trimmed:\n\nOn Wed, 17 Feb 2021 at 20:56, Martin Ågren wrote:\n> doc-diff:\n> --- a/.../man/man1/git.1\n> +++ b/.../man/man1/git.1\n> - contain an equals sign to avoid ambiguity with ``s which\n> - contain one.\n> + contain an equals sign to avoid ambiguity with containing\n> + one.\n\nSo that's how the rendering is changed. From \"oops, we rendered the\nbackticks literally\" to \"we no longer do\". (It's not clear from the\ndoc-diff that they're rendered monospace/bold, but at least this is no\nlonger obviously broken.)\n\n(Note the extra indentation of all of that. This is where one might\nplace some commentary that one don't want to burden the commit message\nwith, but which also isn't part of the actual diff. Now that this looks\nvery much like a diff, I can see how it's confusing.)\n\nAnd that's because of this change to the actual sources:\n\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index d36e6fd482..3a9c44987f 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> - to avoid ambiguity with ``s which contain one.\n> + to avoid ambiguity with `` containing one.\n\nI hope that clarifies it? It's a bit unfortunate that the misrendering\nis so similar to the source in the txt file. But I guess that's still\nbetter than some of those misrenderings where some cogwheel slips and\neverything spins out of control through the rest of the paragraph.\n\nMartin\n"},{"id":"417286","messageId":"CAN0heSqn+b70tPJjigeKj4cDE=YW7vSDyZLrmP02qZd0tN8PCw@mail.gmail.com","threadId":"55164","inReplyTo":"YC4I20bQ0jeNLO+M@ncase","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-18T06:32:46Z","receivedAt":"2021-02-18T06:40:21Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 18 Feb 2021 at 07:27, Patrick Steinhardt wrote:\n>\n> On Wed, Feb 17, 2021 at 08:56:05PM +0100, Martin Ågren wrote:\n> > When we write ``s with the \"s\" tucked on to the closing backtick,\n> > we end up rendering the backticks literally. Rephrase this sentence\n> > slightly to render this as monospace.\n> >\n> > Signed-off-by: Martin Ågren \n> > ---\n> > doc-diff:\n> > --- a/.../man/man1/git.1\n> > +++ b/.../man/man1/git.1\n> > @@ -77,8 +77,8 @@ OPTIONS\n> > setting the value to an empty string, instead the environment\n> > variable itself must be set to the empty string. It is an error if\n> > the does not exist in the environment. may not\n> > - contain an equals sign to avoid ambiguity with ``s which\n> > - contain one.\n> > + contain an equals sign to avoid ambiguity with containing\n> > + one.\n>\n> Over here you're also dropping the backticks, while...\n>\n> > This is useful for cases where you want to pass transitory\n> > configuration options to git, but are doing so on OS’s where other\n> > Documentation/git.txt | 2 +-\n> > 1 file changed, 1 insertion(+), 1 deletion(-)\n> >\n> > diff --git a/Documentation/git.txt b/Documentation/git.txt\n> > index d36e6fd482..3a9c44987f 100644\n> > --- a/Documentation/git.txt\n> > +++ b/Documentation/git.txt\n> > @@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> > empty string, instead the environment variable itself must be\n> > set to the empty string. It is an error if the `` does not exist\n> > in the environment. `` may not contain an equals sign\n> > - to avoid ambiguity with ``s which contain one.\n> > + to avoid ambiguity with `` containing one.\n>\n> ... here you don't. Is this on purpose?\n\nYour mail crossed with my response to Chris, who had the same question.\nI'd post a link to lore.kernel.org, but it seems my response hasn't\nreached it yet. The short answer is the first diff is an indented diff\nof the rendered manpages (our \"doc-diff\" script), whereas the second\ndiff is the actual, to-be-applied diff.\n\nI thought it would be helpful to include the doc-diff, but it seems it\njust created more confusion than it avoided. I'll try to avoid that. :-)\n\nThanks\nMartin\n"},{"id":"417294","messageId":"87tuq98xd9.fsf@evledraar.gmail.com","threadId":"55164","inReplyTo":"ee0422ac399daf43a7adcc2b662b50312da04631.1613590761.git.martin.agren@gmail.com","subject":"Re: [PATCH 3/3] gitmailmap.txt: fix rendering of e-mail addresses","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-02-18T10:48:50Z","receivedAt":"2021-02-18T12:26:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Feb 17 2021, Martin Ågren wrote:\n\n> Both AsciiDoc and Asciidoctor are eager to pick up the e-mail addresses\n> in this document and turn them into references at the bottom of the\n> manpage / clickable links. We don't really need that for these dummy\n> addresses. Spell \"@\" as \"@\" to make them not do this. In the open\n> block, we can instead avoid this by indenting the contents, similar to\n> the earlier blocks.\n>\n> Fix a backtick which should have been a single quote mark. With all the\n> quoting that is going on around here, this mistake trips up the parsing\n> and rendering quite a bit.\n>\n> Before this commit, we have the same failure mode with AsciiDoc 8.6.10\n> and Asciidoctor 1.5.5, and this change makes both of them happy.\n\nTHanks a lot for the fix & cleaning up my mess. This LGTM.\n"},{"id":"417336","messageId":"xmqqim6pgqev.fsf@gitster.g","threadId":"55164","inReplyTo":"97c686dd7ba1bbd1c0be6f7f61a3a033adf8adb6.1613590761.git.martin.agren@gmail.com","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-18T18:51:52Z","receivedAt":"2021-02-18T19:32:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> When we write ``s with the \"s\" tucked on to the closing backtick,\n> we end up rendering the backticks literally. Rephrase this sentence\n> slightly to render this as monospace.\n>\n> Signed-off-by: Martin Ågren \n> ---\n> doc-diff:\n> --- a/.../man/man1/git.1\n> +++ b/.../man/man1/git.1\n> @@ -77,8 +77,8 @@ OPTIONS\n> setting the value to an empty string, instead the environment\n> variable itself must be set to the empty string. It is an error if\n> the does not exist in the environment. may not\n> - contain an equals sign to avoid ambiguity with ``s which\n> - contain one.\n> + contain an equals sign to avoid ambiguity with containing\n> + one.\n> \n> This is useful for cases where you want to pass transitory\n> configuration options to git, but are doing so on OS’s where other\n> Documentation/git.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git.txt b/Documentation/git.txt\n> index d36e6fd482..3a9c44987f 100644\n> --- a/Documentation/git.txt\n> +++ b/Documentation/git.txt\n> @@ -88,7 +88,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config\n> \tempty string, instead the environment variable itself must be\n> \tset to the empty string. It is an error if the `` does not exist\n> \tin the environment. `` may not contain an equals sign\n> -\tto avoid ambiguity with ``s which contain one.\n> +\tto avoid ambiguity with `` containing one.\n> +\n> This is useful for cases where you want to pass transitory\n> configuration options to git, but are doing so on OS's where\n\nThe \"two\" diffs may indeed be misleading.\n\nThe patch only changes one source and the \"supporting material\" is\nnot something that we need to use on the source file---it is only\nshowing the change in the output.\n\nI did appreciate the inclusion of doc-diff myself, but it seems that\nit confused Chris and Patrick. I doubt that it is an improvement to\nomit doc-diff. We may want to find a way to make it easier for the\nreaders to tell which part is the patch to be applied and which part\nis not in similar changes we discuss on the list in the future, and\napparently, a one column indentation alone was not quite sufficient\nin this case. Replacing \"doc-diff:\" label and patch header lines up\nto the hunk header with a prose to explain what the intended diff is\nmay have helped, e.g.\n\n\n...\nslightly to render this as monospace.\n\nSigned-off-by: A U Thor \n---\n\n The rendered output changes like the following excerpt from\n doc-diff output.\n\n .... may not\n - contain an equals sign to avoid ambiguity with ``s which\n - contain one.\n + contain an equals sign to avoid ambiguity with containing\n + one.\n\n You can see that backquotes are gone, even though you unfortunately\n cannot see how is typeset (it is in monospace--trust me ;-).\n\n Documentation/git.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/.... \nindex ....\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ ...\n"},{"id":"417388","messageId":"CAN0heSp_Jc6x-xNqt4uSPHi17GwuVtcOEStxe66MAD-6h1cyhg@mail.gmail.com","threadId":"55164","inReplyTo":"xmqqim6pgqev.fsf@gitster.g","subject":"Re: [PATCH 2/3] git.txt: fix monospace rendering","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-02-19T06:33:22Z","receivedAt":"2021-02-19T06:34:31Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 18 Feb 2021 at 19:51, Junio C Hamano wrote:\n>\n> The \"two\" diffs may indeed be misleading.\n>\n> The patch only changes one source and the \"supporting material\" is\n> not something that we need to use on the source file---it is only\n> showing the change in the output.\n>\n> I did appreciate the inclusion of doc-diff myself, but it seems that\n> it confused Chris and Patrick. I doubt that it is an improvement to\n> omit doc-diff. We may want to find a way to make it easier for the\n> readers to tell which part is the patch to be applied and which part\n> is not in similar changes we discuss on the list in the future, and\n> apparently, a one column indentation alone was not quite sufficient\n> in this case. Replacing \"doc-diff:\" label and patch header lines up\n> to the hunk header with a prose to explain what the intended diff is\n> may have helped, e.g.\n\nGlad to know you found the included doc-diff useful. Thanks for the\nsuggestion on how to present it. Next time I'll try wrapping the\ndoc-diff in English prose to make it stand out more. The \"doc-diff:\" I\nused now was definitely a bit too subtle.\n\nThanks\nMartin\n"}]}