Two hypens are rendered as dash in inline content

[obfischer]

In shell commands "--" is often used to separate parameters and arguments. Unfortunately two hyphens are not always correctly rendered in inline content.

Given an input file with the following threee line

`git checkout -- .`
`git --checkout .`
`git checkout-- .`

With Asciidoctor 1.5.1 the two hyphens in the first example are rendered as dash. In all other examples the two hyphens are rendered correctly.

[rockyallen]

According to http://asciidoctor.org/docs/user-manual/#replacements
two hyphens together are shorthand for an emdash.
One way to prevent this substitution (there may be a better one) is to use a pass macro (http://asciidoctor.org/docs/user-manual/#pass-mac) ie

git checkout pass:[--] .

or

git checkout +++--+++ .

This for inline content; if you wanted the command on a line by itself (ie a block) start the line with a space - then you don't need the pass macro or the backticks.

git checkout -- .

[mojavelinux]

@rockyallen wrote:

two hyphens together are shorthand for an emdash.

In certain cases. It depends on the neighboring characters.

@obfischer wrote:

With Asciidoctor 1.5.1 the two hyphens in the first example are rendered as dash.

It's important to remember that, as of Asciidoctor 1.5, backticks are for producing normal text in a monospace font. Normal substitution rules apply (just like if you made the text bold). In other words, the content is not treated literally.

To prevent the substitutions from occurring, you need to use one of the following:

`+git checkout -- README.adoc+`
[x-]`git checkout -- README.adoc`
`pass:c[git checkout -- README.adoc]`
`git checkout \-- README.adoc`

The most common approach is the +...+ syntax, which is the closest equivalent the the old meaning of backticks.

See http://asciidoctor.org/docs/migration/#migration-cheatsheet for details.

The reason we made this change in Asciidoctor is two-fold:

1. The + symbol is now used consistently for passthrough (various types of literal text)
2. You can use formatting and substitutions within monospaced text (unlike Markdown)

In the future, we may be able to limit the substitutions that occur within monospace text more intelligently, since hyphens are rarely desired there. However, we can't do it with the current inline parsing technique we're using.

The annoying part is that you have to pay attention to when substitutions are being applied if you want to use +...+ sparingly. However, there is no harm in using it where it isn't strictly necessary.

[mojavelinux]

@rockyallen do you think a clarification to the user manual is warranted given what I wrote in my response?

[rockyallen]

Definitely. Particularly the rules about how the surrounding characters affect the replacement. Are the rules the same for all the replacements? Also you didn't repeat the +++ form of the pass: macro. Was that deliberate?

[rockyallen]

The rules seem to be:

• All replacements (table, section 40.4) can be escaped with a single \
• All replacements EXCEPT -- work anywhere on the line
• -- is ONLY replaced if it is a word (surrounded by white space or lies start/line end)

[mojavelinux]

you didn't repeat the +++ form of the pass: macro. Was that deliberate?

Yes. That's because +++ means to skip substitutions both for the input and the output. In other words, copy the content directly to the output stream.

While it doesn't matter in this example, if the command contained a < or >, it would not be properly encoded and thus result in broken output. So +++ should only be used when you are sending markup (e.g., HTML) directly to the output stream.

By default, the inline pass macro and +++ do the same thing, but the inline pass macro supports a custom substitution list. I updated the example above so that it encodes special characters (pass:c[...]).

[mojavelinux]

The rules seem to be:

• All replacements (table, section 40.4) can be escaped with a single \

It's not a perfect solution, so let's soften this to say "in most cases".

"In most cases, replacements (table, section 40.4) can be escaped by adding a leading \ character (e.g., \--)

• All replacements EXCEPT -- work anywhere on the line

Let's drop this one. It's too vague.

• -- is ONLY replaced if it is a word (surrounded by white space or lies start/line end)

Yes! Very good.

[mojavelinux]

Let's open an issue in the asciidoctor.org repository to track these changes. We can name the issue "Clarify when replacements are used and how to escape them". We'll sort out which section it belongs. @rockyallen would you like to file the issue.

[KucharczykL]

I ran into this issue when trying to add a link with two hyphens. The link in question is

https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md#2321--2021-12-17

When converted to HTML by asciidoctor, the result is:

https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md#2321—​2021-12-17

This ends up breaking the links in the generated HTML. When I click the link in Firefox, it navigates to:

https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md#2321%E2%80%94%E2%80%8B2021-12-17

[mojavelinux]

That's a duplicate of #625, which has been explained.

[mojavelinux]

Escaping replacements is now covered in the docs. See:

• https://docs.asciidoctor.org/asciidoc/latest/subs/prevent/
• https://docs.asciidoctor.org/asciidoc/latest/macros/complex-urls/

In the AsciiDoc Language, we do plan to define the target of link and xref macros in such a way that only attribute references are substituted. That work is still ongoing.