Asciidoctor-pdf: Allow bolding of text in a code snippet
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.
rlopez133
All 34 comments
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
DavidGamba
on 9 Jun 2015
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.
mojavelinux
on 9 Jun 2015
Fantastic! Is there a way to escape the * character as well?
rlopez133
on 9 Jun 2015
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\'*
----
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
on 9 Jun 2015
@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
on 9 Jun 2015
It's probably best to use the double asterisks in this context to be very clear about what the goal of the markup is.
mojavelinux
on 9 Jun 2015
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 :)
rlopez133
on 9 Jun 2015
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).
mojavelinux
on 10 Jun 2015
As stated, removing the compat-mode did the trick!
rlopez133
on 10 Jun 2015
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*`
Obviously I wasn't thinking this morning, used a simple search and replace for all that and fixed.
rlopez133
on 10 Jun 2015
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" [email protected] 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
https://github.com/asciidoctor/asciidoctor-pdf/issues/180#issuecomment-110831836
.
mojavelinux
on 10 Jun 2015
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:
rlopez133
on 12 Jun 2015
When you enable the quotes substitution, you get all the formatting, including in this case backticks. You need to escape the first backtick.
mojavelinux
on 12 Jun 2015
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
on 12 Jun 2015
...it's also easier to work around edge cases that way since it's not a burden on the writer.
mojavelinux
on 12 Jun 2015
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.
mojavelinux
on 14 Jun 2015
@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.
rlopez133
on 16 Nov 2015
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
on 7 Dec 2015
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.
mojavelinux
on 7 Dec 2015
@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
on 21 Apr 2016
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 protected]> <-- Need to be replaced with > and < to make asciidoctor happy
----
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 protected]>
or
[subs="verbatim,quotes"]
#>gpg --edit-key XXXXXXXXXXX
....
[ unknown] (1). XXXXXXXXX XXXXXXXX <[email protected]>
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
on 22 Apr 2016
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.
mojavelinux
on 22 Apr 2016
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
on 26 May 2016
Hi,
Could anyone help with the issue I asked about above? Thanks.
JoeSadusky
on 2 Jun 2016
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?)
krimple
on 19 Jun 2017
@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
on 19 Jun 2017
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
on 19 Jun 2017
In the end, this is really an engineering problem ;)
mojavelinux
on 19 Jun 2017
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.
krimple
on 19 Jun 2017
:+1:
mojavelinux
on 19 Jun 2017
Related issues
kytrinyx
·
7Comments
aokiplayer
·
8Comments
igagis
·
8Comments
amieiro
·
6Comments
andswitch
·
7Comments
Most helpful comment
This requirement can be accomplished using the following:
The "quotes" substitution enables inline formatting.
Also see http://asciidoctor.org/docs/user-manual/#applying-substitutions.