Re: [PATCH] docs: remove {litdd} usage

From: Михаил Рыжиков <samonon@gmail.com>
Date: Feb 24, 2026, 06:15 UTC
Message-ID: <CABqR6nAdC-GA3ePdJkm5o+W6DyViyJsJ0HkgEre=7ORwi-yH2Q@mail.gmail.com>
In-Reply-To: <xmqq5x7nnwyk.fsf@gitster.g>

On Mon, Feb 23, 2026 at 9:20 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 6 quoted lines

> 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 `<refmiscinfo/>`

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).