Add support for source highlighters implemented in Java

[robertpanzer]

Now that Asciidoctor allows to plug in source highlighters it should also be possible to register Source Highlighters implemented in Java.

Proposal:

To allow registration of a SourceHighlighter the Asciidoctor interface could provide this:

public interface Asciidoctor {
  SourceHighlighterRegistry sourceHighlighterRegistry();
}

public interface SourceHightlighterRegistry {
  public void register(String name, Class<? extends SourceHighlighter> sourceHighlighter);
}

public interface SourceHighlighter {
  Location getDocInfoLocation();
  boolean isHighlight();
  ??? highlight(AbstractBlock node, String lang, Map<String, Object> opts);
  boolean isWriteStylesheet(Document doc); 
  void writeStylesheet(Document doc, String to_dir);
}

I am not fully clear yet about the return type of highlight(), Java doesn't have native Tuples, the safest bet is probably to create a class with the properties String highlightedSource and int lineOffset.

Similar to the RubyExtensionRegistry it should also be possible to register a Ruby implementation, that is requiring it and registering it.

[mojavelinux]

the safest bet is probably to create a class with the properties String highlightedSource and int lineOffset.

Yes, that I recommend that.

[abelsromero]

I assume this will also be possible with SPI right?

[mojavelinux]

It would be exactly the same as converters (however those get registered).

[abelsromero]

Checking the interfaces, I see we are being hit but the return type again like in the PostProcessor. Non-text formats like PDF won't be supported.

[mojavelinux]

The syntax highlighter API is exclusively for HTML outputs.

…

On Mon, Apr 22, 2019, 14:04 Abel Salgado Romero ***@***.***> wrote: Checking the interfaces, I see we are being hit but the return type again like in the PostProcessor. Non-text formats like PDF won't be supported. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#805 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAATL5ZQT3GQIAH3N5LOMODPRYK6XANCNFSM4HHRQ34Q> .

[ysb33r]

The syntax highlighter API is exclusively for HTML outputs.

I would have hoped that it can be used for special cases like Leanpub as well. So for now we'll have to stick with the workaround that we have

[mojavelinux]

That's not exactly what I meant. I should have said "text-based outputs". As an example, we could definitely support Asciidoctor EPUB3.

I'm confused about Leanpub though. Isn't the output Markdown? So why would you want to syntax highlight into Markdown? Or are you still arriving at HTML in the end? If you could clarify, I think we could certainly support it.

[ysb33r]

Woth Leanpub the source block has to be cpnverted to a Leanpub-style source block. The callouts have to be extracted and places as a second block below teferring to the line numbers in the source block.

So it is not a syntax highlighter, but it will benefit from the API.

[ysb33r]

To illustrate my comments above.

If we start with this Asciidoc

[source,groovy]
----
@InputFiles  // <1>
FileCollection getDocuments() {
    project.files(this.documents)
}

private List<Object> documents
----
<1> Create a getter and annotate with `@InputFiles` or `@OutputFiles`. The purpose of the getter is to translate upon access to a `FileCollection` object.

we end with this Leanpub transformation

{lang="groovy",linenos="yes"}
~~~~~~~~
@InputFiles
FileCollection getDocuments() {
    project.files(this.documents)
}

private List<Object> documents
~~~~~~~~

**Line #1:** Create a getter and annotate with `@InputFiles` or `@OutputFiles`. The purpose of the getter is to translate upon access to a `FileCollection` object.

The transformation is not that hard, it is just the work of of extracting the callouts and calculating the line numbers. This is something I suspect the syntax highlighter API can give us and we can as such remove some code from the converter.

[mojavelinux]

So it is not a syntax highlighter, but it will benefit from the API.

I'm not opposed to this. Like I said, since the output is text, it still conforms.

Where you're going to run into a problem is that core assumes the syntax highlighter is only used for html. (See https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/document.rb#L1229) We could find another way to determine what activates it. However, this is a rather deep rooted assumption. Maybe you could set the basebackend to html and it would work out.

[robertpanzer]

Support for syntax highlighting is part of AsciidoctorJ now and is also documented at docs.asciidoctor.org.