Bold Source Code and Escaping

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Bold Source Code and Escaping

rwinch
I would like to draw attention to a new line of code that has been added to a code snippet by making it bold.  Is there a way to support making source code bold when it contains *? For example, I would like to bold ".antMatcher("/resources/**").permitAll()" within the following code snippet:

NOTE: I do not wish to use a callout in this case because it feels a lot like having an outline with a single section.

.MyCode.java
[source,java]
[subs="verbatim,quotes"]
----
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/resources/**").permitAll()
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
    }
----

The issue I am struggling with is that I have not found a way to ensure my code renders as code (i.e. use verbatim), allow for having part of the code as bold (i.e. use quote), and escape the * characters (along with other quote markup). Any help would be greatly appreciated.

Cheers,
Rob Winch
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

asotobu
I am not pretty sure if this is possible because code is styled by using a highlighter.
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

rwinch
Thank you for the quick reply.

I think something like this would be valuable. Do you think this feature might be considered for a future release? It seems like the support is most of the way there. For example, the following renders as "Hello <strong>bold</strong>" as I would expect:

.MyCode.java
[source,java]
[subs="verbatim,quotes"]
----
Hello *bold*
----

The only thing that appears to be missing is toggling on/off "quotes" within the snippet.
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

mojavelinux
Administrator

Rob,

As you have cited, custom substitutions are supported on the source block (and any block, for that matter):

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

If you want to enable the quotes in an ad-hoc way, then you'll want to enable macros on the block and use the inline pass:[] macro, which allows substitutions to be specified:

[source,java]
[subs="verbatim,macros"]
----
System.out.println("No *bold* here");
pass:verbatim,quotes[System.out.println("Hello *bold* text");]
----

Unfortunately, this introduces additional markup into the Java source that makes it invalid in raw form...though the output it produces will be valid. So, hopefully it gets you by today.

An idea that stems from this is to allow the substitutions to be enabled on a given line from outside the source code. That's probably best handled in a BlockProcessor (coming in 0.1.4) or a BlockFilter (planned for the subsequent release).

Let me know if that works for you, or if you need more info.

Cheers,

-Dan


On Mon, Aug 19, 2013 at 11:33 AM, rwinch [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thank you for the quick reply.

I think something like this would be valuable. Do you think this feature might be considered for a future release? It seems like the support is most of the way there. For example, the following renders as "Hello <strong>bold</strong>" as I would expect:

.MyCode.java
[source,java]
[subs="verbatim,quotes"]
----
Hello *bold*
----

The only thing that appears to be missing is toggling on/off "quotes" within the snippet.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Bold-Source-Code-and-Escaping-tp464p466.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

rwinch
Dan,

Thank you for your very informative response.

I may just be missing something, but I don't think this solves my initial use case (correct me if I am wrong). I would like to bold a line with two ** in it. For example the following bolds the first half of the line, but the bold ends as soon as it hits the ** within the code.

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                pass:verbatim,quotes[**.antMatchers("/resources/**").permitAll()**]
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
----

I tried escaping the code's ** using $$, but I believe the verbatim gets in the way of $$ working. I also tried removing the verbatim from the macro and using $$ as shown below, but it is still not working as I would like:

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                pass:quotes[**.antMatchers("/resources/$$**$$").permitAll()**]
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
----

 It may be something I am just missing, so if anyone can help me with this last piece I'd be extremely grateful.

Thanks again,
Rob Winch
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

mojavelinux
Administrator
Rob,

Aha! I see that I missed the special case. The circumstances here require that we get into a little bit of yak shaving. You'll be quite surprised that it's very solvable.

I've come up with not one, but two solutions to the challenge. First, we'll finish the solution you started.

1. Double dollar escaping

You are correct to think that the double dollar will escape the second occurance of ** to allow the bold to stretch the whole line. In your case, though, the double dollar is not used because it's a macro and macros are not enabled on your pass:[] macro. Thus, simply enabling macros using pass:verbatim,quotes,macros[] will allow it to work (technically the verbatim isn't needed here since there's nothing to escape).

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            pass:verbatim,quotes,macros[**.antMatchers("/resources/$$**$$").permitAll()**]
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();
----

TIP: You can also use triple plus instead of double dollar, which is even more strict about escaping.

2. Use an empty attribute to interrupt the markup

Since the ** is closing your span of bold text, you can use an attribute to get in between the two asterisks and keep them apart during parsing:

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            pass:verbatim,quotes,attributes[**.antMatchers("/resources/\*{empty}*").permitAll()**]
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();
----

NOTE: You still need to escape the bold marks around {empty} or else it will bold the empty text.



Of course, now that I realize you are talking about escpaing formatting, and not turning on the formatting on a per-line basis, you can just skip the pass macro and enable quotes and macros on the whole block.

[source,java]
[subs="verbatim,quotes,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            **.antMatchers("/resources/$$**$$").permitAll()**
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();
----

Btw, to save some typing and ensure consistency, I recommend making the substitution set an attribute on the document:

:markup-in-source: verbatim,quotes,macros

[source,java]
[subs="{markup-in-source}"]
----
...
----

Btw, a totally different solution to this problem (in the upcoming Asciidoctor 0.1.4) is to to introduce a Treeprocessor extension that goes through all source code blocks (or ones marked with a certain role) and look for special markup which indicates the line should be emphasized in some way. For instance, you could type it as:

[source,java]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .antMatchers("/resources/**").permitAll() // (*)
            .anyRequest().authenticated()
            .and()
        .formLogin()
            .loginPage("/login")
            .permitAll();
----

The Treeprocessor would examine the contents looking for the "// (*)" suffix and rewrite the line so that Asciidoctor will format it appropriately. This is probably more of a long-term approach to keep the docs simple. What's great about Asciidoctor is that hints like these are very possible...all with the aim of keeping docs as simple and clean as possible.

-Dan


On Mon, Aug 19, 2013 at 8:47 PM, rwinch [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan,

Thank you for your very informative response.

I may just be missing something, but I don't think this solves my initial use case (correct me if I am wrong). I would like to bold a line with two ** in it. For example the following bolds the first half of the line, but the bold ends as soon as it hits the ** within the code.

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                pass:verbatim,quotes[**.antMatchers("/resources/**").permitAll()**]
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
----

I tried escaping the code's ** using $$, but I believe the verbatim gets in the way of $$ working. I also tried removing the verbatim from the macro and using $$ as shown below, but it is still not working as I would like:

[source,java]
[subs="verbatim,macros"]
----
protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                pass:quotes[**.antMatchers("/resources/$$**$$").permitAll()**]
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
----

 It may be something I am just missing, so if anyone can help me with this last piece I'd be extremely grateful.

Thanks again,
Rob Winch


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Bold-Source-Code-and-Escaping-tp464p472.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Bold Source Code and Escaping

rwinch
Dan,

Thank you so much for the detailed response. This is exactly what I was looking for. I cannot wait to streamline this using a Treeprocessor when the next release becomes available.

One follow up question I had was "Is there a reference to specify that $$ is a macro?" I figured out that * was based upon its context within the document, but I was wondering if there was a handy reference to state how each item was enabled. This reference may be handy for me when trying to determine how to create my other block elements.

Thanks again,
Rob Winch

PS: I'm loving asciidoctor more and more every day; the excellent community certainly adds to this excitement. If you are interested in open source projects using asciidoctor, I thought I would mention that I am migrating Spring Security [1] to use  asciidoctor. By migrating from docbook to asciidoctor, I am confident we will get more developers contributing to our documentation. Thanks again for your efforts!

[1] http://www.springsource.org/spring-security