{"thread":{"id":"50845","subject":"[PATCH v1 0/2] minor asciidoc/tor formatting fixes","startedAt":"2019-03-30T18:30:11Z","lastAt":"2019-04-10T03:10:00Z","messageCount":23,"participants":["Todd Zullinger","Jeff King","Jeff Hostetler","Martin Ågren","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"372810","messageId":"20190330183001.16624-1-tmz@pobox.com","threadId":"50845","inReplyTo":null,"subject":"[PATCH v1 0/2] minor asciidoc/tor formatting fixes","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-03-30T18:29:59Z","receivedAt":"2019-03-30T18:30:11Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Just chipping away at the remaining differences between asciidoc and\nasciidoctor.\n\nTodd Zullinger (2):\n Documentation/rev-list-options: wrap --date= block with \"--\"\n Documentation/git-status: fix titles in porcelain v2 section\n\n Documentation/git-status.txt | 12 ++++++++----\n Documentation/rev-list-options.txt | 22 +++++++++++-----------\n 2 files changed, 19 insertions(+), 15 deletions(-)\n\n"},{"id":"372811","messageId":"20190330183001.16624-3-tmz@pobox.com","threadId":"50845","inReplyTo":"20190330183001.16624-1-tmz@pobox.com","subject":"[PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-03-30T18:30:01Z","receivedAt":"2019-03-30T18:30:28Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Asciidoc uses either one-line or two-line syntax for document/section\ntitles[1]. The two-line form is used in git-status. Fix a few section\ntitles in the porcelain v2 section which were inadvertently using\nmarkdown syntax.\n\n[1] http://asciidoc.org/userguide.html#X17\n\nSigned-off-by: Todd Zullinger \n---\n\nThe '^### ' lines were added in 1cd828ddc8 (\"git-status.txt: describe\n--porcelain=v2 format\", 2016-08-11). I'm _presuming_ they were made\nwith markdown syntax in mind, but if not I can drop that bit from the\ncommit message. Jeff H, do you happen to recall?\n\nAs an aside, while I was reading the Asciidoc/tor manuals, I notice the\ntwo-line title syntax was not mentioned in Asciidoctor. That seems to\nbe because Asciidoctor has suggested the two-line title format should be\ndeprecated, as discussed at:\n\n https://github.com/asciidoctor/asciidoctor/issues/418\n\nI'm not sure how likely that is to occur. With the 2.0 release,\nasciidoctor plans to use semantic versioning, so I would not expect any\ndeprecation to happen before at least 2.1. It would only affect use\nwithout compat-mode.\n\n Documentation/git-status.txt | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 861d821d7f..d4e8f24f0c 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -278,7 +278,8 @@ Header lines start with \"#\" and are added in response to specific\n command line arguments. Parsers should ignore headers they\n don't recognize.\n \n-### Branch Headers\n+Branch Headers\n+^^^^^^^^^^^^^^\n \n If `--branch` is given, a series of header lines are printed with\n information about the current branch.\n@@ -294,7 +295,8 @@ Line Notes\n ------------------------------------------------------------\n ....\n \n-### Changed Tracked Entries\n+Changed Tracked Entries\n+^^^^^^^^^^^^^^^^^^^^^^^\n \n Following the headers, a series of lines are printed for tracked\n entries. One of three different line formats may be used to describe\n@@ -365,7 +367,8 @@ Field Meaning\n --------------------------------------------------------\n ....\n \n-### Other Items\n+Other Items\n+^^^^^^^^^^^\n \n Following the tracked entries (and if requested), a series of\n lines will be printed for untracked and then ignored items\n@@ -379,7 +382,8 @@ Ignored items have the following format:\n \n ! \n \n-### Pathname Format Notes and -z\n+Pathname Format Notes and -z\n+^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n \n When the `-z` option is given, pathnames are printed as is and\n without any quoting and lines are terminated with a NUL (ASCII 0x00)\n"},{"id":"372812","messageId":"20190330183001.16624-2-tmz@pobox.com","threadId":"50845","inReplyTo":"20190330183001.16624-1-tmz@pobox.com","subject":"[PATCH v1 1/2] Documentation/rev-list-options: wrap --date= block with \"--\"","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-03-30T18:30:00Z","receivedAt":"2019-03-30T18:30:35Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Using \"+\" to continue multiple list items is more tedious and\nerror-prone than wrapping the entire block with \"--\" block markers.\n\nWhen using asciidoctor, the list items after the --date=iso list items\nare incorrectly formatted when using \"+\" continuation. Use \"--\" block\nmarkers to correctly format the block.\n\nWhen using asciidoc there is no change in how the content is rendered.\n\nSigned-off-by: Todd Zullinger \n---\n\nThe issue this fixes can be seen in the git-log and git-rev-list docs on\ngit-scm.com:\n\nhttps://git-scm.com/docs/git-log#Documentation/git-log.txt---dateltformatgt\nhttps://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---dateltformatgt\n\n Documentation/rev-list-options.txt | 22 +++++++++++-----------\n 1 file changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex ca959a7286..7b415dff82 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -805,12 +805,13 @@ include::pretty-options.txt[]\n \tauthor's). If `-local` is appended to the format (e.g.,\n \t`iso-local`), the user's local time zone is used instead.\n +\n+--\n `--date=relative` shows dates relative to the current time,\n e.g. ``2 hours ago''. The `-local` option has no effect for\n `--date=relative`.\n-+\n+\n `--date=local` is an alias for `--date=default-local`.\n-+\n+\n `--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.\n The differences to the strict ISO 8601 format are:\n \n@@ -818,15 +819,14 @@ The differences to the strict ISO 8601 format are:\n \t- a space between time and time zone\n \t- no colon between hours and minutes of the time zone\n \n-+\n `--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict\n ISO 8601 format.\n-+\n+\n `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822\n format, often found in email messages.\n-+\n+\n `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.\n-+\n+\n `--date=raw` shows the date as seconds since the epoch (1970-01-01\n 00:00:00 UTC), followed by a space, and then the timezone as an offset\n from UTC (a `+` or `-` with four digits; the first two are hours, and\n@@ -835,28 +835,28 @@ with `strftime(\"%s %z\")`).\n Note that the `-local` option does not affect the seconds-since-epoch\n value (which is always measured in UTC), but does switch the accompanying\n timezone value.\n-+\n+\n `--date=human` shows the timezone if the timezone does not match the\n current time-zone, and doesn't print the whole date if that matches\n (ie skip printing year for dates that are \"this year\", but also skip\n the whole date itself if it's in the last few days and we can just say\n what weekday it was). For older dates the hour and minute is also\n omitted.\n-+\n+\n `--date=unix` shows the date as a Unix epoch timestamp (seconds since\n 1970). As with `--raw`, this is always in UTC and therefore `-local`\n has no effect.\n-+\n+\n `--date=format:...` feeds the format `...` to your system `strftime`,\n except for %z and %Z, which are handled internally.\n Use `--date=format:%c` to show the date in your system locale's\n preferred format. See the `strftime` manual for a complete list of\n format placeholders. When using `-local`, the correct syntax is\n `--date=format-local:...`.\n-+\n+\n `--date=default` is the default format, and is similar to\n `--date=rfc2822`, with a few exceptions:\n-\n+--\n \t- there is no comma after the day-of-week\n \n \t- the time zone is omitted when the local time zone is used\n"},{"id":"372886","messageId":"20190401130804.GA11664@sigill.intra.peff.net","threadId":"50845","inReplyTo":"20190330183001.16624-2-tmz@pobox.com","subject":"Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date= block with \"--\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-04-01T13:08:04Z","receivedAt":"2019-04-01T13:08:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote:\n\n> Using \"+\" to continue multiple list items is more tedious and\n> error-prone than wrapping the entire block with \"--\" block markers.\n> \n> When using asciidoctor, the list items after the --date=iso list items\n> are incorrectly formatted when using \"+\" continuation. Use \"--\" block\n> markers to correctly format the block.\n> \n> When using asciidoc there is no change in how the content is rendered.\n\nThis seems like an asciidoctor bug, though I think this kind of\nlist-within-a-list stuff is inherently a bit heuristic-driven just due\nto the syntax.\n\nI do agree that the result after your patch is more readable, so I think\nI prefer it even if the asciidoctor bug were fixed. I suspect we could\nbe using \"--\" blocks for readability in more places (I don't think it's\nworth going on a hunt to convert old spots, but something to keep in\nmind as we write new documentation).\n\n-Peff\n"},{"id":"372887","messageId":"20190401131831.GA12254@sigill.intra.peff.net","threadId":"50845","inReplyTo":"20190330183001.16624-3-tmz@pobox.com","subject":"Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-04-01T13:18:32Z","receivedAt":"2019-04-01T13:18:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Mar 30, 2019 at 02:30:01PM -0400, Todd Zullinger wrote:\n\n> Asciidoc uses either one-line or two-line syntax for document/section\n> titles[1]. The two-line form is used in git-status. Fix a few section\n> titles in the porcelain v2 section which were inadvertently using\n> markdown syntax.\n\nYep, makes sense. One observation:\n\n> -### Branch Headers\n> +Branch Headers\n> +^^^^^^^^^^^^^^\n\nThe one-line equivalent in asciidoc would be something like:\n\n === Branch Headers\n\nbut that's actually a \"level 2\" header (because it counts from zero),\nwhereas \"^\" underlining is a \"level 3\" header. But I think \"^\" is right\nhere, because this is under level 2 \"~\" header.\n\n> As an aside, while I was reading the Asciidoc/tor manuals, I notice the\n> two-line title syntax was not mentioned in Asciidoctor. That seems to\n> be because Asciidoctor has suggested the two-line title format should be\n> deprecated, as discussed at:\n> \n> https://github.com/asciidoctor/asciidoctor/issues/418\n> \n> I'm not sure how likely that is to occur. With the 2.0 release,\n> asciidoctor plans to use semantic versioning, so I would not expect any\n> deprecation to happen before at least 2.1. It would only affect use\n> without compat-mode.\n\nI think it's probably fine to punt on this until we see some actual\nmovement upstream on the deprecation / removal.\n\nOne side note. The original asciidoc user guide says one-line headers\nhave equals on either side, like:\n\n === Branch Headers ===\n\nbut that one can omit the trailing delimiter. The asciidoctor reference\njust suggests using the one-sided:\n\n === Branch Headers\n\nSo presumably if we do want to convert, we would just go with the\none-sided version.\n\n-Peff\n"},{"id":"373009","messageId":"a8be0a1e-bb34-5709-0307-68b1fdd2d95c@jeffhostetler.com","threadId":"50845","inReplyTo":"20190330183001.16624-3-tmz@pobox.com","subject":"Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section","fromName":"Jeff Hostetler","fromEmail":"git@jeffhostetler.com","sentAt":"2019-04-03T08:49:50Z","receivedAt":"2019-04-03T08:49:58Z","isPatch":true,"sender":{"key":"git@jeffhostetler.com","avatar":null},"body":"\n\nOn 3/30/2019 2:30 PM, Todd Zullinger wrote:\n> Asciidoc uses either one-line or two-line syntax for document/section\n> titles[1]. The two-line form is used in git-status. Fix a few section\n> titles in the porcelain v2 section which were inadvertently using\n> markdown syntax.\n> \n> [1] http://asciidoc.org/userguide.html#X17\n> \n> Signed-off-by: Todd Zullinger \n> ---\n> \n> The '^### ' lines were added in 1cd828ddc8 (\"git-status.txt: describe\n> --porcelain=v2 format\", 2016-08-11). I'm _presuming_ they were made\n> with markdown syntax in mind, but if not I can drop that bit from the\n> commit message. Jeff H, do you happen to recall?\n\nYes, I was probably had markdown on the brain that day.\nThanks\nJeff\n\n\n"},{"id":"373012","messageId":"CAN0heSpB_0Hi2zCA+gmiaARpSYM7fKayB2rs6wFi_VeXevqd+Q@mail.gmail.com","threadId":"50845","inReplyTo":"20190330183001.16624-1-tmz@pobox.com","subject":"Re: [PATCH v1 0/2] minor asciidoc/tor formatting fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-03T09:26:43Z","receivedAt":"2019-04-03T09:26:58Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 30 Mar 2019 at 19:30, Todd Zullinger wrote:\n>\n> Just chipping away at the remaining differences between asciidoc and\n> asciidoctor.\n>\n> Todd Zullinger (2):\n> Documentation/rev-list-options: wrap --date= block with \"--\"\n> Documentation/git-status: fix titles in porcelain v2 section\n\nNice. I've tested and diffed across various dimensions. Looks good to me.\n\nMartin\n"},{"id":"373164","messageId":"20190405012002.GO4047@pobox.com","threadId":"50845","inReplyTo":"20190401130804.GA11664@sigill.intra.peff.net","subject":"Re: [PATCH v1 1/2] Documentation/rev-list-options: wrap --date= block with \"--\"","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T01:20:02Z","receivedAt":"2019-04-05T01:20:11Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi,\n\nJeff King wrote:\n> On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote:\n> \n>> Using \"+\" to continue multiple list items is more tedious and\n>> error-prone than wrapping the entire block with \"--\" block markers.\n>> \n>> When using asciidoctor, the list items after the --date=iso list items\n>> are incorrectly formatted when using \"+\" continuation. Use \"--\" block\n>> markers to correctly format the block.\n>> \n>> When using asciidoc there is no change in how the content is rendered.\n> \n> This seems like an asciidoctor bug, though I think this kind of\n> list-within-a-list stuff is inherently a bit heuristic-driven just due\n> to the syntax.\n\nIndeed. There's certainly a limit to the changes we want to\nmake solely to work-around issues in either asciidoc or\nasciidoctor. When the work-around is (at least arguably) an\nimprovement, then it's probably worthwhile. That's how I\nthought about it, anyway. :)\n\n> I do agree that the result after your patch is more readable, so I think\n> I prefer it even if the asciidoctor bug were fixed. I suspect we could\n> be using \"--\" blocks for readability in more places (I don't think it's\n> worth going on a hunt to convert old spots, but something to keep in\n> mind as we write new documentation).\n\nAgreed, that sounds perfectly reasonable to me. The\nAsciidoctor user manual says:\n\n If you’re attaching more than one block to a list item,\n you’re strongly encouraged to wrap the content inside an\n open block. That way, you only need a single list\n continuation line to attach the open block to the list\n item. Within the open block, you write like you normally\n would, no longer having to worry about adding list\n continuations between the blocks to keep them attached\n to the list item.\n\nhttps://asciidoctor.org/docs/user-manual/#list-continuation\n\nI imagine it's \"strongly encouraged\" both to help consumers\navoid these sort of oddly-parsed continuation issues, as\nwell as the Asciidoctor devs from having to field as many\nbug reports.\n\n-- \nTodd\n"},{"id":"373165","messageId":"20190405012650.GP4047@pobox.com","threadId":"50845","inReplyTo":"20190401131831.GA12254@sigill.intra.peff.net","subject":"Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T01:26:50Z","receivedAt":"2019-04-05T01:27:03Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Jeff King wrote:\n> On Sat, Mar 30, 2019 at 02:30:01PM -0400, Todd Zullinger wrote:\n> \n>> Asciidoc uses either one-line or two-line syntax for document/section\n>> titles[1]. The two-line form is used in git-status. Fix a few section\n>> titles in the porcelain v2 section which were inadvertently using\n>> markdown syntax.\n> \n> Yep, makes sense. One observation:\n> \n>> -### Branch Headers\n>> +Branch Headers\n>> +^^^^^^^^^^^^^^\n> \n> The one-line equivalent in asciidoc would be something like:\n> \n> === Branch Headers\n> \n> but that's actually a \"level 2\" header (because it counts from zero),\n> whereas \"^\" underlining is a \"level 3\" header. But I think \"^\" is right\n> here, because this is under level 2 \"~\" header.\n\nYeah, since there were a number of existing two-line headers\nin the document, I thought it would be better to simply\nupdate these to that form than convert the others. We have\nfar more of the two-line form too, so it's more consistent\nwith the existing docs.\n\n>> As an aside, while I was reading the Asciidoc/tor manuals, I notice the\n>> two-line title syntax was not mentioned in Asciidoctor. That seems to\n>> be because Asciidoctor has suggested the two-line title format should be\n>> deprecated, as discussed at:\n>> \n>> https://github.com/asciidoctor/asciidoctor/issues/418\n>> \n>> I'm not sure how likely that is to occur. With the 2.0 release,\n>> asciidoctor plans to use semantic versioning, so I would not expect any\n>> deprecation to happen before at least 2.1. It would only affect use\n>> without compat-mode.\n> \n> I think it's probably fine to punt on this until we see some actual\n> movement upstream on the deprecation / removal.\n\nNo doubt. I'm sure that would be a long deprecation period.\n\n> One side note. The original asciidoc user guide says one-line headers\n> have equals on either side, like:\n> \n> === Branch Headers ===\n> \n> but that one can omit the trailing delimiter. The asciidoctor reference\n> just suggests using the one-sided:\n> \n> === Branch Headers\n\nInteresting. I didn't notice the matching right hand side\nwhile I was looking at the original asciidoc manual.\n\n> So presumably if we do want to convert, we would just go with the\n> one-sided version.\n\nSeems like a good rule. I presume that when in doubt, we\nshould look to the Asciidoctor reference for the current\nbest practice.\n\nThanks,\n\n-- \nTodd\n"},{"id":"373166","messageId":"20190405013228.GQ4047@pobox.com","threadId":"50845","inReplyTo":"a8be0a1e-bb34-5709-0307-68b1fdd2d95c@jeffhostetler.com","subject":"Re: [PATCH v1 2/2] Documentation/git-status: fix titles in porcelain v2 section","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T01:32:28Z","receivedAt":"2019-04-05T01:32:38Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi,\n\nJeff Hostetler wrote:\n> On 3/30/2019 2:30 PM, Todd Zullinger wrote:\n>> The '^### ' lines were added in 1cd828ddc8 (\"git-status.txt: describe\n>> --porcelain=v2 format\", 2016-08-11). I'm _presuming_ they were made\n>> with markdown syntax in mind, but if not I can drop that bit from the\n>> commit message. Jeff H, do you happen to recall?\n> \n> Yes, I was probably had markdown on the brain that day.\n\nCool, thanks. Lucky guess on my part then. It's not like\nI've ever done something similar in other repos. ;)\n\n-- \nTodd\n"},{"id":"373167","messageId":"20190405014040.GR4047@pobox.com","threadId":"50845","inReplyTo":"CAN0heSpB_0Hi2zCA+gmiaARpSYM7fKayB2rs6wFi_VeXevqd+Q@mail.gmail.com","subject":"Re: [PATCH v1 0/2] minor asciidoc/tor formatting fixes","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T01:40:41Z","receivedAt":"2019-04-05T01:40:50Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi,\n\nMartin Ågren wrote:\n> On Sat, 30 Mar 2019 at 19:30, Todd Zullinger wrote:\n>>\n>> Just chipping away at the remaining differences between asciidoc and\n>> asciidoctor.\n>>\n>> Todd Zullinger (2):\n>> Documentation/rev-list-options: wrap --date= block with \"--\"\n>> Documentation/git-status: fix titles in porcelain v2 section\n> \n> Nice. I've tested and diffed across various dimensions. Looks good to me.\n\nThanks for testing! On pu we're down to a fairly small\namount of differences now. Most of what remains are\nwhitespace changes; some of which I would like to bring up\nto the Asciidoctor team to see if they're intentional.\n\nThere are two other changes I've got queued locally. One in\ngit-show-branch.txt removes the last use of {apostrophe}.\nAnother in git-svn.txt is a bit of a work-around for a\ndifference in the way asciidoc and asciidoctor parse the\nsecond paragraph in the CONFIGURATION section. That may\nwell be an asiidoctor bug, but it seems like one we can\nadjust for without much effort.\n\n-- \nTodd\n"},{"id":"373191","messageId":"CAN0heSrbjRExHwch0K_W+xwpERnFUJmaiHhCkAaK9nnxFnXEhw@mail.gmail.com","threadId":"50845","inReplyTo":"20190405014040.GR4047@pobox.com","subject":"Re: [PATCH v1 0/2] minor asciidoc/tor formatting fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-05T10:23:36Z","receivedAt":"2019-04-05T10:23:52Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Todd,\n\nOn Fri, 5 Apr 2019 at 03:40, Todd Zullinger wrote:\n\n> > On Sat, 30 Mar 2019 at 19:30, Todd Zullinger wrote:\n> >>\n> >> Just chipping away at the remaining differences between asciidoc and\n> >> asciidoctor.\n> >>\n> >> Todd Zullinger (2):\n> >> Documentation/rev-list-options: wrap --date= block with \"--\"\n> >> Documentation/git-status: fix titles in porcelain v2 section\n\n> There are two other changes I've got queued locally. One in\n> git-show-branch.txt removes the last use of {apostrophe}.\n> Another in git-svn.txt is a bit of a work-around for a\n> difference in the way asciidoc and asciidoctor parse the\n> second paragraph in the CONFIGURATION section. That may\n> well be an asiidoctor bug, but it seems like one we can\n> adjust for without much effort.\n\nThe second one looks like it can be fixed by using `*` instead of '\\*',\nwhich I think is more correct anyway. I don't know what your local\nworkaround looks like, but I think a patch like \"use backticks\nconsistently\" (both change to them, in a number of places, and add them,\nwhere we currently have nothing) would be a good change by itself, and\nwe could note that \"BTW, this fixes ...\". How does that compare to what\nyou have?\n\nMartin\n"},{"id":"373272","messageId":"20190405225115.3882-1-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrbjRExHwch0K_W+xwpERnFUJmaiHhCkAaK9nnxFnXEhw@mail.gmail.com","subject":"[PATCH 0/2] a few more minor asciidoc/tor formatting fixes","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T22:51:13Z","receivedAt":"2019-04-05T22:51:29Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi,\n\nMartin Ågren wrote:\n> On Fri, 5 Apr 2019 at 03:40, Todd Zullinger wrote:\n>> There are two other changes I've got queued locally. One in\n>> git-show-branch.txt removes the last use of {apostrophe}.\n>> Another in git-svn.txt is a bit of a work-around for a\n>> difference in the way asciidoc and asciidoctor parse the\n>> second paragraph in the CONFIGURATION section. That may\n>> well be an asiidoctor bug, but it seems like one we can\n>> adjust for without much effort.\n> \n> The second one looks like it can be fixed by using `*` instead of '\\*',\n> which I think is more correct anyway. I don't know what your local\n> workaround looks like, but I think a patch like \"use backticks\n> consistently\" (both change to them, in a number of places, and add them,\n> where we currently have nothing) would be a good change by itself, and\n> we could note that \"BTW, this fixes ...\". How does that compare to what\n> you have?\n\nThat's exactly what I have -- except that I only changed the\nparts needed to improve compatibility between asciidoc and\nasciidoctor. So my commit message justifies it differently.\n\nYou're probably right that a more general cleanup could be done\nand then we get better asciidoctor compatibilty as a consequence.\nI was trying to keep from taking too many tangents to avoid\nmaking more work (both for myself and reviewers). :)\n\nHere's what I have currently. I haven't tested this much with\nasciidoctor-1.5.x releases (or maybe not at all -- it's been a\nweek or so since I worked on this).\n\nTodd Zullinger (2):\n Documentation/git-show-branch: drop last use of {apostrophe}\n Documentation/git-svn: improve asciidoctor compatibility\n\n Documentation/git-show-branch.txt | 2 +-\n Documentation/git-svn.txt | 6 +++---\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\n"},{"id":"373273","messageId":"20190405225115.3882-2-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrbjRExHwch0K_W+xwpERnFUJmaiHhCkAaK9nnxFnXEhw@mail.gmail.com","subject":"[PATCH 1/2] Documentation/git-show-branch: drop last use of {apostrophe}","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T22:51:14Z","receivedAt":"2019-04-05T22:51:29Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"The {apostrophe} was needed at the time of a521845800 (\"Documentation:\nremove stray backslash in show-branch discussion\", 2010-08-20). All\nother uses of {apostrophe} were removed in 6cf378f0cb (\"docs: stop using\nasciidoc no-inline-literal\", 2012-04-26).\n\nEscape only the leading single-quote. This renders properly in asciidoc\nand asciidoctor.\n\nSigned-off-by: Todd Zullinger \n---\n\nMaybe it would be easier to change the example commit messages\nand avoid having to nest single quotes within double quotes? I\ndon't know if that's much preferable to escaping only the opening\nsingle quote.\n\nI went with the more minimal change to avoid having to rewrite\nother bits of the example (and risk making them not match what\nusers would see if they ran similar commands).\n\nThis is another potential parsing bug in asciidoctor. Of course,\ndistros will have versions of asciidoctor in place for some time\nwhich have trouble parsing this doc. Since it's not much work\nfor us to adjust the text to work around it, that seemed\nreasonable.\n\n Documentation/git-show-branch.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 4a01371227..5cc2fcefba 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -167,7 +167,7 @@ $ git show-branch master fixes mhf\n ------------------------------------------------\n \n These three branches all forked from a common commit, [master],\n-whose commit message is \"Add {apostrophe}git show-branch{apostrophe}\".\n+whose commit message is \"Add \\'git show-branch'\".\n The \"fixes\" branch adds one commit \"Introduce \"reset type\" flag to\n \"git reset\"\". The \"mhf\" branch adds many other commits.\n The current branch is \"master\".\n"},{"id":"373274","messageId":"20190405225115.3882-3-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrbjRExHwch0K_W+xwpERnFUJmaiHhCkAaK9nnxFnXEhw@mail.gmail.com","subject":"[PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-05T22:51:15Z","receivedAt":"2019-04-05T22:51:32Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"The second paragraph in the CONFIGURATION section intends to emphasize\nthe word 'must' with bold type. Adjust the formatting slightly to\nprovide similar results between asciidoc and asciidoctor.\n\nSigned-off-by: Todd Zullinger \n---\nI debated changing 'must' from bold to italic in this hunk.\nThere are two other emphasized uses of 'must' in git-svn.txt.\nOne is bold and one is italic. So I left this one bold and\nsimply adjusted the \"'\" quotes to \"`\" around the \"*\" and \":\"\ncharacters. This is the more minimal fix to keep the output\nrendered the same in asciidoc and asciidoctor.\n\n Documentation/git-svn.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex b99029520d..81aaef8e4e 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -1100,10 +1100,10 @@ listed below are allowed:\n \ttags = tags/*/project-a:refs/remotes/project-a/tags/*\n ------------------------------------------------------------------------\n \n-Keep in mind that the '\\*' (asterisk) wildcard of the local ref\n-(right of the ':') *must* be the farthest right path component;\n+Keep in mind that the `*` (asterisk) wildcard of the local ref\n+(right of the `:`) *must* be the farthest right path component;\n however the remote wildcard may be anywhere as long as it's an\n-independent path component (surrounded by '/' or EOL). This\n+independent path component (surrounded by `/` or EOL). This\n type of configuration is not automatically created by 'init' and\n should be manually entered with a text-editor or using 'git config'.\n \n"},{"id":"373280","messageId":"CAN0heSrPx+_dB+NZzRzidZFpfLMpQUHk-Wi8rTaer+stam0NPA@mail.gmail.com","threadId":"50845","inReplyTo":"20190405225115.3882-1-tmz@pobox.com","subject":"Re: [PATCH 0/2] a few more minor asciidoc/tor formatting fixes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-06T09:16:36Z","receivedAt":"2019-04-06T09:16:52Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 6 Apr 2019 at 00:51, Todd Zullinger wrote:\n> Here's what I have currently. I haven't tested this much with\n> asciidoctor-1.5.x releases (or maybe not at all -- it's been a\n> week or so since I worked on this).\n\nTested with Asciidoctor 1.5.5. For both patches, AsciiDoctor stumbles\nbefore the patch, but not after it. Great. :-) For AsciiDoc 8.6.10, the\nfirst patch is a no-op, while the second patch makes the difference it\nintends to do. I'll follow up with comments on the individual patches.\n\nMartin\n"},{"id":"373281","messageId":"CAN0heSoNNb4QLqQfkgPZRBD2TJ3h1JM3udyRyHnuoOcWbe94Zg@mail.gmail.com","threadId":"50845","inReplyTo":"20190405225115.3882-2-tmz@pobox.com","subject":"Re: [PATCH 1/2] Documentation/git-show-branch: drop last use of {apostrophe}","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-06T09:21:22Z","receivedAt":"2019-04-06T09:21:37Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 6 Apr 2019 at 00:51, Todd Zullinger wrote:\n>\n> The {apostrophe} was needed at the time of a521845800 (\"Documentation:\n> remove stray backslash in show-branch discussion\", 2010-08-20). All\n> other uses of {apostrophe} were removed in 6cf378f0cb (\"docs: stop using\n> asciidoc no-inline-literal\", 2012-04-26).\n>\n> Escape only the leading single-quote. This renders properly in asciidoc\n> and asciidoctor.\n\nYou could perhaps say that \"{apostrophe}\" renders literally with\nAsciidoctor (at least with 1.5.5). Right now, you sort of undersell this\npatch. I know from context that you have some Asciidoctor \"issue\", but\nit's not clear from this patch alone.\n\n> ---\n>\n> Maybe it would be easier to change the example commit messages\n> and avoid having to nest single quotes within double quotes? I\n> don't know if that's much preferable to escaping only the opening\n> single quote.\n\nYeah, those commit messages are a bit unfortunate from the point of view\nof quoting. Avoiding all that nesting would probably improve the reading\nexperience, but I don't think that should hold up this patch.\n\n> This is another potential parsing bug in asciidoctor. Of course,\n> distros will have versions of asciidoctor in place for some time\n> which have trouble parsing this doc. Since it's not much work\n> for us to adjust the text to work around it, that seemed\n> reasonable.\n\nAgreed.\n\n\nMartin\n"},{"id":"373282","messageId":"CAN0heSpL_pQMtDaEdDgcsC_Sso45owHjRttrdp7cQdYOb7i9BA@mail.gmail.com","threadId":"50845","inReplyTo":"20190405225115.3882-3-tmz@pobox.com","subject":"Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2019-04-06T09:31:19Z","receivedAt":"2019-04-06T09:31:33Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 6 Apr 2019 at 00:51, Todd Zullinger wrote:\n>\n> The second paragraph in the CONFIGURATION section intends to emphasize\n> the word 'must' with bold type. Adjust the formatting slightly to\n> provide similar results between asciidoc and asciidoctor.\n\nI don't think this explains the problem you're solving well enough. It\nalso doesn't make it clear enough, IMHO, how what we're doing here\nsolves that problem. How about something like this?\n\n The second paragraph in the CONFIGURATION section intends to emphasize\n the word 'must' with bold type. It does so by writing it as *must*,\n and this works fine with AsciiDoc. It usually works great with\n Asciidoctor, too, but in this particular instance, we have another \"*\"\n earlier in the paragraph. We do escape it, and it is rendered\n literally just like we want it to, but Asciidoctor then ends up\n tripping on the second (or third) of the asterisks in this paragraph.\n\n Since that asterisk is (part of) a literal example, we can set it in\n monospace, by giving it as `*`. Adjust the whole paragraph in this\n way. There's lots more monospacing to be done in this document, but\n since our main motivation is addressing AsciiDoc/Asciidoctor\n discrepancies like this one, let's just convert this one paragraph.\n\nI think what's happening could be related to the fix in the first patch.\nThere, it's ok to explicitly escape only the first '. The second one is\nmatched to it and gets escaped implicitly. Something like that could be\nhappening here, too, just that we don't want it to. (Should we escape\nthe implicit escaping? ...) Just speculation, though.\n\n\nMartin\n"},{"id":"373546","messageId":"20190410003734.17124-2-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrPx+_dB+NZzRzidZFpfLMpQUHk-Wi8rTaer+stam0NPA@mail.gmail.com","subject":"[PATCH v2 1/2] Documentation/git-show-branch: avoid literal {apostrophe}","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-10T00:37:33Z","receivedAt":"2019-04-10T00:37:43Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"The {apostrophe} was needed at the time of a521845800 (\"Documentation:\nremove stray backslash in show-branch discussion\", 2010-08-20). All\nother uses of {apostrophe} were removed in 6cf378f0cb (\"docs: stop using\nasciidoc no-inline-literal\", 2012-04-26).\n\nUnfortunately, the {apostrophe} is rendered literally with Asciidoctor\n(at least with 1.5.5-2.0.3). Avoid this by using single-quotes.\n\nEscaping the leading single-quote allows the content to render properly\nin AsciiDoc and Asciidoctor.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-show-branch.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 4a01371227..5cc2fcefba 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -167,7 +167,7 @@ $ git show-branch master fixes mhf\n ------------------------------------------------\n \n These three branches all forked from a common commit, [master],\n-whose commit message is \"Add {apostrophe}git show-branch{apostrophe}\".\n+whose commit message is \"Add \\'git show-branch'\".\n The \"fixes\" branch adds one commit \"Introduce \"reset type\" flag to\n \"git reset\"\". The \"mhf\" branch adds many other commits.\n The current branch is \"master\".\n"},{"id":"373547","messageId":"20190410003734.17124-3-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrPx+_dB+NZzRzidZFpfLMpQUHk-Wi8rTaer+stam0NPA@mail.gmail.com","subject":"[PATCH v2 2/2] Documentation/git-svn: improve asciidoctor compatibility","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-10T00:37:34Z","receivedAt":"2019-04-10T00:37:45Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"The second paragraph in the CONFIGURATION section intends to emphasize\nthe word 'must' with bold type. It does so by writing it as *must*, and\nthis works fine with AsciiDoc. It usually works great with Asciidoctor,\ntoo, but in this particular instance, we have another \"*\" earlier in the\nparagraph. We do escape it, and it is rendered literally just like we\nwant it to, but Asciidoctor then ends up tripping on the second (or\nthird) of the asterisks in this paragraph.\n\nSince that asterisk is (part of) a literal example, we can set it in\nmonospace, by giving it as `*`. Adjust the whole paragraph in this way.\nThere's lots more monospacing to be done in this document, but since our\nmain motivation is addressing AsciiDoc/Asciidoctor discrepancies like\nthis one, let's just convert this one paragraph.\n\nSigned-off-by: Todd Zullinger \n---\n Documentation/git-svn.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex b99029520d..81aaef8e4e 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -1100,10 +1100,10 @@ listed below are allowed:\n \ttags = tags/*/project-a:refs/remotes/project-a/tags/*\n ------------------------------------------------------------------------\n \n-Keep in mind that the '\\*' (asterisk) wildcard of the local ref\n-(right of the ':') *must* be the farthest right path component;\n+Keep in mind that the `*` (asterisk) wildcard of the local ref\n+(right of the `:`) *must* be the farthest right path component;\n however the remote wildcard may be anywhere as long as it's an\n-independent path component (surrounded by '/' or EOL). This\n+independent path component (surrounded by `/` or EOL). This\n type of configuration is not automatically created by 'init' and\n should be manually entered with a text-editor or using 'git config'.\n \n"},{"id":"373548","messageId":"20190410003734.17124-1-tmz@pobox.com","threadId":"50845","inReplyTo":"CAN0heSrPx+_dB+NZzRzidZFpfLMpQUHk-Wi8rTaer+stam0NPA@mail.gmail.com","subject":"[PATCH v2 0/2] a few more minor asciidoc/tor formatting fixes","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-10T00:37:32Z","receivedAt":"2019-04-10T00:37:46Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi,\n\nMartin Ågren wrote:\n> On Sat, 6 Apr 2019 at 00:51, Todd Zullinger wrote:\n>> Here's what I have currently. I haven't tested this much with\n>> asciidoctor-1.5.x releases (or maybe not at all -- it's been a\n>> week or so since I worked on this).\n> \n> Tested with Asciidoctor 1.5.5. For both patches, AsciiDoctor stumbles\n> before the patch, but not after it. Great. :-) For AsciiDoc 8.6.10, the\n> first patch is a no-op, while the second patch makes the difference it\n> intends to do. I'll follow up with comments on the individual patches.\n\nThanks for testing these against older Asciidoctor and for the\nhelpful feedback on the commit messages. \n\nI reworded the message in the first commit to make it clearer\nthat Asciidoctor renders the {apostrophe} literally. I updated\nthe body of the second commit using your suggested wording. It\nwas much better than the original. :)\n\nThe contents of each commit remain unchanged.\n\nTodd Zullinger (2):\n Documentation/git-show-branch: avoid literal {apostrophe}\n Documentation/git-svn: improve asciidoctor compatibility\n\n Documentation/git-show-branch.txt | 2 +-\n Documentation/git-svn.txt | 6 +++---\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\nRange-diff against v1:\n1: 70e3339859 ! 1: da553a596c Documentation/git-show-branch: drop last use of {apostrophe}\n @@ -1,14 +1,17 @@\n Author: Todd Zullinger \n \n - Documentation/git-show-branch: drop last use of {apostrophe}\n + Documentation/git-show-branch: avoid literal {apostrophe}\n \n The {apostrophe} was needed at the time of a521845800 (\"Documentation:\n remove stray backslash in show-branch discussion\", 2010-08-20). All\n other uses of {apostrophe} were removed in 6cf378f0cb (\"docs: stop using\n asciidoc no-inline-literal\", 2012-04-26).\n \n - Escape only the leading single-quote. This renders properly in asciidoc\n - and asciidoctor.\n + Unfortunately, the {apostrophe} is rendered literally with Asciidoctor\n + (at least with 1.5.5-2.0.3). Avoid this by using single-quotes.\n +\n + Escaping the leading single-quote allows the content to render properly\n + in AsciiDoc and Asciidoctor.\n \n Signed-off-by: Todd Zullinger \n \n2: e8f6f873bc ! 2: 6fd412bd97 Documentation/git-svn: improve asciidoctor compatibility\n @@ -3,8 +3,18 @@\n Documentation/git-svn: improve asciidoctor compatibility\n \n The second paragraph in the CONFIGURATION section intends to emphasize\n - the word 'must' with bold type. Adjust the formatting slightly to\n - provide similar results between asciidoc and asciidoctor.\n + the word 'must' with bold type. It does so by writing it as *must*, and\n + this works fine with AsciiDoc. It usually works great with Asciidoctor,\n + too, but in this particular instance, we have another \"*\" earlier in the\n + paragraph. We do escape it, and it is rendered literally just like we\n + want it to, but Asciidoctor then ends up tripping on the second (or\n + third) of the asterisks in this paragraph.\n +\n + Since that asterisk is (part of) a literal example, we can set it in\n + monospace, by giving it as `*`. Adjust the whole paragraph in this way.\n + There's lots more monospacing to be done in this document, but since our\n + main motivation is addressing AsciiDoc/Asciidoctor discrepancies like\n + this one, let's just convert this one paragraph.\n \n Signed-off-by: Todd Zullinger \n \n-- \nTodd\n"},{"id":"373549","messageId":"20190410004117.GM3654@pobox.com","threadId":"50845","inReplyTo":"CAN0heSpL_pQMtDaEdDgcsC_Sso45owHjRttrdp7cQdYOb7i9BA@mail.gmail.com","subject":"Re: [PATCH 2/2] Documentation/git-svn: improve asciidoctor compatibility","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2019-04-10T00:41:17Z","receivedAt":"2019-04-10T00:41:26Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Martin Ågren wrote:\n> I think what's happening could be related to the fix in the first patch.\n> There, it's ok to explicitly escape only the first '. The second one is\n> matched to it and gets escaped implicitly. Something like that could be\n> happening here, too, just that we don't want it to. (Should we escape\n> the implicit escaping? ...) Just speculation, though.\n\nIt could well be a similar issue. I think I tried adding an\nescape to the existing \\* and/or to elsewhere in the block\nof text, without success. But I didn't try very hard\nthough, as adjusting the test to use `*` seemed like an\nimprovement.\n\nThanks,\n\n-- \nTodd\n"},{"id":"373563","messageId":"xmqqef6a369n.fsf@gitster-ct.c.googlers.com","threadId":"50845","inReplyTo":"20190410003734.17124-1-tmz@pobox.com","subject":"Re: [PATCH v2 0/2] a few more minor asciidoc/tor formatting fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-04-10T03:09:56Z","receivedAt":"2019-04-10T03:10:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Todd Zullinger writes:\n\n> Thanks for testing these against older Asciidoctor and for the\n> helpful feedback on the commit messages. \n>\n> I reworded the message in the first commit to make it clearer\n> that Asciidoctor renders the {apostrophe} literally. I updated\n> the body of the second commit using your suggested wording. It\n> was much better than the original. :)\n\nThanks, will replace.\n"}]}