Add attribute for forward slash

[mojavelinux]

The forward slash character can potentially end the Javadoc comment prematurely. Typically it is escaped using {@literal /}. However, since we've got attributes in AsciiDoc, this can be simplified to {slash}. Although AsciiDoc has built-in named replacements like backslash, it does not have slash.

The new attribute can be defined when calling the Asciidoctor render method:

attribute("slash", "/")

An example use case is as follows:

[source,java]
--
/**
 * Javadoc in example code
 *{slash}
public class ExampleCode {}
--

The only catch is that attributes aren't normally substituted in verbatim blocks like source. One workaround is to manually replace the {slash} prior to invoking Asciidoctor.render. (That's currently how the {@literal *} is handled).

Another possible solution is to replace an escaped forward slash prior to invoking Asciidcotor.render.

 *\/

would become

 */

It's an interesting use case, definitely worth exploring.

Btw, the author always has the option of defining the attribute and enabling attribute substitution on the source block, as in:

= Javadoc for Class
:slash: /

[source,java,subs="specialcharacters,attributes,callouts"]
--
/**
 * Javadoc in example code
 *{slash}
public class ExampleCode {}
--

[mojavelinux]

I just toyed around with it, and I think the simplest solution is:

1. Define the slash attribute
2. Replace the character sequence *\/ with */
3. Replace the {slash} attribute with /
4. Replace {@literal char} with char (as it is today)

[mojavelinux]

I'll send a pull request once #2 is merged.

[johncarl81]

Should we also consider the @ symbol? I think we're required to use a {@literal @} as well.

[mojavelinux]

I checked and it doesn't seem to be required. I suppose we should first find the case where it causes an issue so that we best understand the constraint.

...having said that, if it is an issue, then yet, we should have something like {at}.

[mojavelinux]

Ah, I see the case. When there is a word prefixed with @ (like an annotation) that it doesn't recognize, it throws a warning. I was using @author, so it wasn't complaining.