{"thread":{"id":"55685","subject":"[PATCH 0/6] AsciiDoc vs Asciidoctor, once again","startedAt":"2021-05-13T18:18:06Z","lastAt":"2021-05-14T20:11:45Z","messageCount":22,"participants":["Martin Ågren","Eric Sunshine","Junio C Hamano","Felipe Contreras","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"424487","messageId":"cover.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":null,"subject":"[PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:39Z","receivedAt":"2021-05-13T18:18:06Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"These patches reduce\n\n ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD\n\nfrom ~1200 to ~1000 lines. It's the usual mix of things where one or the\nother of the tools renders something less well, or where we're doing\nsomething odd in the source and we just happen to notice it in the diff.\n\nMy ulterior motive here is to have a smaller doc-diff when I post a\npatch to switch the default to Asciidoctor (with xmlto), so that it gets\na bit easier to reason about. But if everybody gets prettier docs,\nthat's also good.\n\nSome of these rephrase wording such as \"other peoples' commits\" to avoid\nthat apostrophe at the end of a word. I'm hoping those rephrasings don't\nregress the quality of the text -- if they do, I'll be happy to try\nsomething else.\n\nMartin Ågren (6):\n git-http-push.txt,git-send-pack.txt: avoid single quote\n git-range-diff.txt: avoid single quotes\n git-check-ref-format.txt: avoid single quote\n diff-options.txt: move monospace markup out of attribute\n git-svn.txt: change verse to listing block\n Doc: use two backticks for monospace, not backtick+apostrophe\n\n Documentation/config/diff.txt | 2 +-\n Documentation/diff-options.txt | 2 +-\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-check-ref-format.txt | 6 +--\n Documentation/git-describe.txt | 2 +-\n Documentation/git-http-push.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-range-diff.txt | 6 +--\n Documentation/git-send-pack.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n Documentation/git-svn.txt | 51 +++++++++++++++++---------\n 11 files changed, 47 insertions(+), 32 deletions(-)\n\n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424488","messageId":"04e2d9de24db1e69803c495710f1f0908a12c91a.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 1/6] git-http-push.txt,git-send-pack.txt: avoid single quote","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:40Z","receivedAt":"2021-05-13T18:18:08Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"AsciiDoc matches up the very first backtick with the single quote\ntowards the end, and renders that first backtick literally:\n\n `--force, ... other peoples' commits\n\nRewrite the \"other peoples' commits\" construction to drop the single\nquote mark.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-http-push.txt | 2 +-\n Documentation/git-send-pack.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt\nindex ea03a4eeb0..cbb7d2de6d 100644\n--- a/Documentation/git-http-push.txt\n+++ b/Documentation/git-http-push.txt\n@@ -85,7 +85,7 @@ Without `--force`, the ref is stored at the remote only if\n does not exist, or is a proper subset (i.e. an\n ancestor) of . This check, known as \"fast-forward check\",\n is performed in order to avoid accidentally overwriting the\n-remote ref and lose other peoples' commits from there.\n+remote ref and losing commits of other people from there.\n \n With `--force`, the fast-forward check is disabled for all refs.\n \ndiff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt\nindex 44fd146b91..d8c8acb96e 100644\n--- a/Documentation/git-send-pack.txt\n+++ b/Documentation/git-send-pack.txt\n@@ -144,7 +144,7 @@ Without `--force`, the ref is stored at the remote only if\n does not exist, or is a proper subset (i.e. an\n ancestor) of . This check, known as \"fast-forward check\",\n is performed in order to avoid accidentally overwriting the\n-remote ref and lose other peoples' commits from there.\n+remote ref and losing commits of other people from there.\n \n With `--force`, the fast-forward check is disabled for all refs.\n \n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424489","messageId":"187b7290cfb516b957762e82538e64abda255cd3.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 2/6] git-range-diff.txt: avoid single quotes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:41Z","receivedAt":"2021-05-13T18:18:11Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Similar to the previous commit, the use of backticks for monospacing and\na single quote as an apostrophe trip up AsciiDoc in two places which\nrender as follows:\n\n `git range-diff ... diffs' coloring\n\n ‘1` is ... commits' patches\n\nReword slighly to avoid those last single quotes.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-range-diff.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt\nindex fe350d7f40..6e9a0ea6b6 100644\n--- a/Documentation/git-range-diff.txt\n+++ b/Documentation/git-range-diff.txt\n@@ -45,7 +45,7 @@ OPTIONS\n -------\n --no-dual-color::\n \tWhen the commit diffs differ, `git range-diff` recreates the\n-\toriginal diffs' coloring, and adds outer -/+ diff markers with\n+\tcoloring of the original diffs, and adds outer -/+ diff markers with\n \tthe *background* being red/green to make it easier to see e.g.\n \twhen there was a change in what exact lines were added.\n +\n@@ -239,8 +239,8 @@ because of the modification:\n In mathematical terms, what we are looking for is some sort of a minimum\n cost bipartite matching; `1` is matched to `C` at some cost, etc. The\n underlying graph is in fact a complete bipartite graph; the cost we\n-associate with every edge is the size of the diff between the two\n-commits' patches. To explain also new commits, we introduce dummy nodes\n+associate with every edge is the size of the diff between the patches of\n+the two commits. To explain also new commits, we introduce dummy nodes\n on both sides:\n \n ------------\n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424490","messageId":"f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:42Z","receivedAt":"2021-05-13T18:18:15Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Asciidoctor renders 'git cat-file' with the single quotes. It's somehow\ntricked by the single quote in \"srcref\\'s\" earler in the paragraph. If\nwe drop the backslash, we'll regress with AsciiDoc. Let's just rewrite\nthings a bit to avoid \"srcref's\" entirely.\n\nAdd backticks for monospacing around these refs and command invocations\nwhile at it.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-check-ref-format.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt\nindex ee6a4144fb..71d53ffb60 100644\n--- a/Documentation/git-check-ref-format.txt\n+++ b/Documentation/git-check-ref-format.txt\n@@ -70,10 +70,10 @@ reference name expressions (see linkgit:gitrevisions[7]):\n . A tilde `~` and caret `^` are used to introduce the postfix\n 'nth parent' and 'peel onion' operation.\n \n-. A colon `:` is used as in `srcref:dstref` to mean \"use srcref\\'s\n- value and store it in dstref\" in fetch and push operations.\n+. A colon `:` is used as in `srcref:dstref` to mean \"use the value\n+ of `srcref` and store it in `dstref`\" in fetch and push operations.\n It may also be used to select a specific object such as with\n- 'git cat-file': \"git cat-file blob v1.3.3:refs.c\".\n+ 'git cat-file': `git cat-file blob v1.3.3:refs.c`.\n \n . at-open-brace `@{` is used as a notation to access a reflog entry.\n \n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424491","messageId":"f6241315a4d90185882a247d1c81ed7ee595d9a9.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 4/6] diff-options.txt: move monospace markup out of attribute","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:43Z","receivedAt":"2021-05-13T18:18:23Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"git-log.txt and git-show.txt want to use different defaults for the\n`--no-diff-merges` option. They do this by defining a\n\"diff-merges-default\" attribute as, e.g., `off` (with backticks), which\nis then referenced in the common diff-options.txt.\n\nAsciiDoc renders the default in monospace, as wanted, but Asciidoctor\nrenders the backticks literally.\n\nPull the formatting into diff-options.txt and define\n\"diff-merges-default\" without any quotation or markup. We can't write\n`{diff-merges-default)` with backticks since that would render as\n\"{diff-merges-default}\", but we can use +{diff-merges-default}+ -- both\nAsciidoc and Asciidoctor do the substitution and the parsing of the\nplusses in the order we want.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/diff-options.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 530d115914..6eb8bfff5d 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -37,7 +37,7 @@ ifdef::git-log[]\n --diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc)::\n --no-diff-merges::\n \tSpecify diff format to be used for merge commits. Default is\n-\t{diff-merges-default} unless `--first-parent` is in use, in which case\n+\t+{diff-merges-default}+ unless `--first-parent` is in use, in which case\n \t`first-parent` is the default.\n +\n --diff-merges=(off|none):::\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 1bbf865a1b..19560650bf 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -115,7 +115,7 @@ is when `--first-parent` is in use, in which case `first-parent` is\n the default format.\n \n :git-log: 1\n-:diff-merges-default: `off`\n+:diff-merges-default: off\n include::diff-options.txt[]\n \n include::diff-generate-patch.txt[]\ndiff --git a/Documentation/git-show.txt b/Documentation/git-show.txt\nindex 2b1bc7288d..f8341e51c0 100644\n--- a/Documentation/git-show.txt\n+++ b/Documentation/git-show.txt\n@@ -51,7 +51,7 @@ The options below can be used to change the way `git show` generates\n diff output.\n \n :git-log: 1\n-:diff-merges-default: `dense-combined`\n+:diff-merges-default: dense-combined\n include::diff-options.txt[]\n \n include::diff-generate-patch.txt[]\n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424492","messageId":"96c5a7ce800b37306274a6725ad44582fefb06a8.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 5/6] git-svn.txt: change verse to listing block","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:44Z","receivedAt":"2021-05-13T18:18:28Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Unlike AsciiDoc, Asciidoctor seems to leave out an empty line after a verse\nin a list continuation:\n\n allow only certain refs.\n\n config key: svn-remote..ignore-refs\n If the ignore-refs configuration key is ...\n\nWe could probably convince Asciidoctor do this differently, but thinking\nabout it, there's no real reason for a \"verse\" here. We might as well\nuse a listing block.\n\nThis is the only place in our documentation that uses this \"config key:\nfoo.bar\" construction. We could rework it into prose (\"This option\noverrides the foo.bar configuration, which defaults to baz.\"). Right\nnow, let's just solve the immediate issue of the missing empty line when\nwe use Asciidoctor to generate the manpage.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-svn.txt | 45 ++++++++++++++++++++++++++-------------\n 1 file changed, 30 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex d5776ffcfd..4e62dc37e7 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -148,8 +148,9 @@ the same local time zone.\n \t`^refs/remotes/origin/(?!tags/wanted-tag|wanted-branch).*$`\n \tcan be used to allow only certain refs.\n +\n-[verse]\n+------------\n config key: svn-remote..ignore-refs\n+------------\n +\n If the ignore-refs configuration key is set, and the command-line\n option is also given, both regular expressions will be used.\n@@ -161,8 +162,9 @@ option is also given, both regular expressions will be used.\n \t(including automatic fetches due to 'clone', 'dcommit',\n \t'rebase', etc) on a given repository.\n +\n-[verse]\n+------------\n config key: svn-remote..ignore-paths\n+------------\n +\n If the ignore-paths configuration key is set, and the command-line\n option is also given, both regular expressions will be used.\n@@ -191,8 +193,9 @@ Skip \"branches\" and \"tags\" of first level directories;;\n \t'rebase', etc) on a given repository. `--ignore-paths` takes\n \tprecedence over `--include-paths`.\n +\n-[verse]\n+------------\n config key: svn-remote..include-paths\n+------------\n \n --log-window-size=;;\n \tFetch log entries per request when scanning Subversion history.\n@@ -267,9 +270,10 @@ Use of 'dcommit' is preferred to 'set-tree' (below).\n \treused if a user is later given access to an alternate transport\n \tmethod (e.g. `svn+ssh://` or `https://`) for commit.\n +\n-[verse]\n+------------\n config key: svn-remote..commiturl\n config key: svn.commiturl (overwrites all svn-remote..commiturl options)\n+------------\n +\n Note that the SVN URL of the commiturl config key includes the SVN branch.\n If you rather want to set the commit URL for an entire SVN repository use\n@@ -286,8 +290,9 @@ discouraged.\n \tbranches, use a single space character between the branches\n \t(`--mergeinfo=\"/branches/foo:1-10 /branches/bar:3,5-6,8\"`)\n +\n-[verse]\n+------------\n config key: svn.pushmergeinfo\n+------------\n +\n This option will cause git-svn to attempt to automatically populate the\n svn:mergeinfo property in the SVN repository when possible. Currently, this can\n@@ -548,9 +553,10 @@ Assume you have local changes in \"master\", but you need to refetch \"r2\".\n Fix the ignore-paths or SVN permissions problem that caused \"r2\" to\n be incomplete in the first place. Then:\n +\n-[verse]\n+------------\n git svn reset -r2 -p\n git svn fetch\n+------------\n +\n ------------\n r1---r2'--r3' remotes/git-svn\n@@ -562,8 +568,9 @@ Then fixup \"master\" with 'git rebase'.\n Do NOT use 'git merge' or your history will not be compatible with a\n future 'dcommit'!\n +\n-[verse]\n+------------\n git rebase --onto remotes/git-svn A^ master\n+------------\n +\n ------------\n r1---r2'--r3' remotes/git-svn\n@@ -608,8 +615,9 @@ removed by default if there are no files left in them. Git\n cannot version empty directories. Enabling this flag will make\n the commit to SVN act like Git.\n +\n-[verse]\n+------------\n config key: svn.rmdir\n+------------\n \n -e::\n --edit::\n@@ -619,8 +627,9 @@ Edit the commit message before committing to SVN. This is off by\n default for objects that are commits, and forced on when committing\n tree objects.\n +\n-[verse]\n+------------\n config key: svn.edit\n+------------\n \n -l::\n --find-copies-harder::\n@@ -629,9 +638,10 @@ config key: svn.edit\n They are both passed directly to 'git diff-tree'; see\n linkgit:git-diff-tree[1] for more information.\n +\n-[verse]\n+------------\n config key: svn.l\n config key: svn.findcopiesharder\n+------------\n \n -A::\n --authors-file=::\n@@ -648,8 +658,9 @@ will abort operation. The user will then have to add the\n appropriate entry. Re-running the previous 'git svn' command\n after the authors-file is modified should continue operation.\n +\n-[verse]\n+------------\n config key: svn.authorsfile\n+------------\n \n --authors-prog=::\n \tIf this option is specified, for each SVN committer name that\n@@ -664,8 +675,9 @@ relative to the current directory for 'init' and 'clone' and relative\n to the root of the working tree for 'fetch'. If 'filename' is\n not found, it is searched like any other command in '$PATH'.\n +\n-[verse]\n+------------\n config key: svn.authorsProg\n+------------\n \n -q::\n --quiet::\n@@ -704,8 +716,9 @@ creating the branch or tag.\n \t'dcommit' operations), look for the first `From:` line or `Signed-off-by` trailer\n \tin the log message and use that as the author string.\n +\n-[verse]\n+------------\n config key: svn.useLogAuthor\n+------------\n \n --add-author-from::\n \tWhen committing to svn from Git (as part of 'set-tree' or 'dcommit'\n@@ -714,8 +727,9 @@ config key: svn.useLogAuthor\n \tGit commit's author string. If you use this, then `--use-log-author`\n \twill retrieve a valid author string for all commits.\n +\n-[verse]\n+------------\n config key: svn.addAuthorFrom\n+------------\n \n ADVANCED OPTIONS\n ----------------\n@@ -749,8 +763,9 @@ ADVANCED OPTIONS\n \tprocess. This feature is enabled by default, use\n \t--no-follow-parent to disable it.\n +\n-[verse]\n+------------\n config key: svn.followparent\n+------------\n \n CONFIG FILE-ONLY OPTIONS\n ------------------------\n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424493","messageId":"f0af6c8f6aeb765a2670cc6c097059c591cdcedc.1620928059.git.martin.agren@gmail.com","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"[PATCH 6/6] Doc: use two backticks for monospace, not backtick+apostrophe","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T18:17:45Z","receivedAt":"2021-05-13T18:18:32Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"In a few places, we wrap the name of an --option or an ENV_VARIABLE in\nbacktick+apostrophe rather than backtick+backtick. Switch to using\ntwo backticks, as per the coding guidelines.\n\nAs an added bonus to rendering these as monospace, we will have them\nrender the same with AsciiDoc and Asciidoctor. The `quoted' way ends up\nas ‘quoted’ vs “quoted”.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/config/diff.txt | 2 +-\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-describe.txt | 2 +-\n Documentation/git-svn.txt | 6 +++---\n 4 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 2d3331f55c..eda0c452d1 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -69,7 +69,7 @@ diff.interHunkContext::\n diff.external::\n \tIf this config variable is set, diff generation is not\n \tperformed using the internal diff machinery, but using the\n-\tgiven command. Can be overridden with the `GIT_EXTERNAL_DIFF'\n+\tgiven command. Can be overridden with the `GIT_EXTERNAL_DIFF`\n \tenvironment variable. The command is called with parameters\n \tas described under \"git Diffs\" in linkgit:git[1]. Note: if\n \tyou want to use an external diff program only on a subset of\ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex 0c3924a63d..ab97ee9d50 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -21,7 +21,7 @@ input files to the exclude mechanism) and output the path if it is\n excluded.\n \n By default, tracked files are not shown at all since they are not\n-subject to exclude rules; but see `--no-index'.\n+subject to exclude rules; but see `--no-index`.\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt\nindex a88f6ae2c6..adbbb8907f 100644\n--- a/Documentation/git-describe.txt\n+++ b/Documentation/git-describe.txt\n@@ -44,7 +44,7 @@ OPTIONS\n \tHEAD\". If the working tree has local modification \"-dirty\"\n \tis appended to it. If a repository is corrupt and Git\n \tcannot determine if there is local modification, Git will\n-\terror out, unless `--broken' is given, which appends\n+\terror out, unless `--broken` is given, which appends\n \tthe suffix \"-broken\" instead.\n \n --all::\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 4e62dc37e7..2491ed47a6 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -361,7 +361,7 @@ where is the name of the SVN repository as specified by the -R option to\n \tThis should make it easy to look up svn log messages when svn\n \tusers refer to -r/--revision numbers.\n +\n-The following features from `svn log' are supported:\n+The following features from `svn log` are supported:\n +\n --\n -r [:];;\n@@ -397,7 +397,7 @@ Any other arguments are passed directly to 'git log'\n 'blame'::\n \tShow what revision and author last modified each line of a file. The\n \toutput of this mode is format-compatible with the output of\n-\t`svn blame' by default. Like the SVN blame command,\n+\t`svn blame` by default. Like the SVN blame command,\n \tlocal uncommitted changes in the working tree are ignored;\n \tthe version of the file in the HEAD revision is annotated. Unknown\n \targuments are passed directly to 'git blame'.\n@@ -482,7 +482,7 @@ denotes such an object, or it is requested by invoking an editor (see\n \n 'info'::\n \tShows information about a file or directory similar to what\n-\t`svn info' provides. Does not currently support a -r/--revision\n+\t`svn info` provides. Does not currently support a -r/--revision\n \targument. Use the --url option to output only the value of the\n \t'URL:' field.\n \n-- \n2.31.1.751.gd2f1c929bd\n\n"},{"id":"424496","messageId":"CAPig+cSKod_dL7Cm+=T_TPdTxxcV6mz2d+ktm4i1SEUJxQWUqg@mail.gmail.com","threadId":"55685","inReplyTo":"f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-05-13T19:16:01Z","receivedAt":"2021-05-13T19:16:14Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 13, 2021 at 2:18 PM Martin Ågren wrote:\n> Asciidoctor renders 'git cat-file' with the single quotes. It's somehow\n> tricked by the single quote in \"srcref\\'s\" earler in the paragraph. If\n\ns/earler/earlier/\n\n> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite\n> things a bit to avoid \"srcref's\" entirely.\n>\n> Add backticks for monospacing around these refs and command invocations\n> while at it.\n>\n> Signed-off-by: Martin Ågren \n"},{"id":"424498","messageId":"CAN0heSo0u9z8yFjWHFQ6rub2xTKy8B5zitjbaQm8o+1-xzaG8g@mail.gmail.com","threadId":"55685","inReplyTo":"CAPig+cSKod_dL7Cm+=T_TPdTxxcV6mz2d+ktm4i1SEUJxQWUqg@mail.gmail.com","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T19:35:16Z","receivedAt":"2021-05-13T19:35:32Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 13 May 2021 at 21:16, Eric Sunshine wrote:\n>\n> On Thu, May 13, 2021 at 2:18 PM Martin Ågren wrote:\n> > Asciidoctor renders 'git cat-file' with the single quotes. It's somehow\n> > tricked by the single quote in \"srcref\\'s\" earler in the paragraph. If\n>\n> s/earler/earlier/\n\nOops. Thanks!\n"},{"id":"424508","messageId":"xmqqsg2q9xts.fsf@gitster.g","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T20:35:11Z","receivedAt":"2021-05-13T20:35:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> These patches reduce\n>\n> ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD\n>\n> from ~1200 to ~1000 lines. It's the usual mix of things where one or the\n> other of the tools renders something less well, or where we're doing\n> something odd in the source and we just happen to notice it in the diff.\n>\n> My ulterior motive here is to have a smaller doc-diff when I post a\n> patch to switch the default to Asciidoctor (with xmlto), so that it gets\n> a bit easier to reason about. But if everybody gets prettier docs,\n> that's also good.\n>\n> Some of these rephrase wording such as \"other peoples' commits\" to avoid\n> that apostrophe at the end of a word. I'm hoping those rephrasings don't\n> regress the quality of the text -- if they do, I'll be happy to try\n> something else.\n\nIt is sad, but we really should try \"something else\", unfortunately.\n\nI do agree with the \"motive\" very much---even though condensing it\ndown to plain text before running comparison already loses too much\ninformation, doc-diff is the only tool we currently have to\neffectively review regressions in rendered document, and the\nproposed transition cannot be done safely with confidence without\nbeing able to vet the differences. I am happy to hear about 17%\nreduction already, but the requirement to rewrite things like \"other\npeoples' commits\" is a dealbreaker.\n\nI am not so worried about the existing text you rewrote in these\npatches. I however do not want to see asciidoc(tor) dictating use\nof a strange dialect of English when we write new documentation or\nupdate existing ones by imposing rules like \"you are not allowed to\nuse apostrophe-es to express possessive, and instead use 'of'\"; it\nwill become a continuing burden for anybody who writes documentation\nfor us.\n\nA typesettig rule like \"instead of double-dashes --, use {litdd}\" is\nan acceptable way out. At least that wouldn't constrain what the\nfinal product that gets delivered to the end-users can say.\n\nThanks.\n"},{"id":"424520","messageId":"xmqqzgwy8faq.fsf@gitster.g","threadId":"55685","inReplyTo":"f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T22:00:45Z","receivedAt":"2021-05-13T22:00:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> Asciidoctor renders 'git cat-file' with the single quotes.\n\nI somehow find this sentence a bit hard to grok. Do you mean\n\"instead of typesetting them emphasized, the two-word phrase is\nenclosed in a pair of literal single quotes\"?\n\n> It's somehow\n> tricked by the single quote in \"srcref\\'s\" earler in the paragraph. If\n> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite\n> things a bit to avoid \"srcref's\" entirely.\n\nI also was puzzled by this one and the previous \"cat-file\" thing,\nmostly because I couldn't tell if this is an unrelated problem that\nhappens to be around the same single-quote letter, or somehow\nhappens only because the single-quoted 'cat-file' was nearby, until\nI checked the patch text (and it seems that this is \"here is another\nproblem around apostrophe\").\n\n> Add backticks for monospacing around these refs and command invocations\n> while at it.\n\nI have no problem with this particular rephrasing from \"srcref's\nvalue\" to \"value of srcref\", but forbidding possessive \"'s\" from any\nfuture documentation is troubling.\n\n> -. A colon `:` is used as in `srcref:dstref` to mean \"use srcref\\'s\n> - value and store it in dstref\" in fetch and push operations.\n> +. A colon `:` is used as in `srcref:dstref` to mean \"use the value\n> + of `srcref` and store it in `dstref`\" in fetch and push operations.\n> It may also be used to select a specific object such as with\n> - 'git cat-file': \"git cat-file blob v1.3.3:refs.c\".\n> + 'git cat-file': `git cat-file blob v1.3.3:refs.c`.\n\nThe proposed log message did not explain why you wanted to avoid\ndouble-quote pair on the \"cat-file\" line. Is this meant as a\nworkaround for the \"single quotes are shown around git cat-file\"\nissue?\n\nThanks.\n"},{"id":"424538","messageId":"609dd5171e7de_19566208ca@natae.notmuch","threadId":"55685","inReplyTo":"cover.1620928059.git.martin.agren@gmail.com","subject":"RE: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-14T01:40:39Z","receivedAt":"2021-05-14T01:40:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> These patches reduce\n> \n> ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD\n> \n> from ~1200 to ~1000 lines. It's the usual mix of things where one or the\n> other of the tools renders something less well, or where we're doing\n> something odd in the source and we just happen to notice it in the diff.\n\nThese changes are good, but what happens the next time somebody\ninadvertedly introduces something that \"trips\" asciidoctor?\n\nWe should be submitting bug reports to the asciidoctor project as well,\nso in the future it's less likely we find ourselves in the same\nscenario.\n\nPreferably the bug report should be in the commit message.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"424543","messageId":"YJ4K4UXh6sva5I4H@coredump.intra.peff.net","threadId":"55685","inReplyTo":"f2a78267fd0f424c5cfa6969c891597af4d5171f.1620928059.git.martin.agren@gmail.com","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-14T05:30:09Z","receivedAt":"2021-05-14T05:30:15Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, May 13, 2021 at 08:17:42PM +0200, Martin Ågren wrote:\n\n> -. A colon `:` is used as in `srcref:dstref` to mean \"use srcref\\'s\n> - value and store it in dstref\" in fetch and push operations.\n> +. A colon `:` is used as in `srcref:dstref` to mean \"use the value\n> + of `srcref` and store it in `dstref`\" in fetch and push operations.\n> It may also be used to select a specific object such as with\n> - 'git cat-file': \"git cat-file blob v1.3.3:refs.c\".\n> + 'git cat-file': `git cat-file blob v1.3.3:refs.c`.\n\nI'd perhaps write:\n\n `srcref`'s value...\n\nbut I'm a little afraid to see how it is handled by the various parsers\n(I'd write it because it does look OK in most markdown parsers I've\nused).\n\nThat said, I think in this case \"value of `srcref`\" is actually an\nimprovement to the text (but I wouldn't say the same of the earlier\npatches, which feel like they are making things clunkier).\n\n-Peff\n"},{"id":"424550","messageId":"CAN0heSrzkexY9K=VD=y0h9D0pVh59BjaLLg0pEo-WxsP+s0juA@mail.gmail.com","threadId":"55685","inReplyTo":"xmqqsg2q9xts.fsf@gitster.g","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-14T08:40:17Z","receivedAt":"2021-05-14T08:40:32Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 13 May 2021 at 22:35, Junio C Hamano wrote:\n>\n> Martin Ågren writes:\n>\n> > Some of these rephrase wording such as \"other peoples' commits\" to avoid\n> > that apostrophe at the end of a word. I'm hoping those rephrasings don't\n> > regress the quality of the text -- if they do, I'll be happy to try\n> > something else.\n>\n> It is sad, but we really should try \"something else\", unfortunately.\n>\n> I do agree with the \"motive\" very much---even though condensing it\n> down to plain text before running comparison already loses too much\n> information, doc-diff is the only tool we currently have to\n> effectively review regressions in rendered document, and the\n> proposed transition cannot be done safely with confidence without\n> being able to vet the differences. I am happy to hear about 17%\n> reduction already, but the requirement to rewrite things like \"other\n> peoples' commits\" is a dealbreaker.\n\nOK, calling it a dealbreaker is fair. Thanks.\n\n> A typesettig rule like \"instead of double-dashes --, use {litdd}\" is\n> an acceptable way out. At least that wouldn't constrain what the\n> final product that gets delivered to the end-users can say.\n\nI've done some experimenting now with a new attribute \"apos\" which\nexpands to a lone SQ. It seems to work fine across the different tools.\nThe rule could be that all ' should be {apos}. That's a quite\naggressive rule in a sense. It could be narrowed down to something like\n\"... if the paragraph contains other quotation, such as backticks or\nsingle quotes\", but that's probably just overly complicating things.\n\nI don't see an immediate need to go s/'/{apos}/ just because we can.\nWe've identified five problematic spots, four of which are with the tool\nwe're moving away from.\n\nMartin\n"},{"id":"424551","messageId":"CAN0heSoK5VfP68Us2e2bwSfTzY=5FBEBjxuTHRXeA_qg5MH65w@mail.gmail.com","threadId":"55685","inReplyTo":"609dd5171e7de_19566208ca@natae.notmuch","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-14T08:43:41Z","receivedAt":"2021-05-14T08:43:56Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Fri, 14 May 2021 at 03:40, Felipe Contreras\n wrote:\n\n> We should be submitting bug reports to the asciidoctor project as well,\n> so in the future it's less likely we find ourselves in the same\n> scenario.\n>\n> Preferably the bug report should be in the commit message.\n\nI don't have an account with the website they use for their issue\ntracking. If you want to submit a bug report and post the link here,\nthat's fine by me and I'll include it in the reroll.\n\nMartin\n"},{"id":"424554","messageId":"CAN0heSqsrUU=GYsckhZT7Dvx=Rh3aWMMTMBLBfy2XuDWYpQPFg@mail.gmail.com","threadId":"55685","inReplyTo":"xmqqzgwy8faq.fsf@gitster.g","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-14T09:07:11Z","receivedAt":"2021-05-14T09:07:25Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Fri, 14 May 2021 at 00:00, Junio C Hamano wrote:\n>\n> Martin Ågren writes:\n>\n> > Asciidoctor renders 'git cat-file' with the single quotes.\n>\n> I somehow find this sentence a bit hard to grok. Do you mean\n> \"instead of typesetting them emphasized, the two-word phrase is\n> enclosed in a pair of literal single quotes\"?\n\nYes. I will improve the description.\n\n> I have no problem with this particular rephrasing from \"srcref's\n> value\" to \"value of srcref\", but forbidding possessive \"'s\" from any\n> future documentation is troubling.\n\nI think this is a case of several things going on in one paragraph in a\nway that confuses the tool. As Felipe commented, it's probably correct\nto call it out as an Asciidoctor bug. If we hit is *once* across all our\ndocumentation, I think it's correct to work around it [and report the\nbug, if we can], but not let the experience impose a blanket rule on\nourselves that we mustn't do anything that even resembles this\nparagraph.\n\n> > -. A colon `:` is used as in `srcref:dstref` to mean \"use srcref\\'s\n> > - value and store it in dstref\" in fetch and push operations.\n> > +. A colon `:` is used as in `srcref:dstref` to mean \"use the value\n> > + of `srcref` and store it in `dstref`\" in fetch and push operations.\n> > It may also be used to select a specific object such as with\n> > - 'git cat-file': \"git cat-file blob v1.3.3:refs.c\".\n> > + 'git cat-file': `git cat-file blob v1.3.3:refs.c`.\n>\n> The proposed log message did not explain why you wanted to avoid\n> double-quote pair on the \"cat-file\" line. Is this meant as a\n> workaround for the \"single quotes are shown around git cat-file\"\n> issue?\n\nHmm, I've somehow tended to think that it's 'git foo' the tool and `git\nfoo --bar baz` the actual invocation. SQs for the former, backticks for\nthe latter. Like, `git cat-file` is not a correct invocation of 'git\ncat-file'. But I think I'm starting to see the error in my ways --\nCodingGuidelines says to use backticks around command names, so it\nreally should be `git cat-file`. And changing that might just happen to\navoid the issue that triggered this patch.\n\nThanks for your comments.\n\nMartin\n"},{"id":"424555","messageId":"CAN0heSp13ZStRU7Gv0HwuRM4xvMV+EDhUZd_wbs+nVv0u0a4ew@mail.gmail.com","threadId":"55685","inReplyTo":"YJ4K4UXh6sva5I4H@coredump.intra.peff.net","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-14T09:08:53Z","receivedAt":"2021-05-14T09:09:07Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Fri, 14 May 2021 at 07:30, Jeff King wrote:\n>\n> That said, I think in this case \"value of `srcref`\" is actually an\n> improvement to the text (but I wouldn't say the same of the earlier\n> patches, which feel like they are making things clunkier).\n\nOk, if it's an improvement on its own, that's good. Thanks for calling\nout that the others are not.\n\nMartin\n"},{"id":"424576","messageId":"609e6aa287cc9_4312720893@natae.notmuch","threadId":"55685","inReplyTo":"CAN0heSrzkexY9K=VD=y0h9D0pVh59BjaLLg0pEo-WxsP+s0juA@mail.gmail.com","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-14T12:18:42Z","receivedAt":"2021-05-14T12:18:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Thu, 13 May 2021 at 22:35, Junio C Hamano wrote:\n> >\n> > Martin Ågren writes:\n> >\n> > > Some of these rephrase wording such as \"other peoples' commits\" to avoid\n> > > that apostrophe at the end of a word. I'm hoping those rephrasings don't\n> > > regress the quality of the text -- if they do, I'll be happy to try\n> > > something else.\n> >\n> > It is sad, but we really should try \"something else\", unfortunately.\n> >\n> > I do agree with the \"motive\" very much---even though condensing it\n> > down to plain text before running comparison already loses too much\n> > information, doc-diff is the only tool we currently have to\n> > effectively review regressions in rendered document, and the\n> > proposed transition cannot be done safely with confidence without\n> > being able to vet the differences. I am happy to hear about 17%\n> > reduction already, but the requirement to rewrite things like \"other\n> > peoples' commits\" is a dealbreaker.\n> \n> OK, calling it a dealbreaker is fair. Thanks.\n\nIf I understood correctly the deal-breaker is as a long-term solution.\n\nThese particular patches may be welcome right now to reduce the\ndoc-diff, but eventually these issues should be fixed in asciidoctor.\n\n> > A typesettig rule like \"instead of double-dashes --, use {litdd}\" is\n> > an acceptable way out. At least that wouldn't constrain what the\n> > final product that gets delivered to the end-users can say.\n> \n> I've done some experimenting now with a new attribute \"apos\" which\n> expands to a lone SQ. It seems to work fine across the different tools.\n> The rule could be that all ' should be {apos}. That's a quite\n> aggressive rule in a sense. It could be narrowed down to something like\n> \"... if the paragraph contains other quotation, such as backticks or\n> single quotes\", but that's probably just overly complicating things.\n\nI would rather fix it in asciidoctor (the ones that are actually\nasciidoctor issues)\n\n-- \nFelipe Contreras"},{"id":"424577","messageId":"609e6be4bc14d_4312720861@natae.notmuch","threadId":"55685","inReplyTo":"CAN0heSoK5VfP68Us2e2bwSfTzY=5FBEBjxuTHRXeA_qg5MH65w@mail.gmail.com","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-14T12:24:04Z","receivedAt":"2021-05-14T12:24:14Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Fri, 14 May 2021 at 03:40, Felipe Contreras\n> wrote:\n> \n> > We should be submitting bug reports to the asciidoctor project as well,\n> > so in the future it's less likely we find ourselves in the same\n> > scenario.\n> >\n> > Preferably the bug report should be in the commit message.\n> \n> I don't have an account with the website they use for their issue\n> tracking.\n\nGitHub? It probably takes a couple of minutes to set up an account.\n\n> If you want to submit a bug report and post the link here,\n> that's fine by me and I'll include it in the reroll.\n\nIf you would rather have me act as a proxy, that's fine by me.\n\nJust give me a simple example that produces the issue.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"424579","messageId":"609e6d4d67f90_4312720862@natae.notmuch","threadId":"55685","inReplyTo":"CAN0heSqsrUU=GYsckhZT7Dvx=Rh3aWMMTMBLBfy2XuDWYpQPFg@mail.gmail.com","subject":"Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-14T12:30:05Z","receivedAt":"2021-05-14T12:30:20Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Fri, 14 May 2021 at 00:00, Junio C Hamano wrote:\n\n> > The proposed log message did not explain why you wanted to avoid\n> > double-quote pair on the \"cat-file\" line. Is this meant as a\n> > workaround for the \"single quotes are shown around git cat-file\"\n> > issue?\n> \n> Hmm, I've somehow tended to think that it's 'git foo' the tool and `git\n> foo --bar baz` the actual invocation. SQs for the former, backticks for\n> the latter. Like, `git cat-file` is not a correct invocation of 'git\n> cat-file'. But I think I'm starting to see the error in my ways --\n> CodingGuidelines says to use backticks around command names, so it\n> really should be `git cat-file`. And changing that might just happen to\n> avoid the issue that triggered this patch.\n\nHmmm. `git status`, `git branch`, `git diff`, `git log`.\n\nAll these are both \"tools\" **and** invocations. In fact, you an pretty\nmuch \"invoke\" any thing: `git checkout` might not do anything... But it\nruns.\n\n-- \nFelipe Contreras"},{"id":"424588","messageId":"CAN0heSp7JFS3j+DypQm=P-rPzyScvs+Yed75AXYBsQpbJtVytA@mail.gmail.com","threadId":"55685","inReplyTo":"609e6be4bc14d_4312720861@natae.notmuch","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-14T15:28:09Z","receivedAt":"2021-05-14T15:28:36Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Fri, 14 May 2021 at 14:24, Felipe Contreras\n wrote:\n>\n> Martin Ågren wrote:\n> > On Fri, 14 May 2021 at 03:40, Felipe Contreras\n> > wrote:\n> >\n> > > We should be submitting bug reports to the asciidoctor project as well,\n> > > so in the future it's less likely we find ourselves in the same\n> > > scenario.\n> > >\n> > > Preferably the bug report should be in the commit message.\n> >\n> > I don't have an account with the website they use for their issue\n> > tracking.\n>\n> GitHub? It probably takes a couple of minutes to set up an account.\n\nYes, it's GitHub. I'm not interested in having an account there. There's\nsome trade-off there with me not being able to report bugs, but that\ncuts both ways, so I don't feel bad about it.\n\n> > If you want to submit a bug report and post the link here,\n> > that's fine by me and I'll include it in the reroll.\n>\n> If you would rather have me act as a proxy, that's fine by me.\n\nThanks. If you have better things to do, no worry.\n\n> Just give me a simple example that produces the issue.\n\nHere are three variants where AsciiDoc 8.6.10 renders the same, with\nemphasis:\n\n single quotes that will not render literally: 'git cat-file'.\n\n single quotes that won't render literally: 'git cat-file'.\n\n single quotes that\\'ll render literally: 'git cat-file'.\n\nWith Asciidoctor (2.0.15),\n\n asciidoctor -b docbook5 -d manpage -o test.xml test.txt\n\nthe XML contains\n\nsingle quotes that will not render literally: git\ncat-file.\nsingle quotes that won’t render literally:\ngit cat-file.\nsingle quotes that’ll render literally: 'git cat-file'.\n\nThat last paragraph is not as expected. I expect .\n\nI realize that a good answer here is \"don't do that then\". But the\nbackground is that there's some other stuff going on that means AsciiDoc\nneeds that backspaced apostrophe. So this is a minimal reproduction for\nAsciidoctor where we've lost some of the AsciiDoc-specific background.\n\nA fix that works with both tools is an attribute:\n\n :apos: '\n single quotes that won{apos}t render literally: 'git cat-file'.\n\nMartin\n"},{"id":"424619","messageId":"609ed97d9013_43127208bd@natae.notmuch","threadId":"55685","inReplyTo":"CAN0heSp7JFS3j+DypQm=P-rPzyScvs+Yed75AXYBsQpbJtVytA@mail.gmail.com","subject":"Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-14T20:11:41Z","receivedAt":"2021-05-14T20:11:45Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Fri, 14 May 2021 at 14:24, Felipe Contreras\n> wrote:\n> >\n> > Martin Ågren wrote:\n> > > On Fri, 14 May 2021 at 03:40, Felipe Contreras\n> > > wrote:\n> > >\n> > > > We should be submitting bug reports to the asciidoctor project as well,\n> > > > so in the future it's less likely we find ourselves in the same\n> > > > scenario.\n> > > >\n> > > > Preferably the bug report should be in the commit message.\n> > >\n> > > I don't have an account with the website they use for their issue\n> > > tracking.\n> >\n> > GitHub? It probably takes a couple of minutes to set up an account.\n> \n> Yes, it's GitHub. I'm not interested in having an account there. There's\n> some trade-off there with me not being able to report bugs, but that\n> cuts both ways, so I don't feel bad about it.\n\nI don't see what are those both ways, but OK.\n\n> > > If you want to submit a bug report and post the link here,\n> > > that's fine by me and I'll include it in the reroll.\n> >\n> > If you would rather have me act as a proxy, that's fine by me.\n> \n> Thanks. If you have better things to do, no worry.\n\nI do, but reporting bugs doesn't that *that* much time.\n\n> > Just give me a simple example that produces the issue.\n> \n> Here are three variants where AsciiDoc 8.6.10 renders the same, with\n> emphasis:\n> \n> single quotes that will not render literally: 'git cat-file'.\n> \n> single quotes that won't render literally: 'git cat-file'.\n> \n> single quotes that\\'ll render literally: 'git cat-file'.\n> \n> With Asciidoctor (2.0.15),\n> \n> asciidoctor -b docbook5 -d manpage -o test.xml test.txt\n> \n> the XML contains\n\nI'm not talking about the XML, I'm talking about the man pages. I'm not\ninterested in intermediary code, I'm interested in the final output,\nwhich does seem to work correctly:\n\n ruby -r asciidoctor <<\\EOF\n puts Asciidoctor.convert(<