{"thread":{"id":"65054","subject":"[PATCH] docs: remove {litdd} usage","startedAt":"2026-02-23T11:30:37Z","lastAt":"2026-02-24T06:15:50Z","messageCount":3,"participants":["Michael Ryzhikov via GitGitGadget","Junio C Hamano","Михаил Рыжиков"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"536747","messageId":"pull.2215.git.git.1771846234706.gitgitgadget@gmail.com","threadId":"65054","inReplyTo":null,"subject":"[PATCH] docs: remove {litdd} usage","fromName":"Michael Ryzhikov via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-02-23T11:30:34Z","receivedAt":"2026-02-23T11:30:37Z","isPatch":true,"sender":{"key":"name:Michael Ryzhikov","avatar":null},"body":"From: samonon <samonon@gmail.com>\n\n*** Problem.\n{litdd} is used as alias for -- (when not inside backticks) because --\nis a reserved text in asciidoc. There is some problems with this:\n- need to remember that in some cases -- should be replaced with {litdd}\n- unnecessary config options when exporting adoc to other formats\n- in HTML it looks like \"&#x2d;&#x2d;\" instead of \"--\" (it works, but\n   browser should correctly decode hex symbols in html link:\n   see htmldocs/git-sh-i18n.html)\n\n*** Solution\nFor better readability just escape -- using \\.\nThis is default asciidoc mechanism that don't need any configuration.\nTested with \"make all doc\" - links inside linkgit: work.\n\nSigned-off-by: samonon <samonon@gmail.com>\n---\n    docs: remove {litdd} usage\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2215%2FMuxaJIbI4%2Fremove-litdd-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2215/MuxaJIbI4/remove-litdd-v1\nPull-Request: https://github.com/git/git/pull/2215\n\n Documentation/Makefile                          |  1 -\n Documentation/SubmittingPatches                 |  2 +-\n Documentation/asciidoc.conf.in                  |  1 -\n Documentation/config/browser.adoc               |  2 +-\n Documentation/config/core.adoc                  |  2 +-\n Documentation/git-archimport.adoc               |  6 +++---\n Documentation/git-credential-cache--daemon.adoc |  6 +++---\n Documentation/git-fsmonitor--daemon.adoc        | 12 ++++++------\n Documentation/git-help.adoc                     |  6 +++---\n Documentation/git-instaweb.adoc                 |  6 +++---\n Documentation/git-mergetool--lib.adoc           | 10 +++++-----\n Documentation/git-sh-i18n--envsubst.adoc        | 10 +++++-----\n Documentation/git-sh-i18n.adoc                  |  2 +-\n Documentation/git-update-index.adoc             |  2 +-\n Documentation/git-web--browse.adoc              | 10 +++++-----\n Documentation/lint-gitlink.perl                 |  2 +-\n Documentation/meson.build                       |  1 -\n contrib/subtree/Makefile                        |  1 -\n t/t0450-txt-doc-vs-help.sh                      |  2 +-\n 19 files changed, 40 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2699f0b24a..64c3ed880c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -223,7 +223,6 @@ ASCIIDOC_HTML = xhtml5\n ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n-ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n ASCIIDOC_EXTRA += -adocinfo=shared\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex e270ccbe85..8322a4a05c 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -35,7 +35,7 @@ The people who may need to know are the ones who worked on the code\n you are touching.  These people happen to be the ones who are\n most likely to be knowledgeable enough to help you, but\n they have no obligation to help you (i.e. you ask them for help,\n-you don't demand).  +git log -p {litdd} _$area_you_are_modifying_+ would\n+you don't demand).  +git log -p \\-- _$area_you_are_modifying_+ would\n help you find out who they are.\n \n . You get comments and suggestions for improvements.  You may even get\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex 31b883a72c..3a54e1644e 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -20,7 +20,6 @@ backslash=&#92;\n tilde=&#126;\n apostrophe=&#39;\n backtick=&#96;\n-litdd=&#45;&#45;\n manmanual=Git Manual\n mansource=Git @GIT_VERSION@\n revdate=@GIT_DATE@\ndiff --git a/Documentation/config/browser.adoc b/Documentation/config/browser.adoc\nindex 195df207a6..8f9161fb8a 100644\n--- a/Documentation/config/browser.adoc\n+++ b/Documentation/config/browser.adoc\n@@ -1,7 +1,7 @@\n browser.<tool>.cmd::\n \tSpecify the command to invoke the specified browser. The\n \tspecified command is evaluated in shell with the URLs passed\n-\tas arguments. (See linkgit:git-web{litdd}browse[1].)\n+\tas arguments. (See linkgit:git-web\\--browse[1].)\n \n browser.<tool>.path::\n \tOverride the path for the given tool that may be used to\ndiff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc\nindex a0ebf03e2e..db5ab03eae 100644\n--- a/Documentation/config/core.adoc\n+++ b/Documentation/config/core.adoc\n@@ -63,7 +63,7 @@ core.protectNTFS::\n \n core.fsmonitor::\n \tIf set to true, enable the built-in file system monitor\n-\tdaemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]).\n+\tdaemon for this working directory (linkgit:git-fsmonitor\\--daemon[1]).\n +\n Like hook-based file system monitors, the built-in file system monitor\n can speed up Git commands that need to refresh the Git index\ndiff --git a/Documentation/git-archimport.adoc b/Documentation/git-archimport.adoc\nindex 847777fd17..178a4d66ed 100644\n--- a/Documentation/git-archimport.adoc\n+++ b/Documentation/git-archimport.adoc\n@@ -45,7 +45,7 @@ archives that it imports, it is also possible to specify Git branch names\n manually.  To do so, write a Git branch name after each <archive>/<branch>\n parameter, separated by a colon.  This way, you can shorten the Arch\n branch names and convert Arch jargon to Git jargon, for example mapping a\n-\"PROJECT{litdd}devo{litdd}VERSION\" branch to \"master\".\n+\"PROJECT\\--devo\\--VERSION\" branch to \"master\".\n \n Associating multiple Arch branches to one Git branch is possible; the\n result will make the most sense only if no commits are made to the first\n@@ -86,8 +86,8 @@ OPTIONS\n -o::\n \tUse this for compatibility with old-style branch names used by\n \tearlier versions of 'git archimport'.  Old-style branch names\n-\twere category{litdd}branch, whereas new-style branch names are\n-\tarchive,category{litdd}branch{litdd}version.  In both cases, names given\n+\twere category\\--branch, whereas new-style branch names are\n+\tarchive,category\\--branch\\--version.  In both cases, names given\n \ton the command-line will override the automatically-generated\n \tones.\n \ndiff --git a/Documentation/git-credential-cache--daemon.adoc b/Documentation/git-credential-cache--daemon.adoc\nindex 650a15a7ed..b9e05146d1 100644\n--- a/Documentation/git-credential-cache--daemon.adoc\n+++ b/Documentation/git-credential-cache--daemon.adoc\n@@ -1,5 +1,5 @@\n-git-credential-cache{litdd}daemon(1)\n-====================================\n+git-credential-cache\\--daemon(1)\n+================================\n \n NAME\n ----\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-'git credential-cache{litdd}daemon' [--debug] <socket-path>\n+'git credential-cache\\--daemon' [--debug] <socket-path>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-fsmonitor--daemon.adoc b/Documentation/git-fsmonitor--daemon.adoc\nindex 8fe5241b08..547d185214 100644\n--- a/Documentation/git-fsmonitor--daemon.adoc\n+++ b/Documentation/git-fsmonitor--daemon.adoc\n@@ -1,5 +1,5 @@\n-git-fsmonitor{litdd}daemon(1)\n-=============================\n+git-fsmonitor\\--daemon(1)\n+=========================\n \n NAME\n ----\n@@ -8,10 +8,10 @@ git-fsmonitor--daemon - A Built-in Filesystem Monitor\n SYNOPSIS\n --------\n [verse]\n-'git fsmonitor{litdd}daemon' start\n-'git fsmonitor{litdd}daemon' run\n-'git fsmonitor{litdd}daemon' stop\n-'git fsmonitor{litdd}daemon' status\n+'git fsmonitor\\--daemon' start\n+'git fsmonitor\\--daemon' run\n+'git fsmonitor\\--daemon' stop\n+'git fsmonitor\\--daemon' status\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-help.adoc b/Documentation/git-help.adoc\nindex f0bedc1f96..b83feed536 100644\n--- a/Documentation/git-help.adoc\n+++ b/Documentation/git-help.adoc\n@@ -110,9 +110,9 @@ other display programs (see below).\n +\n The web browser can be specified using the configuration variable\n `help.browser`, or `web.browser` if the former is not set. If neither of\n-these config variables is set, the 'git web{litdd}browse' helper script\n+these config variables is set, the 'git web\\--browse' helper script\n (called by 'git help') will pick a suitable default. See\n-linkgit:git-web{litdd}browse[1] for more information about this.\n+linkgit:git-web\\--browse[1] for more information about this.\n \n CONFIGURATION VARIABLES\n -----------------------\n@@ -135,7 +135,7 @@ help.browser, web.browser, and browser.<tool>.path\n The `help.browser`, `web.browser` and `browser.<tool>.path` will also\n be checked if the 'web' format is chosen (either by command-line\n option or configuration variable). See '-w|--web' in the OPTIONS\n-section above and linkgit:git-web{litdd}browse[1].\n+section above and linkgit:git-web\\--browse[1].\n \n man.viewer\n ~~~~~~~~~~\ndiff --git a/Documentation/git-instaweb.adoc b/Documentation/git-instaweb.adoc\nindex a54fe4401b..c17011c438 100644\n--- a/Documentation/git-instaweb.adoc\n+++ b/Documentation/git-instaweb.adoc\n@@ -45,9 +45,9 @@ OPTIONS\n -b::\n --browser::\n \tThe web browser that should be used to view the gitweb\n-\tpage. This will be passed to the 'git web{litdd}browse' helper\n+\tpage. This will be passed to the 'git web\\--browse' helper\n \tscript along with the URL of the gitweb instance. See\n-\tlinkgit:git-web{litdd}browse[1] for more information about this. If\n+\tlinkgit:git-web\\--browse[1] for more information about this. If\n \tthe script fails, the URL will be printed to stdout.\n \n start::\n@@ -83,7 +83,7 @@ You may specify configuration in your .git/config\n \n If the configuration variable `instaweb.browser` is not set,\n `web.browser` will be used instead if it is defined. See\n-linkgit:git-web{litdd}browse[1] for more information about this.\n+linkgit:git-web\\--browse[1] for more information about this.\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-mergetool--lib.adoc b/Documentation/git-mergetool--lib.adoc\nindex 0726b560d4..cdbc881bfb 100644\n--- a/Documentation/git-mergetool--lib.adoc\n+++ b/Documentation/git-mergetool--lib.adoc\n@@ -1,5 +1,5 @@\n-git-mergetool{litdd}lib(1)\n-==========================\n+git-mergetool\\--lib(1)\n+======================\n \n NAME\n ----\n@@ -8,7 +8,7 @@ git-mergetool--lib - Common Git merge tool shell scriptlets\n SYNOPSIS\n --------\n [verse]\n-'TOOL_MODE=(diff|merge) . \"$(git --exec-path)/git-mergetool{litdd}lib\"'\n+'TOOL_MODE=(diff|merge) . \"$(git --exec-path)/git-mergetool\\--lib\"'\n \n DESCRIPTION\n -----------\n@@ -17,11 +17,11 @@ This is not a command the end user would want to run.  Ever.\n This documentation is meant for people who are studying the\n Porcelain-ish scripts and/or are writing new ones.\n \n-The 'git-mergetool{litdd}lib' scriptlet is designed to be sourced (using\n+The 'git-mergetool\\--lib' scriptlet is designed to be sourced (using\n `.`) by other shell scripts to set up functions for working\n with Git merge tools.\n \n-Before sourcing 'git-mergetool{litdd}lib', your script must set `TOOL_MODE`\n+Before sourcing 'git-mergetool\\--lib', your script must set `TOOL_MODE`\n to define the operation mode for the functions listed below.\n 'diff' and 'merge' are valid values.\n \ndiff --git a/Documentation/git-sh-i18n--envsubst.adoc b/Documentation/git-sh-i18n--envsubst.adoc\nindex 2ffaf9392e..6473a9a795 100644\n--- a/Documentation/git-sh-i18n--envsubst.adoc\n+++ b/Documentation/git-sh-i18n--envsubst.adoc\n@@ -1,5 +1,5 @@\n-git-sh-i18n{litdd}envsubst(1)\n-=============================\n+git-sh-i18n\\--envsubst(1)\n+=========================\n \n NAME\n ----\n@@ -10,8 +10,8 @@ SYNOPSIS\n [verse]\n eval_gettext () {\n \tprintf \"%s\" \"$1\" | (\n-\t\texport PATH $('git sh-i18n{litdd}envsubst' --variables \"$1\");\n-\t\t'git sh-i18n{litdd}envsubst' \"$1\"\n+\t\texport PATH $('git sh-i18n\\--envsubst' --variables \"$1\");\n+\t\t'git sh-i18n\\--envsubst' \"$1\"\n \t)\n }\n \n@@ -22,7 +22,7 @@ This is not a command the end user would want to run.  Ever.\n This documentation is meant for people who are studying the\n plumbing scripts and/or are writing new ones.\n \n-'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU\n+'git sh-i18n\\--envsubst' is Git's stripped-down copy of the GNU\n `envsubst(1)` program that comes with the GNU gettext package. It's\n used internally by linkgit:git-sh-i18n[1] to interpolate the variables\n passed to the `eval_gettext` function.\ndiff --git a/Documentation/git-sh-i18n.adoc b/Documentation/git-sh-i18n.adoc\nindex 60cf49cb2a..7deb13d861 100644\n--- a/Documentation/git-sh-i18n.adoc\n+++ b/Documentation/git-sh-i18n.adoc\n@@ -35,7 +35,7 @@ gettext::\n eval_gettext::\n \tCurrently a dummy fall-through function implemented as a wrapper\n \taround `printf(1)` with variables expanded by the\n-\tlinkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a\n+\tlinkgit:git-sh-i18n\\--envsubst[1] helper. Will be replaced by a\n \treal gettext implementation in a later version.\n \n GIT\ndiff --git a/Documentation/git-update-index.adoc b/Documentation/git-update-index.adoc\nindex 9bea9fab9a..0cda1e699e 100644\n--- a/Documentation/git-update-index.adoc\n+++ b/Documentation/git-update-index.adoc\n@@ -539,7 +539,7 @@ This feature is intended to speed up git operations for repos that have\n large working directories.\n \n It enables git to work together with a file system monitor (see\n-linkgit:git-fsmonitor{litdd}daemon[1]\n+linkgit:git-fsmonitor\\--daemon[1]\n and the\n \"fsmonitor-watchman\" section of linkgit:githooks[5]) that can\n inform it as to what files have been modified. This enables git to avoid\ndiff --git a/Documentation/git-web--browse.adoc b/Documentation/git-web--browse.adoc\nindex f2f996cbe1..13e37dac82 100644\n--- a/Documentation/git-web--browse.adoc\n+++ b/Documentation/git-web--browse.adoc\n@@ -1,5 +1,5 @@\n-git-web{litdd}browse(1)\n-=======================\n+git-web\\--browse(1)\n+===================\n \n NAME\n ----\n@@ -8,7 +8,7 @@ git-web--browse - Git helper script to launch a web browser\n SYNOPSIS\n --------\n [verse]\n-'git web{litdd}browse' [<options>] (<URL>|<file>)...\n+'git web\\--browse' [<options>] (<URL>|<file>)...\n \n DESCRIPTION\n -----------\n@@ -71,7 +71,7 @@ browser.<tool>.path\n You can explicitly provide a full path to your preferred browser by\n setting the configuration variable `browser.<tool>.path`. For example,\n you can configure the absolute path to firefox by setting\n-'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool\n+'browser.firefox.path'. Otherwise, 'git web\\--browse' assumes the tool\n is available in PATH.\n \n browser.<tool>.cmd\n@@ -80,7 +80,7 @@ browser.<tool>.cmd\n When the browser, specified by options or configuration variables, is\n not among the supported ones, then the corresponding\n `browser.<tool>.cmd` configuration variable will be looked up. If this\n-variable exists then 'git web{litdd}browse' will treat the specified tool\n+variable exists then 'git web\\--browse' will treat the specified tool\n as a custom command and will use a shell eval to run the command with\n the URLs passed as arguments.\n \ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex a92e887b4c..c7d9b2805a 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -54,7 +54,7 @@ while (<>) {\n \t\tmy ($target, $page, $section) = ($1, $2, $3);\n \n \t\t# De-AsciiDoc\n-\t\t$page =~ s/{litdd}/--/g;\n+\t\t$page =~ s/\\\\--/--/g;\n \n \t\tif (!exists $TXT{$page}) {\n \t\t\treport($pos, $line, $target, \"link outside of our own docs\");\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex fd2e8cc02d..bfeae3587b 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -295,7 +295,6 @@ elif docs_backend == 'asciidoctor'\n     asciidoctor,\n     '--attribute', 'compat-mode',\n     '--attribute', 'tabsize=8',\n-    '--attribute', 'litdd=&#x2d;&#x2d;',\n     '--attribute', 'docinfo=shared',\n     '--attribute', 'build_dir=' + meson.current_build_dir(),\n     '--load-path', meson.current_build_dir(),\ndiff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile\nindex c0c9f21cb7..540a074b02 100644\n--- a/contrib/subtree/Makefile\n+++ b/contrib/subtree/Makefile\n@@ -33,7 +33,6 @@ ASCIIDOC_CONF    =\n ASCIIDOC_HTML    = xhtml5\n ASCIIDOC_DOCBOOK = docbook\n ASCIIDOC_EXTRA  += -I. -rasciidoctor-extensions\n-ASCIIDOC_EXTRA  += -alitdd='&\\#x2d;&\\#x2d;'\n ASCIIDOC_DEPS    = asciidoctor-extensions.rb\n XMLTO_EXTRA     += --skip-validation\n endif\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 822b0d55a5..4e6cb163fb 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -58,7 +58,7 @@ adoc_to_synopsis () {\n \t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n \t\t\t/^$/q;\n \t\t\t/^\\[(verse|synopsis)\\]$/d;\n-\t\t\ts/\\{litdd\\}/--/g;\n+\t\t\ts/\\\\--/--/g;\n \t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n \n \t\t\tp;\n\nbase-commit: 7c02d39fc2ed2702223c7674f73150d9a7e61ba4\n-- \ngitgitgadget\n"},{"id":"536866","messageId":"xmqq5x7nnwyk.fsf@gitster.g","threadId":"65054","inReplyTo":"pull.2215.git.git.1771846234706.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: remove {litdd} usage","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-23T18:20:19Z","receivedAt":"2026-02-23T18:20:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Michael Ryzhikov via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: samonon <samonon@gmail.com>\n>\n> *** Problem.\n> {litdd} is used as alias for -- (when not inside backticks) because --\n> is a reserved text in asciidoc. There is some problems with this:\n> - need to remember that in some cases -- should be replaced with {litdd}\n> - unnecessary config options when exporting adoc to other formats\n> - in HTML it looks like \"&#x2d;&#x2d;\" instead of \"--\" (it works, but\n>    browser should correctly decode hex symbols in html link:\n>    see htmldocs/git-sh-i18n.html)\n>\n> *** Solution\n> For better readability just escape -- using \\.\n> This is default asciidoc mechanism that don't need any configuration.\n> Tested with \"make all doc\" - links inside linkgit: work.\n\nHmph, I do not quite see the point of this churn.  We'd need to\nremember to do \\-- instead of doing {litdd}, either way.\n\nI do not know what you want to say with \"when exporting to other\nformats\", as we already are formatting these source files into HTML\nand manual pages.\n\n"},{"id":"536918","messageId":"CABqR6nAdC-GA3ePdJkm5o+W6DyViyJsJ0HkgEre=7ORwi-yH2Q@mail.gmail.com","threadId":"65054","inReplyTo":"xmqq5x7nnwyk.fsf@gitster.g","subject":"Re: [PATCH] docs: remove {litdd} usage","fromName":"Михаил Рыжиков","fromEmail":"samonon@gmail.com","sentAt":"2026-02-24T06:15:37Z","receivedAt":"2026-02-24T06:15:50Z","isPatch":true,"sender":{"key":"samonon@gmail.com","avatar":null},"body":"On Mon, Feb 23, 2026 at 9:20 PM Junio C Hamano <gitster@pobox.com> wrote:\n> Hmph, I do not quite see the point of this churn.  We'd need to\n> remember to do \\-- instead of doing {litdd}, either way.\n>\n> I do not know what you want to say with \"when exporting to other\n> formats\", as we already are formatting these source files into HTML\n> and manual pages.\n\nLet this e-mail be a summary post for similar suggestions.\nIf there is a reason to continue using legacy fix {litdd} there needs\nto be an example\nwhere it breaks output with current tools/setups (or even may be future setups).\nIf it can be replaced there needs to be a list of required tests for\nall setups (see 2.).\n\n1. I searched this mailing list for 'litdd' references (links will be\nin the end) and understood\nthat it was introduced because of changes in asciidoc syntax (--\nbecame emdash) and\nbugs in asciidoc* converter more than 10 years ago. Should it be used\nstill for legacy code support?\nI tested (cygwin + asciidoc) 'make all doc' and it works correctly\n(but maybe it's only for me).\nSince '\\--' is a default asciidoc syntax for disabling text\nreplacement it should be used\nfor writing docs and converters now should know about this syntax.\n\n2. What should be tested whether replacing {litdd} with '\\--' doesn't\nregress with current tools?\nShould it work correctly (and create same textual output):\n- with Win/Mac and all types of Linux/Unix/BSD?\n- with all converters (including older versions): asciidoc, asciidoctor, etc...\n- with all output formats (man, html, info, pdf, docbook, etc...)?\n- with 'Git for Windows' repo and other forks?\nWho can take their time and test all this?\nOr release docs should come from a single source (like manpages and html docs\nat https://www.kernel.org/pub/software/scm/git)?\n\n3. Development discussion forum.\n3.1 I apologize for sending it directly to this mailing list - maybe\nIt should have been\ndiscussed somewhere else beforehand? For example, Discord? Mailing\nlist is SO old school.\n3.2 Maybe there should be a discord channel #docs for Git\ndocumentation development?\n\n-----------------------------------------------------------------------------\nPrevious important references to {litdd} in this mailing list. My\ncomments start with >>\n\nhttps://lore.kernel.org/git/20110629053510.GC28690@elie/\n[PATCH 1/2 maint] Documentation: quote double-dash for AsciiDoc\nUse \"\\--\" to avoid such misformatting in sentences in which \"--\"\nrepresents a literal\ndouble-minus command line argument that separates options and revs from\npathspecs, and use \"{litdd}\" in cases where the double-dash is embedded\nin the command name.  The latter is just for consistency with\nv1.7.3-rc0~13^2 (Work around em-dash handling in newer AsciiDoc, 2010-08-23).\n\nhttps://lore.kernel.org/git/20120426085156.GB22819@sigill.intra.peff.net/\n[PATCH] docs: stop using asciidoc no-inline-literal\n\nhttps://lore.kernel.org/git/20150513045650.GA6070@peff.net/\n[PATCH 0/8] asciidoc fixups\n\nhttps://lore.kernel.org/git/1462220405-12408-2-git-send-email-larsxschneider@gmail.com/\n[PATCH v3 1/2] Documentation: fix linkgit references\n>> previous attempt to remove {litdd}\n\nhttps://lore.kernel.org/git/20171029211308.272673-1-sandals@crustytoothpaste.net/\n[PATCH 0/2] Convert SubmittingPatches to AsciiDoc\n\nhttps://lore.kernel.org/git/20180510071103.GC31779@sigill.intra.peff.net/\nThere are certainly a few that can't, though (e.g., config.txt uses\nlinkgit:git-web{litdd}browse[1]).\nI agree that \"\\--\" is less ugly there (and seems to work on my modern asciidoc).\nThere's some history on the litdd versus \"\\--\" choice in 565e135a1e\n(Documentation:\nquote double-dash for AsciiDoc, 2011-06-29). That in turn references\nthe 2839478774\n(Work around em-dash handling in newer AsciiDoc, 2010-08-23),\nbut I wouldn't be surprised if all of that is now obsolete with our\nAsciiDoc 8+ requirement.\n\nhttps://lore.kernel.org/git/20190320181715.GJ31362@pobox.com/\nRe: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`\n\nhttps://lore.kernel.org/git/xmqqsg2q9xts.fsf@gitster.g/\nRe: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again  (14.05.2021)\nA typesetting rule like \"instead of double-dashes --, use {litdd}\" is\nan acceptable way out.\nAt least that wouldn't constrain what the final product that gets\ndelivered to the end-users can say.\n\nhttps://lore.kernel.org/git/20220406184122.4126898-1-tmz@pobox.com/\n[PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor\nAsciidoc renders `--` as em-dash.  This is not appropriate for command names.\nIt also breaks linkgit links to these commands.\n>> Currently it doesn't break linkgit: (but may be only for me).\n"}]}