Allow bolding of text in a code snippet

[rlopez133]

Within a code snippet, I'd like the ability to bold the actual code being run and have the output unbolded to easily distinguish what the user must enter versus what will be displayed as output. As in the example below, I'd like to just bold "cat ceph.conf | grep osd_mount_options_xfs" in my code block.

[DavidGamba]

How are you doing this for the html backend? Should this be a request for asciidoctor core?

Have you considered using a different kind of block? The listing block is only for verbatim output.
http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary

[mojavelinux]

This requirement can be accomplished using the following:

[subs=+quotes]
....
# *cat ceph.conf | grep osd_mount_options_xfs*
osd_mount_options_xfs = inode64,noatime,logbsize=256k
....

The "quotes" substitution enables inline formatting.

Also see http://asciidoctor.org/docs/user-manual/#applying-substitutions.

[rlopez133]

Fantastic! Is there a way to escape the * character as well?

[rlopez133]

Trying to do something like: where I'm escaping the quote (') and the (*)

[subs=+quotes]
----
# *./cardiff.py -p \'/var/lib/edeploy/health/install/results/PowerEdge\*.hw\'*
----

[mojavelinux]

In certain cases you can escape the * character using a backslash. But Asciidoctor doesn't implement full escaping rules. Usually it just works if it would otherwise match as formatting.

Another option is to enable the attributes substitution also and use {asterisk}.

Yet another option is to instead enable the macros substitution and be explicit about where you want formatting.

[subs=+macros]
....
# pass:q[*cat ceph.conf | grep osd_mount_options_xfs*]
osd_mount_options_xfs = inode64,noatime,logbsize=256k
....

The q after pass: is shorthand for the quotes (i.e., formatting) substitution.

[mojavelinux]

@rlopez133 In your case, using double asterisks would work around the issue:

[subs=+quotes]
----
# **./cardiff.py -p '/var/lib/edeploy/health/install/results/PowerEdge*.hw'**
----

Btw, no need to escape the single quotes unless you are running with compat-mode on (which is not the default).

[mojavelinux]

It's probably best to use the double asterisks in this context to be very clear about what the goal of the markup is.

[rlopez133]

Definitely like the double asterisks (easier to use too). However, doesn't seem to bold everything or at least some looks bolder than the other. I'd say the /var/lib/..../PowerEdge* is darker than the cardiff.py but my eyes could be deceiving me too :)

[mojavelinux]

It seems like you have compat-mode on because the single quotes are being interpretted as italic. In the M+ 1mn font, italic is just another font weight, not a slant.

If you have compat-mode on, then you need to write it as:

[subs=+quotes]
----
# **./cardiff.py -p \'/var/lib/edeploy/health/install/results/PowerEdge*.hw'**
----

But it would be far better to turn off compat-mode (look for an attribute at the top of the document or an attribute being passed to Asciidoctor, however you are invoking it).

[rlopez133]

As stated, removing the compat-mode did the trick!

[rlopez133]

Dan,
Now that I've removed compat-mode, any text that I was using for bold-monospace using the following syntax

+*yum*+

Turns into, for example, in the generated pdf

*yum*

I have massive amounts of items in my doc that I used the +word+, is there an easier way to get the same behavior as before without changing everything to something like below?

`*yum*`

[rlopez133]

Obviously I wasn't thinking this morning, used a simple search and replace for all that and fixed.

[mojavelinux]

Super!

As a reminder, be sure to keep the migration page handy.

http://asciidoctor.org/docs/migration

Cheers!

-Dan
Le 10 juin 2015 10:53 AM, "rlopez133" notifications@github.com a écrit :

Obviously I wasn't thinking this morning, used a simple search and replace
for all that and fixed.

—
Reply to this email directly or view it on GitHub
#180 (comment)
.

[rlopez133]

For some reason I cannot get this to bold correctly:

. Use the `*yum*` package manager to install the packages and any of their dependencies with the following command:
+
[subs=+quotes]
----
# **yum install `awk '{print $1}' ./req-rpms.txt`**
----

Output:

[mojavelinux]

When you enable the quotes substitution, you get all the formatting, including in this case backticks. You need to escape the first backtick.

[mojavelinux]

If you are going to bold all the commands, I think a better approach is to use an extension for this. Specifically, I recommend a Treeprocessor that analyzes all the listings and makes the appropriate change to the source in the AST. I'm concerned that you are reducing the maintainability of the source text by adding formatting that a computer could figure out.

[mojavelinux]

...it's also easier to work around edge cases that way since it's not a burden on the writer.

[mojavelinux]

I've noticed that this stops working if syntax highlighting is used on the block. I'll need to look into what's happening there. The order of substitutions isn't working out right in that case.

[rlopez133]

@mojavelinux Can you elaborate more on the comment "....using an extension for this"? I'm tending to use this on all blocks. If I don't need to add this everywhere and there is an easier way I'm all for it.

[mojavelinux]

What you want to use here is a Treeprocessor. A Treeprocessor lets you query for all listing blocks:

# Find listings that are command line statements
commands = (doc.find_by context: :listing).find_all {|b|
  (first_line = b.lines.first).start_with?('$ ') || first_line.start_with?('# ')
}

At this point, you would have to parse the command line using something like regexp and replace it with basic HTML. For example, let's say your input is the following:

