"Michael Ryzhikov via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: samonon <samonon@gmail.com>
>
> *** Problem.
> {litdd} is used as alias for -- (when not inside backticks) because --
> is a reserved text in asciidoc. There is some problems with this:
> - need to remember that in some cases -- should be replaced with {litdd}
> - unnecessary config options when exporting adoc to other formats
> - in HTML it looks like "&#x2d;&#x2d;" instead of "--" (it works, but
>    browser should correctly decode hex symbols in html link:
>    see htmldocs/git-sh-i18n.html)
>
> *** Solution
> For better readability just escape -- using \.
> This is default asciidoc mechanism that don't need any configuration.
> Tested with "make all doc" - links inside linkgit: work.

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.

On Mon, Feb 23, 2026 at 9:20 PM Junio C Hamano <gitster@pobox.com> 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 `<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).