{"thread":{"id":"59615","subject":"[PATCH 0/2] doc: git-checkout: trivial style improvements","startedAt":"2023-04-18T07:00:54Z","lastAt":"2023-05-03T17:44:18Z","messageCount":15,"participants":["Felipe Contreras","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"475592","messageId":"20230418070048.2209469-1-felipe.contreras@gmail.com","threadId":"59615","inReplyTo":null,"subject":"[PATCH 0/2] doc: git-checkout: trivial style improvements","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-18T07:00:46Z","receivedAt":"2023-04-18T07:00:54Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There is a formatting issue discussed in [1] that is readily apparent in\nmanpages after removing one of our hacks, but it's also present in HTML\ndocumentation generated by asciidoc-py.\n\nThis series fixes that issue and cleans up our use of callouts.\n\n[1] https://lore.kernel.org/git/20230418061713.GA169940@coredump.intra.peff.net/T/\n\nFelipe Contreras (2):\n  doc: git-checkout: trivial callout cleanup\n  doc: git-checkout: reorganize examples\n\n Documentation/git-checkout.txt | 54 ++++++++++++++++++----------------\n 1 file changed, 28 insertions(+), 26 deletions(-)\n\n-- \n2.40.0+fc1\n\n"},{"id":"475593","messageId":"20230418070048.2209469-2-felipe.contreras@gmail.com","threadId":"59615","inReplyTo":"20230418070048.2209469-1-felipe.contreras@gmail.com","subject":"[PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-18T07:00:47Z","receivedAt":"2023-04-18T07:00:57Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The callouts are directly tied to the listing above, remove spaces to\nmake it clear they are one and the same.\n\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-checkout.txt | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 6bb32ab460..8ddeec63dd 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -483,14 +483,11 @@ $ git checkout -b foo  # or \"git switch -c foo\"  <1>\n $ git branch foo                                 <2>\n $ git tag foo                                    <3>\n ------------\n-\n <1> creates a new branch `foo`, which refers to commit `f`, and then\n     updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n     be in detached `HEAD` state after this command.\n-\n <2> similarly creates a new branch `foo`, which refers to commit `f`,\n     but leaves `HEAD` detached.\n-\n <3> creates a new tag `foo`, which refers to commit `f`,\n     leaving `HEAD` detached.\n \n@@ -529,7 +526,6 @@ $ git checkout master~2 Makefile  <2>\n $ rm -f hello.c\n $ git checkout hello.c            <3>\n ------------\n-+\n <1> switch branch\n <2> take a file out of another commit\n <3> restore `hello.c` from the index\n-- \n2.40.0+fc1\n\n"},{"id":"475594","messageId":"20230418070048.2209469-3-felipe.contreras@gmail.com","threadId":"59615","inReplyTo":"20230418070048.2209469-1-felipe.contreras@gmail.com","subject":"[PATCH 2/2] doc: git-checkout: reorganize examples","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-18T07:00:48Z","receivedAt":"2023-04-18T07:01:03Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The examples are an ordered list, however, they are complex enough that\na callout is inside example 1, and that confuses the parsers as the list\ncontinuation (`+`) is unclear (are we continuing the previous list item,\nor the previous callout?).\n\nWe could use an open block as the asciidoctor documentation suggests,\nbut that has a tiny formatting issue (a newline is missing).\n\nTo simplify things for everyone (the reader, the writer, and the parser)\nlet's use subsections.\n\nAfter this change, the HTML documentation generated with asciidoc has\nthe right indentation.\n\nCc: Jeff King <peff@peff.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/git-checkout.txt | 50 +++++++++++++++++++---------------\n 1 file changed, 28 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 8ddeec63dd..4af0904f47 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -516,10 +516,12 @@ to checkout these paths out of the index.\n EXAMPLES\n --------\n \n-. The following sequence checks out the `master` branch, reverts\n-  the `Makefile` to two revisions back, deletes `hello.c` by\n-  mistake, and gets it back from the index.\n-+\n+=== 1. Paths\n+\n+The following sequence checks out the `master` branch, reverts\n+the `Makefile` to two revisions back, deletes `hello.c` by\n+mistake, and gets it back from the index.\n+\n ------------\n $ git checkout master             <1>\n $ git checkout master~2 Makefile  <2>\n@@ -529,70 +531,74 @@ $ git checkout hello.c            <3>\n <1> switch branch\n <2> take a file out of another commit\n <3> restore `hello.c` from the index\n-+\n+\n If you want to check out _all_ C source files out of the index,\n you can say\n-+\n+\n ------------\n $ git checkout -- '*.c'\n ------------\n-+\n+\n Note the quotes around `*.c`.  The file `hello.c` will also be\n checked out, even though it is no longer in the working tree,\n because the file globbing is used to match entries in the index\n (not in the working tree by the shell).\n-+\n+\n If you have an unfortunate branch that is named `hello.c`, this\n step would be confused as an instruction to switch to that branch.\n You should instead write:\n-+\n+\n ------------\n $ git checkout -- hello.c\n ------------\n \n-. After working in the wrong branch, switching to the correct\n-  branch would be done using:\n-+\n+=== 2. Merge\n+\n+After working in the wrong branch, switching to the correct\n+branch would be done using:\n+\n ------------\n $ git checkout mytopic\n ------------\n-+\n+\n However, your \"wrong\" branch and correct `mytopic` branch may\n differ in files that you have modified locally, in which case\n the above checkout would fail like this:\n-+\n+\n ------------\n $ git checkout mytopic\n error: You have local changes to 'frotz'; not switching branches.\n ------------\n-+\n+\n You can give the `-m` flag to the command, which would try a\n three-way merge:\n-+\n+\n ------------\n $ git checkout -m mytopic\n Auto-merging frotz\n ------------\n-+\n+\n After this three-way merge, the local modifications are _not_\n registered in your index file, so `git diff` would show you what\n changes you made since the tip of the new branch.\n \n-. When a merge conflict happens during switching branches with\n-  the `-m` option, you would see something like this:\n-+\n+=== 3. Merge conflict\n+\n+When a merge conflict happens during switching branches with\n+the `-m` option, you would see something like this:\n+\n ------------\n $ git checkout -m mytopic\n Auto-merging frotz\n ERROR: Merge conflict in frotz\n fatal: merge program failed\n ------------\n-+\n+\n At this point, `git diff` shows the changes cleanly merged as in\n the previous example, as well as the changes in the conflicted\n files.  Edit and resolve the conflict and mark it resolved with\n `git add` as usual:\n-+\n+\n ------------\n $ edit frotz\n $ git add frotz\n-- \n2.40.0+fc1\n\n"},{"id":"475710","messageId":"xmqq8ren8xz1.fsf@gitster.g","threadId":"59615","inReplyTo":"20230418070048.2209469-2-felipe.contreras@gmail.com","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-19T19:37:38Z","receivedAt":"2023-04-19T19:37:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> The callouts are directly tied to the listing above, remove spaces to\n> make it clear they are one and the same.\n>\n> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n> ---\n>  Documentation/git-checkout.txt | 4 ----\n>  1 file changed, 4 deletions(-)\n\nI tried to format git-checkout.1 and git-checkout.html from HEAD and\nHEAD^ after applying this step, with asciidoc and asciidoctor, and\ndid not see any difference that came from this patch.  Am I correct\nto understand that this patch is done purely for the benefit of\nhuman readers, and not for formatting machinery?\n\nIt may be subjective for those who read the source if it is easier\nto read with or without inter-paragraph spaces, but in any case, the\nresulting source material now look the same way between two hunks,\nand consistency is good.\n\nQueued.  Thanks.\n\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 6bb32ab460..8ddeec63dd 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -483,14 +483,11 @@ $ git checkout -b foo  # or \"git switch -c foo\"  <1>\n>  $ git branch foo                                 <2>\n>  $ git tag foo                                    <3>\n>  ------------\n> -\n>  <1> creates a new branch `foo`, which refers to commit `f`, and then\n>      updates `HEAD` to refer to branch `foo`. In other words, we'll no longer\n>      be in detached `HEAD` state after this command.\n> -\n>  <2> similarly creates a new branch `foo`, which refers to commit `f`,\n>      but leaves `HEAD` detached.\n> -\n>  <3> creates a new tag `foo`, which refers to commit `f`,\n>      leaving `HEAD` detached.\n>  \n> @@ -529,7 +526,6 @@ $ git checkout master~2 Makefile  <2>\n>  $ rm -f hello.c\n>  $ git checkout hello.c            <3>\n>  ------------\n> -+\n>  <1> switch branch\n>  <2> take a file out of another commit\n>  <3> restore `hello.c` from the index\n"},{"id":"475711","messageId":"xmqq4jpb8xyl.fsf@gitster.g","threadId":"59615","inReplyTo":"20230418070048.2209469-3-felipe.contreras@gmail.com","subject":"Re: [PATCH 2/2] doc: git-checkout: reorganize examples","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-19T19:37:54Z","receivedAt":"2023-04-19T19:37:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> To simplify things for everyone (the reader, the writer, and the parser)\n> let's use subsections.\n\nMakes sense.  Queued.  Thanks.\n"},{"id":"475913","messageId":"644684018a766_aba29424@chronos.notmuch","threadId":"59615","inReplyTo":"xmqq8ren8xz1.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-24T13:28:33Z","receivedAt":"2023-04-24T13:29:05Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > The callouts are directly tied to the listing above, remove spaces to\n> > make it clear they are one and the same.\n> >\n> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n> > ---\n> >  Documentation/git-checkout.txt | 4 ----\n> >  1 file changed, 4 deletions(-)\n> \n> I tried to format git-checkout.1 and git-checkout.html from HEAD and\n> HEAD^ after applying this step, with asciidoc and asciidoctor, and\n> did not see any difference that came from this patch.  Am I correct\n> to understand that this patch is done purely for the benefit of\n> human readers, and not for formatting machinery?\n\nNo, it's for the formatting machinery.\n\nThe fact that both asciidoc and asciidoctor happen to understand our quircky\nformatting in this particualr situation doesn't mean it isn't quirky.\n\nIn this particular case the parsers do understand what we are trying to do,\nbecause we just just pepper list continuations (`+`) everywhere and it happens\nto work.\n\nThis works:\n\n  1. item\n  +\n  ----\n  line 1 <1>\n  ----\n  +\n  <1> callout 1\n\nBut if we used an open block instead (which is more propper), this does not:\n\n  1. item\n  +\n  --\n  ----\n  line 1 <1>\n  ----\n  +\n  <1> callout 1\n  --\n\nThis discrepancy confused Jeff in [1].\n\n[1] https://lore.kernel.org/git/20230418061713.GA169940@coredump.intra.peff.net/\n\n> It may be subjective for those who read the source if it is easier\n> to read with or without inter-paragraph spaces, but in any case, the\n> resulting source material now look the same way between two hunks,\n> and consistency is good.\n\nThat is an added benefit.\n\nIt's simply a good practice to follow the format asciidoctor documentation:\nwhich doesn't contain spaces, doesn't require adding list continations, it's\neasier to interpret by the parsers, and works inside open blocks.\n\n-- \nFelipe Contreras\n"},{"id":"475996","messageId":"xmqq8reg96cu.fsf@gitster.g","threadId":"59615","inReplyTo":"644684018a766_aba29424@chronos.notmuch","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-25T00:02:25Z","receivedAt":"2023-04-25T00:02:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> No, it's for the formatting machinery.\n>\n> The fact that both asciidoc and asciidoctor happen to understand our quircky\n> formatting in this particualr situation doesn't mean it isn't quirky.\n>\n> In this particular case the parsers do understand what we are trying to do,\n> because we just just pepper list continuations (`+`) everywhere and it happens\n> to work.\n\nI'll stop at pointing out that the first \"no\" sounds much stronger\nthan the text that tries to substantiate it, which says that the\nmachinery works fine without the changes.\n\n> This discrepancy confused Jeff in [1].\n\nAnd this is a good reason to add this change for humans.\n\n> It's simply a good practice to follow the format asciidoctor documentation:\n\nThat one I would agree with 100%.\n\nThanks.\n"},{"id":"476011","messageId":"20230425061029.GA4015844@coredump.intra.peff.net","threadId":"59615","inReplyTo":"xmqq8reg96cu.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-04-25T06:10:29Z","receivedAt":"2023-04-25T06:10:34Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Apr 24, 2023 at 05:02:25PM -0700, Junio C Hamano wrote:\n\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > No, it's for the formatting machinery.\n> >\n> > The fact that both asciidoc and asciidoctor happen to understand our quircky\n> > formatting in this particualr situation doesn't mean it isn't quirky.\n> >\n> > In this particular case the parsers do understand what we are trying to do,\n> > because we just just pepper list continuations (`+`) everywhere and it happens\n> > to work.\n> \n> I'll stop at pointing out that the first \"no\" sounds much stronger\n> than the text that tries to substantiate it, which says that the\n> machinery works fine without the changes.\n> \n> > This discrepancy confused Jeff in [1].\n> \n> And this is a good reason to add this change for humans.\n\nSince I'm being used as the example, I'd like to point that I think this\nis somewhat tangential to what actually confused me there.\n\nWhat confused me in that earlier message was that having \"+\" as the\ncontinuation between a code-block and its call-out list is odd, since\n\"+\" is about continuing a list item. It happens to work because we're in\na larger list item, but it breaks when you put the two of them in their\nown block (which is the part that got me).\n\nUsing just a blank line between the code block and the call-out list\n(instead of the \"+\") works for asciidoc (it is happy to keep the two\ntogether) but not asciidoctor (it ends the outer ordered list before\nstarting the callout list).\n\nSo the second hunk in the patch, to drop the extra continuation between\nthe code block and the callout, makes perfect sense to me.\n\nThe first hunk seems less obviously good to me. We're not part of a\nlist, so there's no continuation. We might say that it is good to always\nstick the callout list directly adjacent to the associated code block,\nsince it does matter in other cases. But dropping the blank lines\nbetween the paragraph-sized callout blocks makes the source less\nreadable, and empty lines between list elements are a pretty normal\nthing in asciidoc.\n\nThat said, I don't feel _too_ strongly about it, so I'm OK with the\npatch as-is.\n\n-Peff\n"},{"id":"476235","messageId":"644ae968769f2_7f4f2942d@chronos.notmuch","threadId":"59615","inReplyTo":"xmqq8reg96cu.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-27T21:30:16Z","receivedAt":"2023-04-27T21:30:22Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n> \n> > No, it's for the formatting machinery.\n> >\n> > The fact that both asciidoc and asciidoctor happen to understand our quircky\n> > formatting in this particualr situation doesn't mean it isn't quirky.\n> >\n> > In this particular case the parsers do understand what we are trying to do,\n> > because we just just pepper list continuations (`+`) everywhere and it happens\n> > to work.\n> \n> I'll stop at pointing out that the first \"no\" sounds much stronger\n> than the text that tries to substantiate it, which says that the\n> machinery works fine without the changes.\n\nThe question was if this patch was done *purely* for the benefit of human\nreaders:\n\n> > > Am I correct to understand that this patch is done purely for the benefit\n> > > of human readers, and not for formatting machinery?\n\nEven if the conclusion was that it was done primarily for the benefit of human\nreaders and secondarily for machine parsers (it shouldn't), that's still a\n\"no\".\n\n> > This discrepancy confused Jeff in [1].\n> \n> And this is a good reason to add this change for humans.\n> \n> > It's simply a good practice to follow the format asciidoctor documentation:\n> \n> That one I would agree with 100%.\n\n---\n\nTo draw a parallel with a situation the git dev community is much more familiar\nwith: we can think of asciidoc as the shell language. AsiiDoc is trying to be a\nspecified language [1], just like POSIX shell.\n\nThe fact that some syntax happens to work on all the *current* shells does not\nmean it is specified, and it does not mean that it must work on future shells.\n\nSimilarly, the fact some asciidoc syntax happens to work on the current\ntransformers doesn't mean it will work on all future ones. Moreover,\ntransformers are not the only consideration, as text editors trying to parse\nthe same text also matter.\n\nNot to mention blurry lines like human-like-machines like LLMs helping humans\nwith the code, and machine-like-humans because apparently the way I read the\nasciidoc code is different than my fellow humans (I'm thinking of how a parser\ncould interpret it).\n\nEither way, if the question was about *my* motivation for the patch, it was\njust consistency, which helps both humans and machines.\n\nCheers.\n\n[1] https://asciidoc-wg.eclipse.org/\n\n-- \nFelipe Contreras\n"},{"id":"476239","messageId":"644af29c8526c_7f4f2945f@chronos.notmuch","threadId":"59615","inReplyTo":"20230425061029.GA4015844@coredump.intra.peff.net","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-27T22:09:32Z","receivedAt":"2023-04-27T22:09:38Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Mon, Apr 24, 2023 at 05:02:25PM -0700, Junio C Hamano wrote:\n> \n> > Felipe Contreras <felipe.contreras@gmail.com> writes:\n> > \n> > > No, it's for the formatting machinery.\n> > >\n> > > The fact that both asciidoc and asciidoctor happen to understand our quircky\n> > > formatting in this particualr situation doesn't mean it isn't quirky.\n> > >\n> > > In this particular case the parsers do understand what we are trying to do,\n> > > because we just just pepper list continuations (`+`) everywhere and it happens\n> > > to work.\n> > \n> > I'll stop at pointing out that the first \"no\" sounds much stronger\n> > than the text that tries to substantiate it, which says that the\n> > machinery works fine without the changes.\n> > \n> > > This discrepancy confused Jeff in [1].\n> > \n> > And this is a good reason to add this change for humans.\n> \n> Since I'm being used as the example, I'd like to point that I think this\n> is somewhat tangential to what actually confused me there.\n> \n> What confused me in that earlier message was that having \"+\" as the\n> continuation between a code-block and its call-out list is odd, since\n> \"+\" is about continuing a list item.\n\nIndeed.\n\n> It happens to work because we're in a larger list item,\n\nNo, there's only one list item, but yes, it works when the callout is inside\none.\n\nThe `+` is continuing the list item the callout list is part of, it's not part\nof the callout.\n\n> but it breaks when you put the two of them in their own block (which is the\n> part that got me).\n\nYou only need to put one, but when you do, the `+` doesn't belong there as it's\nnot part of the callout.\n\n> Using just a blank line between the code block and the call-out list\n> (instead of the \"+\") works for asciidoc (it is happy to keep the two\n> together) but not asciidoctor (it ends the outer ordered list before\n> starting the callout list).\n\nI don't know what you mean.\n\nThese are three paragraphs:\n\n  foo\n\n  bar\n\n  roo\n\nThese are two paragraphs inside a list item with continuations:\n\n  1. foo\n  +\n  bar\n  +\n  roo\n\nThese are three paragraphs inside a list item with an open block:\n\n\n  1. foo\n  +\n  --\n  bar\n  \n  roo\n  --\n\nIf you are inside an open block, you don't need the list continuations (`+`).\n\nTherefore a callout inside an open block inside a list item does not need continuations:\n\n  1. foo\n  +\n  --\n  ----\n  line 1 <1>\n  line 2 <2>\n  ----\n\n  <1> callout 1\n\n  <2> callout 2\n  --\n\nJust like a callout outside a list item:\n\n  ----\n  line 1 <1>\n  line 2 <2>\n  ----\n\n  <1> callout 1\n\n  <2> callout 2\n\nIt's only a callout inside a list item with no open block that needs\ncontinuations, just like any other paragraph:\n\n  1. foo\n  +\n  ----\n  line 1 <1>\n  line 2 <2>\n  ----\n  +\n  <1> callout 1\n  +\n  <2> callout 2\n\n> So the second hunk in the patch, to drop the extra continuation between\n> the code block and the callout, makes perfect sense to me.\n> \n> The first hunk seems less obviously good to me.\n\nI don't see why: it's exactly the same change: removing an unnecessary space.\n\nExcept that space is represented with a `+` inside a list item.\n\n> We might say that it is good to always\n> stick the callout list directly adjacent to the associated code block,\n> since it does matter in other cases.\n\nI'd say that is good.\n\n> But dropping the blank lines between the paragraph-sized callout blocks makes\n> the source less readable,\n\nThat is a value judgement. It may be less readable to you, I disagree.\n\nI would expect the subsequent callout blocks as close to the listing block they\nrefer to as possible.\n\n> and empty lines between list elements are a pretty normal thing in asciidoc.\n\nUsually, yeah when these list elements are independent, but callout elements\nare not independent.\n\nTo me this is perfectly readable:\n\n  This is a simple example in sh:\n\n  ----\n  #!/bin/sh          <1>\n  echo 'hello world' <2>\n  ----\n  <1> Shebang\n  <2> \"echo\" prints\n\n  This is a simple example in Ruby:\n\n  ----\n  #!/usr/bin/env ruby <1>\n  puts 'hello world' <2>\n  ----\n  <1> Standard shebang\n  <2> \"puts\" puts a string\n\nPut spaces on the callouts, and it's the exact opposite:\n\n  This is a simple example in sh:\n\n  ----\n  #!/bin/sh          <1>\n  echo 'hello world' <2>\n  ----\n\n  <1> Shebang\n\n  <2> \"echo\" prints\n\n  This is a simple example in Ruby:\n\n  ----\n  #!/usr/bin/env ruby <1>\n  puts 'hello world'  <2>\n  ----\n\n  <1> Standard shebang\n\n  <2> \"puts\" puts a string\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"476415","messageId":"20230502101854.GA1180695@coredump.intra.peff.net","threadId":"59615","inReplyTo":"644af29c8526c_7f4f2945f@chronos.notmuch","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-05-02T10:18:54Z","receivedAt":"2023-05-02T10:19:24Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Apr 27, 2023 at 04:09:32PM -0600, Felipe Contreras wrote:\n\n> > Using just a blank line between the code block and the call-out list\n> > (instead of the \"+\") works for asciidoc (it is happy to keep the two\n> > together) but not asciidoctor (it ends the outer ordered list before\n> > starting the callout list).\n> \n> I don't know what you mean.\n\nFor reference, I meant this:\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 6bb32ab460..ed32497290 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -529,7 +529,7 @@ $ git checkout master~2 Makefile  <2>\n $ rm -f hello.c\n $ git checkout hello.c            <3>\n ------------\n-+\n+\n <1> switch branch\n <2> take a file out of another commit\n <3> restore `hello.c` from the index\n\nwhich asciidoc renders the same, but asciidoctor is not.\n\nYour patch is now in master removing the line entirely, though, so the\npoint is moot.\n\n-Peff\n"},{"id":"476431","messageId":"645134e7619b0_1ba2d294a7@chronos.notmuch","threadId":"59615","inReplyTo":"20230502101854.GA1180695@coredump.intra.peff.net","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-02T16:05:59Z","receivedAt":"2023-05-02T16:06:04Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Thu, Apr 27, 2023 at 04:09:32PM -0600, Felipe Contreras wrote:\n> \n> > > Using just a blank line between the code block and the call-out list\n> > > (instead of the \"+\") works for asciidoc (it is happy to keep the two\n> > > together) but not asciidoctor (it ends the outer ordered list before\n> > > starting the callout list).\n> > \n> > I don't know what you mean.\n> \n> For reference, I meant this:\n> \n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 6bb32ab460..ed32497290 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -529,7 +529,7 @@ $ git checkout master~2 Makefile  <2>\n>  $ rm -f hello.c\n>  $ git checkout hello.c            <3>\n>  ------------\n> -+\n> +\n>  <1> switch branch\n>  <2> take a file out of another commit\n>  <3> restore `hello.c` from the index\n> \n> which asciidoc renders the same, but asciidoctor is not.\n\nI see. I would say the code is ambiguous, so it's not surprising that a parser\ninterprets it as an end of a list element.\n\n-- \nFelipe Contreras\n"},{"id":"476491","messageId":"xmqqpm7ivtd0.fsf@gitster.g","threadId":"59615","inReplyTo":"20230502101854.GA1180695@coredump.intra.peff.net","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T06:09:31Z","receivedAt":"2023-05-03T06:09:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n>> > Using just a blank line between the code block and the call-out list\n>> > (instead of the \"+\") works for asciidoc (it is happy to keep the two\n>> > together) but not asciidoctor (it ends the outer ordered list before\n>> > starting the callout list).\n>> ...\n>  $ git checkout hello.c            <3>\n>  ------------\n> -+\n> +\n>  <1> switch branch\n>  <2> take a file out of another commit\n>  <3> restore `hello.c` from the index\n>\n> which asciidoc renders the same, but asciidoctor is not.\n\nYet another random annoying differences that explains why we wrote\nit that way in the first place X-<.  If it has been removed to make\nit not to matter, that was lucky of us ;-)\n\nThanks.\n\n\n\n"},{"id":"476509","messageId":"6452659e704df_682294b6@chronos.notmuch","threadId":"59615","inReplyTo":"xmqqpm7ivtd0.fsf@gitster.g","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-03T13:46:06Z","receivedAt":"2023-05-03T13:46:16Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Jeff King <peff@peff.net> writes:\n> \n> >> > Using just a blank line between the code block and the call-out list\n> >> > (instead of the \"+\") works for asciidoc (it is happy to keep the two\n> >> > together) but not asciidoctor (it ends the outer ordered list before\n> >> > starting the callout list).\n> >> ...\n> >  $ git checkout hello.cgit checkout hello.c            <3>\n> >  ------------\n> > -+\n> > +\n> >  <1> switch branch\n> >  <2> take a file out of another commit\n> >  <3> restore `hello.c` from the index\n> >\n> > which asciidoc renders the same, but asciidoctor is not.\n> \n> Yet another random annoying differences that explains why we wrote\n> it that way in the first place X-<.\n\nI don't think so. This is the sequence of events:\n\n 1. 1e2ccd3abc (Documentation: more examples., 2005-12-12)\n 2. 1be0659efc (checkout: merge local modifications while switching branches., 2006-01-12)\n 3. 48aeecdcc1 (Fix up remaining man pages that use asciidoc \"callouts\"., 2006-04-28)\n\nIn 1 \"callouts\" were added inside the listing itself, so they were not actually\ncallouts, the space was added just for formatting. In 2 other examples were\nadded, which transformed the original example to a list element, and everything\nwas peppered with `+`. Finally in 3 the code was transformed to actual AsciiDoc\ncallouts, which meant that the original space that previously was protected\ninside a listing block would not be protected anymore, so it could either be 1)\nremoved or 2) converted to `+`.\n\nIn the thread that added this `+` [1] I see no discussion about the\nalternatives.\n\nAt no point did anyone consider using a newline inside a list element, because\nspaces inside list elements don't work, so the actual two choices were:\n\nA:\n\n  ----\n  line 1 <1>\n  ----\n  <1> callout 1\n\nB:\n\n  ----\n  line 1 <1>\n  ----\n  +\n  <1> callout 1\n\nAnd there never was any actual reason given as to why B was \"chosen\".\n\nI think the reality is most of the AsciiDoc code doesn't really have any\nconsideration as to what is the actual AsciiDoc syntax, it's there because it\nseems to work, and that's it.\n\nSo I think the real reason is that a newline was there before, and newlines\nstop list elements.\n\nIt couldn't have possibly been because a newline didn't work in asciidoctor,\nbecause asciidoctor would not have been created for another 6 years.\n\n> If it has been removed to make it not to matter, that was lucky of us ;-)\n\nOnly if following the actual syntax of a language is considered \"luck\", in the\nsame way that it's \"lucky\" that following the C specification makes C code work\non most C compilers.\n\n[1] https://lore.kernel.org/git/BAYC1-PASMTP028F5C1C39F7EF6A6EEB95AEB20@CEZ.ICE/\n\n-- \nFelipe Contreras\n"},{"id":"476530","messageId":"xmqqzg6lqpht.fsf@gitster.g","threadId":"59615","inReplyTo":"20230425061029.GA4015844@coredump.intra.peff.net","subject":"Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T17:44:14Z","receivedAt":"2023-05-03T17:44:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> The first hunk seems less obviously good to me. We're not part of a\n> list, so there's no continuation. We might say that it is good to always\n> stick the callout list directly adjacent to the associated code block,\n> since it does matter in other cases. But dropping the blank lines\n> between the paragraph-sized callout blocks makes the source less\n> readable, and empty lines between list elements are a pretty normal\n> thing in asciidoc.\n>\n> That said, I don't feel _too_ strongly about it, so I'm OK with the\n> patch as-is.\n\nI agree with the conclusion.  \n\nThe first hunk may be iffy (in the sense that \"it is not\ncut-and-dried better than the original\"), but the change makes the\npostimage of that hunk look similar to the postimage of the second\nhunk, and adopting it as our local rule to alwys stick the callout\nlist to the associated block gives us more consistent look, that is\ngood, too.\n"}]}