From: Михаил Рыжиков Date: Tue, 24 Feb 2026 06:15:37 GMT Subject: Re: [PATCH] docs: remove {litdd} usage Message-ID: In-Reply-To: On Mon, Feb 23, 2026 at 9:20 PM Junio C Hamano wrote: > Hmph, I do not quite see the point of this churn. We'd need to > remember to do \-- instead of doing {litdd}, either way. > > I do not know what you want to say with "when exporting to other > formats", as we already are formatting these source files into HTML > and manual pages. Let this e-mail be a summary post for similar suggestions. If there is a reason to continue using legacy fix {litdd} there needs to be an example where it breaks output with current tools/setups (or even may be future setups). If it can be replaced there needs to be a list of required tests for all setups (see 2.). 1. I searched this mailing list for 'litdd' references (links will be in the end) and understood that it was introduced because of changes in asciidoc syntax (-- became emdash) and bugs in asciidoc* converter more than 10 years ago. Should it be used still for legacy code support? I tested (cygwin + asciidoc) 'make all doc' and it works correctly (but maybe it's only for me). Since '\--' is a default asciidoc syntax for disabling text replacement it should be used for writing docs and converters now should know about this syntax. 2. What should be tested whether replacing {litdd} with '\--' doesn't regress with current tools? Should it work correctly (and create same textual output): - with Win/Mac and all types of Linux/Unix/BSD? - with all converters (including older versions): asciidoc, asciidoctor, etc... - with all output formats (man, html, info, pdf, docbook, etc...)? - with 'Git for Windows' repo and other forks? Who can take their time and test all this? Or release docs should come from a single source (like manpages and html docs at https://www.kernel.org/pub/software/scm/git)? 3. Development discussion forum. 3.1 I apologize for sending it directly to this mailing list - maybe It should have been discussed somewhere else beforehand? For example, Discord? Mailing list is SO old school. 3.2 Maybe there should be a discord channel #docs for Git documentation development? ----------------------------------------------------------------------------- Previous important references to {litdd} in this mailing list. My comments start with >> https://lore.kernel.org/git/20110629053510.GC28690@elie/ [PATCH 1/2 maint] Documentation: quote double-dash for AsciiDoc Use "\--" to avoid such misformatting in sentences in which "--" represents a literal double-minus command line argument that separates options and revs from pathspecs, and use "{litdd}" in cases where the double-dash is embedded in the command name. The latter is just for consistency with v1.7.3-rc0~13^2 (Work around em-dash handling in newer AsciiDoc, 2010-08-23). https://lore.kernel.org/git/20120426085156.GB22819@sigill.intra.peff.net/ [PATCH] docs: stop using asciidoc no-inline-literal https://lore.kernel.org/git/20150513045650.GA6070@peff.net/ [PATCH 0/8] asciidoc fixups https://lore.kernel.org/git/1462220405-12408-2-git-send-email-larsxschneider@gmail.com/ [PATCH v3 1/2] Documentation: fix linkgit references >> previous attempt to remove {litdd} https://lore.kernel.org/git/20171029211308.272673-1-sandals@crustytoothpaste.net/ [PATCH 0/2] Convert SubmittingPatches to AsciiDoc https://lore.kernel.org/git/20180510071103.GC31779@sigill.intra.peff.net/ There are certainly a few that can't, though (e.g., config.txt uses linkgit:git-web{litdd}browse[1]). I agree that "\--" is less ugly there (and seems to work on my modern asciidoc). There's some history on the litdd versus "\--" choice in 565e135a1e (Documentation: quote double-dash for AsciiDoc, 2011-06-29). That in turn references the 2839478774 (Work around em-dash handling in newer AsciiDoc, 2010-08-23), but I wouldn't be surprised if all of that is now obsolete with our AsciiDoc 8+ requirement. https://lore.kernel.org/git/20190320181715.GJ31362@pobox.com/ Re: [PATCH] asciidoctor-extensions: provide `` https://lore.kernel.org/git/xmqqsg2q9xts.fsf@gitster.g/ Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again (14.05.2021) A typesetting rule like "instead of double-dashes --, use {litdd}" is an acceptable way out. At least that wouldn't constrain what the final product that gets delivered to the end-users can say. https://lore.kernel.org/git/20220406184122.4126898-1-tmz@pobox.com/ [PATCH] doc: replace "--" with {litdd} in credential-cache/fsmonitor Asciidoc renders `--` as em-dash. This is not appropriate for command names. It also breaks linkgit links to these commands. >> Currently it doesn't break linkgit: (but may be only for me).