Highlight Select Lines with Rouge

[noraj]

I'm experiencing a different behavior than the one explained in https://docs.asciidoctor.org/asciidoc/latest/verbatim/highlight-lines/#rouge.

With asciidoctor-pdf (PDF)

Instead, I have

• line highlighting working even without docinfo when using rouge
• also adding a docinfo is not taken into account

With asciidoctor (HTML)

• Works as in the documentation.

Steps to reproduce

Without docinfo ruby.adoc

= Test document
:source-highlighter: rouge

[source,ruby,highlight=2..4]
----
# The Greeter class
class Greeter
  def initialize(name)
    @name = name.capitalize
  end

  def salute
    puts "Hello #{@name}!"
  end
end

# Create a new object
g = Greeter.new("world")

# Output "Hello World!"
g.salute
----

asciidoctor ruby.adoc

asciidoctor-pdf ruby.adoc

With docinfo ruby.adoc

= Test document
:source-highlighter: rouge
:docinfo: shared

[source,ruby,highlight=2..4]
----
# The Greeter class
class Greeter
  def initialize(name)
    @name = name.capitalize
  end

  def salute
    puts "Hello #{@name}!"
  end
end

# Create a new object
g = Greeter.new("world")

# Output "Hello World!"
g.salute
----

docinfo.html

<style>
  pre.rouge .hll {
    background-color: rgb(255, 204, 204);
  }
  pre.rouge .hll * {
    background-color: initial;
  }
</style>

asciidoctor ruby.adoc

asciidoctor-pdf ruby.adoc

Suggestions

Options:

1. Implement the same behavior for asciidoctor-pdf as for asciidoctor and as implemented on the documentation, for consistency
2. Edit the documentation at https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/edit/main/docs/modules/verbatim/pages/highlight-lines.adoc to warn about the different behaviors when using asciidoctor or asciidoctor-pdf

[mojavelinux]

There are always going to be slight presentation differences between HTML and PDF because they are different mediums. Sometimes the difference is because it better suits the medium, sometimes its because the presentation styling for that medium doesn't offer the same capabilities. I don't think this needs to be emphasized, especially not in the docs about the AsciiDoc Language since that has nothing to do with the converters. It could be stated in the intro for Asciidoctor PDF.

In this case, lines are highlighted from edge to edge because that is the only styling we could achieve that looks good. It's not the only way to highlight selected lines. Some people prefer that only the code is highlighted.

Since Rouge's themes don't provide styles for line highlighting, it is necessary to add them using docinfo or similar. Since the docs are suggesting a set of styles to use, I think it is reasonable to add the necessary display property in order to enable block (edge to edge) highlighting. Here's the style that needs to be added:

pre.rouge .hll {
  display: block;
}

(Btw, docinfo is not relevant when converting to PDF).

[noraj]

It could be stated in the intro for Asciidoctor PDF.

There https://github.com/asciidoctor/asciidoctor-pdf/blob/v2.3.x/docs/modules/ROOT/pages/syntax-highlighting.adoc?plain=1? Could I PR?

[mojavelinux]

I was suggesting that we could add disclaimer to https://docs.asciidoctor.org/pdf-converter/latest/features/ or https://docs.asciidoctor.org/pdf-converter/latest/ to clarify that there will be some differences in appearances in the PDF output when compared to the HTML output, and most of the time this is expected. However, if a case could be made that they should match up better, we can always revisit it.

...i've already dealt with the difference in how lines are highlighted when using Rouge by updating the recommended supplemental styles at https://docs.asciidoctor.org/asciidoc/latest/verbatim/highlight-lines/#rouge

[noraj]

...i've already dealt with the difference in how lines are highlighted when using Rouge by updating the recommended supplemental styles at https://docs.asciidoctor.org/asciidoc/latest/verbatim/highlight-lines/#rouge

Yeah that's what I read in the first place but when I exported to PDF I was surprised it was not working as expected until I realized it was only with HTML export. That's why I wanted to PR somewhere in the doc to highlight the difference in behavior from HTML and PDF so one reading the doc dos not have to guess what will work, not work or work differently when exporting to PDF.