{"thread":{"id":"59547","subject":"[PATCH] MyFirstContribution: render literal *","startedAt":"2023-04-05T02:29:11Z","lastAt":"2023-04-06T21:15:03Z","messageCount":7,"participants":["Linus Arver via GitGitGadget","Felipe Contreras","Linus Arver","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"474821","messageId":"pull.1510.git.1680661709616.gitgitgadget@gmail.com","threadId":"59547","inReplyTo":null,"subject":"[PATCH] MyFirstContribution: render literal *","fromName":"Linus Arver via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-04-05T02:28:29Z","receivedAt":"2023-04-05T02:29:11Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"From: Linus Arver <linusa@google.com>\n\nThe HTML version of MyFirstContribution [1] does not render the\nasterisks (*) meant to be typed in as glob patterns by the user, because\nthey are being interpreted as bold text delimiters.\n\n[1]: Search for \"pattern\" in\nhttps://git-scm.com/docs/MyFirstContribution#v2-git-send-email\n\nSigned-off-by: Linus Arver <linusa@google.com>\n---\n    MyFirstContribution: render literal *\n    \n    Hello! I'm Linus Arver from Google. I'll be contributing toward the\n    libification efforts in the near future. Meanwhile, I noticed a\n    formatting error in the HTML output of the MyFirstContribution doc\n    (hence this patch).\n    \n    I am also the author of this old patch series from 2014\n    [https://lore.kernel.org/git/1407518960-6203-1-git-send-email-linusarver@gmail.com/]\n    and am happy to return to hacking on Git. :)\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1510%2Flistx%2Ffix-doc-formatting-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1510/listx/fix-doc-formatting-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1510\n\n Documentation/MyFirstContribution.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex ccfd0cb5f3e..9c64bf58757 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1164,7 +1164,7 @@ After you run this command, `format-patch` will output the patches to the `psuh/\n directory, alongside the v1 patches. Using a single directory makes it easy to\n refer to the old v1 patches while proofreading the v2 patches, but you will need\n to be careful to send out only the v2 patches. We will use a pattern like\n-\"psuh/v2-*.patch\" (not \"psuh/*.patch\", which would match v1 and v2 patches).\n+`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches).\n \n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n\nbase-commit: 73876f4861cd3d187a4682290ab75c9dccadbc56\n-- \ngitgitgadget\n"},{"id":"474822","messageId":"CAMP44s15E0xJwXv8qGp8FqQvB_KaxS2TXenNZNH_VzvXpXv4Hw@mail.gmail.com","threadId":"59547","inReplyTo":"pull.1510.git.1680661709616.gitgitgadget@gmail.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-05T04:30:30Z","receivedAt":"2023-04-05T04:30:48Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Apr 4, 2023 at 9:56 PM Linus Arver via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> From: Linus Arver <linusa@google.com>\n>\n> The HTML version of MyFirstContribution [1] does not render the\n> asterisks (*) meant to be typed in as glob patterns by the user, because\n> they are being interpreted as bold text delimiters.\n\nYes, they should be between backticks in order to be interpreted as literals.\n\nAcked-by: Felipe Contreras <felipe.contreras@gmail.com>\n\n>  Documentation/MyFirstContribution.txt | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index ccfd0cb5f3e..9c64bf58757 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -1164,7 +1164,7 @@ After you run this command, `format-patch` will output the patches to the `psuh/\n>  directory, alongside the v1 patches. Using a single directory makes it easy to\n>  refer to the old v1 patches while proofreading the v2 patches, but you will need\n>  to be careful to send out only the v2 patches. We will use a pattern like\n> -\"psuh/v2-*.patch\" (not \"psuh/*.patch\", which would match v1 and v2 patches).\n> +`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches).\n\nSmall nit: with this change we would lose the quotes, which are\nhelpful, I would rather do \"`foo`\".\n\nAnd for what it's worth I would revamp the whole section, something like this:\n\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1136,18 +1136,18 @@ information on how to handle comments from reviewers.\n We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll\n mark the tip of our v1 branch for easy reference:\n\n-----\n+....\n $ git checkout psuh\n $ git branch psuh-v1\n-----\n+....\n\n Refine your patch series by using `git rebase -i` to adjust commits based upon\n reviewer comments. Once the patch series is ready for submission, generate your\n patches again, but with some new flags:\n\n-----\n+....\n $ git format-patch -v2 --cover-letter -o psuh/ --range-diff\nmaster..psuh-v1 master..\n-----\n+....\n\n The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a\n range-diff between `psuh-v1` and `psuh` in the cover letter (see\n@@ -1157,53 +1157,53 @@ between your v1 and v2 patches.\n The `-v2` parameter tells `format-patch` to output your patches\n as version \"2\". For instance, you may notice that your v2 patches are\n all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format\n-your patches by prefixing them with \"[PATCH v2]\" instead of \"[PATCH]\",\n-and your range-diff will be prefaced with \"Range-diff against v1\".\n+your patches by prefixing them with \"`[PATCH v2]`\" instead of \"`[PATCH]`\",\n+and your range-diff will be prefaced with \"`Range-diff against v1`\".\n\n After you run this command, `format-patch` will output the patches to\nthe `psuh/`\n directory, alongside the v1 patches. Using a single directory makes it easy to\n refer to the old v1 patches while proofreading the v2 patches, but\nyou will need\n to be careful to send out only the v2 patches. We will use a pattern like\n-\"psuh/v2-*.patch\" (not \"psuh/*.patch\", which would match v1 and v2 patches).\n+\"`psuh/v2-*.patch`\" (not \"`psuh/*.patch`\", which would match v1 and\nv2 patches).\n\n Edit your cover letter again. Now is a good time to mention what's different\n between your last version and now, if it's something significant. You do not\n need the exact same body in your second cover letter; focus on explaining to\n reviewers the changes you've made that may not be as visible.\n\n-You will also need to go and find the Message-Id of your previous cover letter.\n+You will also need to go and find the `Message-ID` of your previous\ncover letter.\n You can either note it when you send the first series, from the output of `git\n send-email`, or you can look it up on the\n https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n-archives, click on it, then click \"permalink\" or \"raw\" to reveal the Message-Id\n+archives, click on it, then click \"permalink\" or \"raw\" to reveal the\n`Message-ID`\n header. It should match:\n\n-----\n-Message-Id: <foo.12345.author@example.com>\n-----\n+....\n+Message-ID: <foo.12345.author@example.com>\n+....\n\n-Your Message-Id is `<foo.12345.author@example.com>`. This example will be used\n-below as well; make sure to replace it with the correct Message-Id for your\n-**previous cover letter** - that is, if you're sending v2, use the Message-Id\n-from v1; if you're sending v3, use the Message-Id from v2.\n+Your `Message-ID` is `<foo.12345.author@example.com>`. This example\nwill be used\n+below as well; make sure to replace it with the correct `Message-ID` for your\n+**previous cover letter** - that is, if you're sending v2, use the `Message-ID`\n+from v1; if you're sending v3, use the `Message-ID` from v2.\n\n While you're looking at the email, you should also note who is CC'd, as it's\n common practice in the mailing list to keep all CCs on a thread. You can add\n these CC lines directly to your cover letter with a line like so in the header\n (before the Subject line):\n\n-----\n+....\n CC: author@example.com, Othe R <other@example.com>\n-----\n+....\n\n Now send the emails again, paying close attention to which messages you pass in\n to the command:\n\n-----\n+....\n $ git send-email --to=target@example.com\n  --in-reply-to=\"<foo.12345.author@example.com>\"\n  psuh/v2-*.patch\n-----\n+....\n\n [[single-patch]]\n === Bonus Chapter: One-Patch Changes\n\n\n-- \nFelipe Contreras\n"},{"id":"474823","messageId":"owlyzg7mubui.fsf@fine.c.googlers.com","threadId":"59547","inReplyTo":"CAMP44s15E0xJwXv8qGp8FqQvB_KaxS2TXenNZNH_VzvXpXv4Hw@mail.gmail.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-04-05T05:39:17Z","receivedAt":"2023-04-05T05:39:22Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Hello Felipe!\n\nFelipe Contreras <felipe.contreras@gmail.com> writes:\n> Small nit: with this change we would lose the quotes, which are\n> helpful, I would rather do \"`foo`\".\n\nI see that the doc currently does not quote backticked areas, so this\nwould be introducing a new style. I think such a change should belong in\na separate patch.\n\nThat being said, personally I think having the quotes around the\nbackticks makes things harder to read, especially for users directly\nreading from the raw *.txt file.\n\n\n> And for what it's worth I would revamp the whole section, something like  \n> this:\n\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -1136,18 +1136,18 @@ information on how to handle comments from  \n> reviewers.\n>   We'll reuse our `psuh` topic branch for v2. Before we make any changes,  \n> we'll\n>   mark the tip of our v1 branch for easy reference:\n\n> -----\n> +....\n>   $ git checkout psuh\n>   $ git branch psuh-v1\n> -----\n> +....\n\n\nWhile I see the four dots (....) being used to denote regions in other\nfiles like SubmittingPatches, they are not used at all in\nMyFirstContribution.txt. So I am not sure why we would want to change\nthis.\n"},{"id":"474844","messageId":"CAMP44s128zFcMrK7URUK73ZmzETDRA5SNkWwoHgukZ9Q3f+5Qg@mail.gmail.com","threadId":"59547","inReplyTo":"owlyzg7mubui.fsf@fine.c.googlers.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-05T13:22:58Z","receivedAt":"2023-04-05T13:23:13Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Apr 5, 2023 at 12:39 AM Linus Arver <linusa@google.com> wrote:\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> > And for what it's worth I would revamp the whole section, something like\n> > this:\n>\n> > --- a/Documentation/MyFirstContribution.txt\n> > +++ b/Documentation/MyFirstContribution.txt\n> > @@ -1136,18 +1136,18 @@ information on how to handle comments from\n> > reviewers.\n> >   We'll reuse our `psuh` topic branch for v2. Before we make any changes,\n> > we'll\n> >   mark the tip of our v1 branch for easy reference:\n>\n> > -----\n> > +....\n> >   $ git checkout psuh\n> >   $ git branch psuh-v1\n> > -----\n> > +....\n>\n>\n> While I see the four dots (....) being used to denote regions in other\n> files like SubmittingPatches, they are not used at all in\n> MyFirstContribution.txt. So I am not sure why we would want to change\n> this.\n\n\"We\" probably don't want to change it, *I* do. Because in AsciiDoc\nthere's a difference between a listing block and a literal block, but\nthe Git documentation does a very poor job of being compatible with\nAsciiDoc anyway. It doesn't even use the modern syntax. So it probably\ndoesn't matter.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"474859","messageId":"owlywn2qtj75.fsf@fine.c.googlers.com","threadId":"59547","inReplyTo":"CAMP44s128zFcMrK7URUK73ZmzETDRA5SNkWwoHgukZ9Q3f+5Qg@mail.gmail.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Linus Arver","fromEmail":"linusa@google.com","sentAt":"2023-04-05T15:58:06Z","receivedAt":"2023-04-05T15:58:12Z","isPatch":true,"sender":{"key":"linus@ucla.edu","avatar":null},"body":"Felipe Contreras <felipe.contreras@gmail.com> writes:\n\n> \"We\" probably don't want to change it, *I* do. Because in AsciiDoc\n> there's a difference between a listing block and a literal block, but\n> the Git documentation does a very poor job of being compatible with\n> AsciiDoc anyway.\n\nTIL. I'll be happy to apply the listing block -> literal block changes\nyou suggested in a separate follow-up patch (probably looking at other\ndocs we have as well, not just for MyFirstContribution.txt).\n\n> It doesn't even use the modern syntax.\n\nI am new to asciidoc; if you know any other examples of modernizations\nwe can do, feel free to chime in. Thanks.\n"},{"id":"474923","messageId":"CAMP44s0_-DaXNMfvfQG8PUbKu9tbbdv4WCYuxY7y58Waoz=nkA@mail.gmail.com","threadId":"59547","inReplyTo":"owlywn2qtj75.fsf@fine.c.googlers.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-06T08:52:41Z","receivedAt":"2023-04-06T08:52:56Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Apr 5, 2023 at 10:58 AM Linus Arver <linusa@google.com> wrote:\n>\n> Felipe Contreras <felipe.contreras@gmail.com> writes:\n>\n> > \"We\" probably don't want to change it, *I* do. Because in AsciiDoc\n> > there's a difference between a listing block and a literal block, but\n> > the Git documentation does a very poor job of being compatible with\n> > AsciiDoc anyway.\n>\n> TIL. I'll be happy to apply the listing block -> literal block changes\n> you suggested in a separate follow-up patch (probably looking at other\n> docs we have as well, not just for MyFirstContribution.txt).\n>\n> > It doesn't even use the modern syntax.\n>\n> I am new to asciidoc; if you know any other examples of modernizations\n> we can do, feel free to chime in. Thanks.\n\nUnfortunately I cannot recommend you to do any modernizations, because\nGit doesn't use modern AsciiDoc: it uses legacy asciiidoc.py.\n\nIf you still want to do some modernization, it would have to be\ncompatible with legacy asciidoc.py, so it would require testing in\nboth. I tried to explain the differences in [1], but that's not yet\naccepted, so I don't know what a documentation writer is supposed to\ndo at this point.\n\nThere's too many considerations to think about before even attempting\nto do `make doc`, so I don't know.\n\nCheers.\n\n[1] https://lore.kernel.org/git/20230405125453.49674-2-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"474953","messageId":"ZC82US7vQpKKpOtF@nand.local","threadId":"59547","inReplyTo":"pull.1510.git.1680661709616.gitgitgadget@gmail.com","subject":"Re: [PATCH] MyFirstContribution: render literal *","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2023-04-06T21:14:57Z","receivedAt":"2023-04-06T21:15:03Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Apr 05, 2023 at 02:28:29AM +0000, Linus Arver via GitGitGadget wrote:\n> ---\n>\n>  Documentation/MyFirstContribution.txt | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n\nFor what it's worth, I think that this change is very reasonable and I'd\nbe happy to see it go forward as-is.\n\nThanks,\nTaylor\n"}]}