Mixing bold markup and literal asterisks

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Mixing bold markup and literal asterisks

oddhack
I'm running into another misunderstanding of how to escape formatting marks in asciidoctor so they appear in the output as themselves. In this case I'm trying to mix literal '*' characters (as used in C declarations) with a bold style applied to nearby text, so as to get text like

*foo  // With leading asterisk visible
bar   // In bold

The only way I have been able to get this to work is using pass:[*] around the literal asterisk, which is very verbose and intrusive on writing the source markup. Is there a reliable way to do it with \ escapes or other short notation? My recollection from previous related discussions is that \ escapes are done heuristically with a lot of non- or poorly-documented exceptions, and I suspect I've run into one. Simple test case follows.

Jon

-------------------------------------------------

= Test

Doesn't work. 'foo' is in bold, without leading asterisk:

*foo +
*bar*

Works, but very verbose:

pass:[*]foo +
*bar*

Doesn't work. '*bar*' is rendered with asterisks and no bold:

\*foo +    
*bar*    
Reply | Threaded
Open this post in threaded view
|

Re: Mixing bold markup and literal asterisks

abelsromero
I suspect, the passthrough macro this is the only way. But I feel you are focusing too much in the format instead of focusing on describing the purpose of the text.

If you want to scape a piece of text, yes, I fear there's no other way. But I would not constrain it to the character itself, but the whole text I want to describe as literal.
Also, consider different approachs, if what you want is highlight some text inside some other that is literal (code, example, etc). Mark the whole block as literal and use  a pass macro to enable bold processing of the text you want in bold (like in here http://asciidoctor.org/docs/user-manual/#inline-pass-macro-and-explicit-substitutions.). Also, you can just use callouts in a literal block.

With more onfo in waht you want to achieve maybe we can provide more help.
Reply | Threaded
Open this post in threaded view
|

Re: Mixing bold markup and literal asterisks

mojavelinux
Administrator
You're content happens to match a perfectly valid syntax in AsciiDoc, which are the boundaries of a bold region.

*foo +
*bar*

It does not matter that they are on different lines, consistent with the rules of the scope of constrained formatting in AsciiDoc. So when you escape the first asterisk, what you are saying is don't bold what would have been formatted in bold. It doesn't change where it looks.

Abel wrote:
But I would not constrain it to the character itself, but the whole text I want to describe as literal. 

That's precisely what I was going to suggest, so I second that. I'd do something like:

pass:[*foo] +
*bar*

though it's more correct to use:

+*foo+ +
*bar*

The single plus escapes formatting but does not prevent special character substitution for HTML output. Currently, the single plus escaping is preferred over backslash escaping. That could change in the future with a better inline parser, but that's where we are today.

Anther option is to tuck the star away in an attribute:

{star}foo +
*bar*

Then the inline formatter won't treat is as a formatting character.

I hope that gives you some options.

Cheers,

-Dan

On Fri, Feb 23, 2018 at 12:15 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I suspect, the passthrough macro this is the only way. But I feel you are focusing too much in the format instead of focusing on describing the purpose of the text.

If you want to scape a piece of text, yes, I fear there's no other way. But I would not constrain it to the character itself, but the whole text I want to describe as literal.
Also, consider different approachs, if what you want is highlight some text inside some other that is literal (code, example, etc). Mark the whole block as literal and use  a pass macro to enable bold processing of the text you want in bold (like in here http://asciidoctor.org/docs/user-manual/#inline-pass-macro-and-explicit-substitutions.). Also, you can just use callouts in a literal block.

With more onfo in waht you want to achieve maybe we can provide more help.



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Mixing-bold-markup-and-literal-asterisks-tp6198p6199.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Mixing bold markup and literal asterisks

mojavelinux
Administrator
In reply to this post by abelsromero
You're content

Your content... 

On Fri, Feb 23, 2018 at 3:30 AM, Dan Allen <[hidden email]> wrote:
You're content happens to match a perfectly valid syntax in AsciiDoc, which are the boundaries of a bold region.

*foo +
*bar*

It does not matter that they are on different lines, consistent with the rules of the scope of constrained formatting in AsciiDoc. So when you escape the first asterisk, what you are saying is don't bold what would have been formatted in bold. It doesn't change where it looks.

Abel wrote:
But I would not constrain it to the character itself, but the whole text I want to describe as literal. 

That's precisely what I was going to suggest, so I second that. I'd do something like:

pass:[*foo] +
*bar*

though it's more correct to use:

+*foo+ +
*bar*

The single plus escapes formatting but does not prevent special character substitution for HTML output. Currently, the single plus escaping is preferred over backslash escaping. That could change in the future with a better inline parser, but that's where we are today.

Anther option is to tuck the star away in an attribute:

{star}foo +
*bar*

Then the inline formatter won't treat is as a formatting character.

I hope that gives you some options.

Cheers,

-Dan

On Fri, Feb 23, 2018 at 12:15 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I suspect, the passthrough macro this is the only way. But I feel you are focusing too much in the format instead of focusing on describing the purpose of the text.

If you want to scape a piece of text, yes, I fear there's no other way. But I would not constrain it to the character itself, but the whole text I want to describe as literal.
Also, consider different approachs, if what you want is highlight some text inside some other that is literal (code, example, etc). Mark the whole block as literal and use  a pass macro to enable bold processing of the text you want in bold (like in here http://asciidoctor.org/docs/user-manual/#inline-pass-macro-and-explicit-substitutions.). Also, you can just use callouts in a literal block.

With more onfo in waht you want to achieve maybe we can provide more help.



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Mixing-bold-markup-and-literal-asterisks-tp6198p6199.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Mixing bold markup and literal asterisks

oddhack
In reply to this post by abelsromero
I have been tasked to translate an existing document from Word to asciidoctor, preserving the visual appearance. It's not in my scope to tell them how their document should be formatted, so what I want and need to achieve is just what I said.

I wish there were an actual grammar for asciidoctor, so there's something more concrete to point to when these sorts of issues arise.
Reply | Threaded
Open this post in threaded view
|

Re: Mixing bold markup and literal asterisks

abelsromero
I see the case now.
In that case you can have a look at https://asciidoctor.org/docs/migrating-from-msword/ & https://github.com/rockyallen/asciidoctoressays/blob/master/wordimport/build.xml.

I use the method in the first link to get a quick first version that I tune later. But it's for internal use, and we don't aim to look exactly the same.