# yum install `awk '{print $1}' ./req-rpms.txt`

You would want to replace the source lines with:

# <strong>yum install `awk '{print $1}' ./req-rpms.txt`</strong>

Then you'd also need to disable subs on the block so that the code is interpreted literally.

Something like:

commands.each do |c|
  c.lines.replace([c.lines.first.gsub(/^(\$|#) (.*)/, '\1 <strong>\2</strong>')])
  c.subs.clear
end

In the end, we are doing our own source code highlighting, in effect.

I'd be happy to work with you to add such an extension to the extensions-lab. It's very similar to https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/shell-session-treeprocessor/extension.rb and may even been an improvement of that extension.

[mojavelinux]

It's much, much better to keep this type of formatting out of the source document because it isn't semantic information. It is a display concern. Asciidoctor gives you the power to weave in display concerns (like syntax highlighting) during conversion.

[AlexanderZobkov]

@mojavelinux , I confirm that bolding in code snippets does not work anymore. In PDF, text that is expected to be in bold is rendered as <strong>text</strong>.
Example:
input:

[source,java,subs="verbatim,quotes"] 
----
System.out.println("Hello *bold* text"). 
----

output:

System.out.println("Hello <strong>bold</strong> text").

[AlexanderZobkov]

One more thing, Is it normal that < and > symbols break formatting and cause errors in blocks like the following?

[subs="quotes"] 
----
#>gpg --edit-key XXXXXXXXXXX
....
[ unknown] (1). XXXXXXXXX XXXXXXXX <email@domain.com> <-- Need to be replaced with &gt; and &lt; to make asciidoctor happy
----

[mojavelinux]

I'll address your section question first. You should almost never set subs without using the incremental setting. That's because it drops the important special character substitution. So you should write it as follows:

[subs=+quotes]
#>gpg --edit-key XXXXXXXXXXX
....
[ unknown] (1). XXXXXXXXX XXXXXXXX <email@domain.com>

or

[subs="verbatim,quotes"]
#>gpg --edit-key XXXXXXXXXXX
....
[ unknown] (1). XXXXXXXXX XXXXXXXX <email@domain.com>

[mojavelinux]

To address your first question, unfortunately, it's not possible to use quotes on a block with syntax highlighting in the PDF converter. There's just no way I've been able to figure out that I can get the order right so that the syntax highlighter doesn't escape the inline HTML. This works in the HTML converter because the order of operations is different.

Simply put, you can either use quote substitution or syntax highlighting, but not both.

If someone is able to figure out how to do it, I'm definitely open to adding it to the converter.

[mojavelinux]

I confirm that bolding in code snippets does not work anymore.

To clarify, bolding in code snippets that are also syntax highlighted doesn't work in the PDF converter. You need to use a listing or literal block instead.

[JoeSadusky]

Hello,

I know this is probably very simple, but is it possible to add bold (or in my case, italics) to an inline code snippet enclosed in [snippet] characters? I know how to use subs for a code block, but not how to make formatting appear correctly in an inline snippet.

[JoeSadusky]

Hi,

Could anyone help with the issue I asked about above? Thanks.

[krimple]

I know this is an old issue, but I'm trying to develop documentation that can be presented as slides and PDF for a training course. I'd like to be able to bold and syntax highlight in both reveal and PDF output targets. Without something that can handle both it makes Asciidoc not ideal for a Markdown replacement for my training (which has its own issues, one of them being syntax in fenced blocks cannot be styled, just highlighted). Is there some approach that works with a macro or some kind of context (if we're generating PDF, add quote subs but don't syntax highlight, and if we're generating HTML, add both for example?)

[mojavelinux]

@krimple At the moment, you can have formatted text in a listing block or you can have syntax highlighting, but not both at the same time. The reason comes down to the fact that adding the formatting confuses the highlighter (and vice versa).

Having said that, it's very straightforward to add line-based highlighting in the syntax highlighter. We already support this in some places in the Asciidoctor ecosystem, so it's just a matter of adding that support to Asciidoctor PDF. This is described in #681.

[mojavelinux]

if we're generating PDF, add quote subs but don't syntax highlight, and if we're generating HTML, add both for example?

This ultimately feels like a hack to me. And since adding formatting at the character level requires changing the example source code, it really requires having two separate samples.

Generally, I recommend against adding formatting at the character level. That modifies the sample and makes it impossible to validate (so you run the risk of broken samples). It's better to externalize the information about which lines or characters to emphasize. I think that can be done either using emphasized lines or, where possible, a custom highlighting lexer (using the native highlighting ability of the source highlighter).

[mojavelinux]

In the end, this is really an engineering problem ;)

[krimple]

Yeah, I can see getting it to emphasize, perhaps doing the cueballs, and forgetting the bolding. If we did externalized samples for our manuals that'd make even more sense. Just curious if there was a way found. At least I have options.

[mojavelinux]

👍

[mojavelinux]

Our position on this issue is that you cannot mix the quote subs with syntax highlighting on a code block. I don't know any way it could work out of the box. So it's either one or the other. If you can prove to me it can be done, please come forward with that solution.

If you need to be able to emphasize fragments, and callout numbers don't work for you, the only thing I can suggest is to create a custom lexer for Rouge, etc that will understand how to process the formatting marks.