Asciidoctor :: Discussion

Mixing bold markup and literal asterisks

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

oddhack

Feb 23, 2018; 12:03am

Mixing bold markup and literal asterisks

51 posts

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*

abelsromero

Feb 23, 2018; 7:15am

Re: Mixing bold markup and literal asterisks

242 posts

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.

mojavelinux

Feb 23, 2018; 10:30am

Re: Mixing bold markup and literal asterisks

Administrator

2681 posts

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

... [show rest of quote]

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

mojavelinux

Feb 23, 2018; 10:30am

Re: Mixing bold markup and literal asterisks

Administrator

2681 posts

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
... [show rest of quote]

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

... [show rest of quote]

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

oddhack

Feb 23, 2018; 12:57pm

Re: Mixing bold markup and literal asterisks

51 posts

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.

abelsromero

Feb 23, 2018; 1:52pm

Re: Mixing bold markup and literal asterisks

242 posts

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.