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

string starting with underscore gets italicized #2020

Closed
codynguyen opened this issue Feb 14, 2017 · 7 comments

Comments

Projects
None yet
4 participants
@codynguyen
Copy link

commented Feb 14, 2017

Hi,

I have this piece of source converted from swagger API, which has an _id attribute which is optional:

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|*_id* +
_optional_|ID of the item within the system. +
*Pattern* : `"^[a-fA-F0-9]{24}$"` +
*Example* : `"5742b1f7535cf2baba8fff91"`|string
|*currency_gain* +
_optional_|Gain value over the specified period, in investment/asset currency.|number
|===

which gets rendered into

screen shot 2017-02-14 at 2 24 46 pm

There are 2 problems with the results: 1) _id is missing the underscore and is italicized, and 2) optional is prefixed with an underscore and is not italicized.

The expected result can be seen in the line below for currency_gain, in which currency_gain is bold + not italic, where as optional is normal weighted + italic.

When I tried to escaped the underscore being recognized as italic handle by adding a back slash before _id so it becomes \_id:

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|*\_id* +
_optional_|ID of the item within the system. +
*Pattern* : `"^[a-fA-F0-9]{24}$"` +
*Example* : `"5742b1f7535cf2baba8fff91"`|string
|===

Then I get this result:

screen shot 2017-02-14 at 2 14 14 pm

Which is better because _id doesn't loose the underscore, but optional now displays as _optional_ (not italicized and wrapped by underscores).

Is there anyway to work around this problem so that _id is displayed in full, and optional gets italicized without being wrapped by underscores?

Thanks a lot!

@JBR69

This comment has been minimized.

Copy link

commented Feb 14, 2017

Try this (use pass:[] for the underscore of _id)

[options="header", cols=".^3,.^11,.^4"]
|===
|Name|Description|Schema
|*pass:[_]id* +
_optional_|ID of the item within the system. +
*Pattern* : `"^[a-fA-F0-9]{24}$"` +
*Example* : `"5742b1f7535cf2baba8fff91"`|string
|*currency_gain* +
_optional_|Gain value over the specified period, in investment/asset currency.|number
|===
@mojavelinux

This comment has been minimized.

Copy link
Member

commented Feb 14, 2017

You can also use a backslash in this case. It's important to keep in mind that backslashes are only recognized if formatting would be applied. In this case, it would be.

Your use case happens to be a valid formatting request, thus you have to take additional action.

@mojavelinux mojavelinux added this to the support milestone Feb 14, 2017

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Feb 14, 2017

Actually, I misspoke. A backslash confuses things in this case. The other way to approach this is to make the italic around optional more explicit by using unconstrained italics.

*_id* +
__optional__

Then you get the result that you want.

@codynguyen

This comment has been minimized.

Copy link
Author

commented Feb 15, 2017

Thanks @JBR69 & @mojavelinux for your answers.

I haven't actually tried them yet because they require making changes directly in the adoc file, while my adoc file is generated by http://swagger2markup.github.io/. I'm asking the guys at swagger2markup to see if there's any option to produce the adoc with your suggested markup.

I also wonder if this can be considered a bug in asciidoctor and if it can be fixed in order to support words prefixed by an underscore? Otherwise I think it's OK to close this issue

@elextr

This comment has been minimized.

Copy link

commented Feb 24, 2017

Its an implementation issue that Asciidoctor, Asciidoc Python and several other lightweight markup implementations have.

They parse and process each markup type one at a time, so when the parser is processing italic markup and it sees the underscore ahead of id it is not aware that this is inside the stars markup and finds the underscore after optional as a match, whereas since there is no matching end underscore also inside the stars then it should be recognised that it can't be markup and can just be left as text.

This can only be solved by a full language parser which would recognise the star markup and therefore only recognise markup that nested properly. Unfortunately such a parser is extremely difficult for markup languages which are highly context dependent (so ruling out most formal tools and methods) and are also full of that human language rubbish that isn't parsable :).

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Feb 25, 2017

Nice explanation @elextr.

I don't think it's that difficult to write such a parser. There will be some edge cases we'll need to deal with, for sure, but we'll get there. I just need time and resources to do it, which I'm working to amass.

I want to point out that if a word has a leading underscore, and there's a matching underscore at the end of another word (e.g., _word blah blah word_), that's actually a valid formatting request. Not even a proper parser would prevent that match. (It could be programmed to honor backslashes independent of matching pairs, which is one of the open requests in Asciidoctor). On the other hand, if that underscore is inside another formatting mark, then the range of formatting should be restricted to be inside that format context as well. So in your specific case (e.g., *_id*), you could argue that the underscore should be treated literally. But that would only come with a proper parser. So really, this is just another test case for #61.

@mojavelinux

This comment has been minimized.

Copy link
Member

commented Feb 25, 2017

I added the test case to #61, so we can close this issue as the information has been preserved there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.