Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Two hypens are rendered as dash in inline content #1717

Open
obfischer opened this issue Mar 31, 2016 · 8 comments
Open

Two hypens are rendered as dash in inline content #1717

obfischer opened this issue Mar 31, 2016 · 8 comments
Milestone

Comments

@obfischer
Copy link

@obfischer obfischer commented Mar 31, 2016

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
Copy link

@rockyallen rockyallen commented Apr 1, 2016

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
Copy link
Member

@mojavelinux mojavelinux commented Apr 1, 2016

@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
Copy link
Member

@mojavelinux mojavelinux commented Apr 1, 2016

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

@mojavelinux mojavelinux added this to the support milestone Apr 1, 2016
@rockyallen
Copy link

@rockyallen rockyallen commented Apr 1, 2016

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
Copy link

@rockyallen rockyallen commented Apr 2, 2016

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
Copy link
Member

@mojavelinux mojavelinux commented Apr 5, 2016

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
Copy link
Member

@mojavelinux mojavelinux commented Apr 5, 2016

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
Copy link
Member

@mojavelinux mojavelinux commented Apr 5, 2016

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants