Arbitrary code block doesn't receive syntax highlighting

[Hubro]

A snippet of my rdoc:

Example - Basic usage:

  waypoints = [
    Rozi::Waypoint.new(latitude: -12.7, longitude: -58.0, name: "South America"),
    Rozi::Waypoint.new(latitude: 43.7, longitude: -103.7, name: "North America"),
    Rozi::Waypoint.new(latitude: 49.6, longitude: 20.9, name: "Europe")
  ]

  Rozi.write_waypoints(waypoints, "file_path.wpt")

Example - More verbose usage:

  file = WaypointFile.open("file_path.wpt", "w")
  metadata = WaypointMetadata.new(datum: "WGS 84")

  file.write_metadata(metadata)
  file.write(waypoints)
  file.close

Example - Even more verbose usage:

  file = WaypointFile.open("file_path.wpt", "w")
  metadata = WaypointMetadata.new(datum: "WGS 84")

  file.write_metadata(metadata)

  waypoints.each { |wpt|
    file.write_waypoint(wpt)
  }

  file.close

It renders like this:

If I remove the loop, it renders correctly:

Is this a bug, or am I doing something wrong?

[lsegal]

Seems like it might be an issue with the RDoc or markdown libraries you are using (not sure if you are using rdoc or markdown here). I can't directly see the generated markup but my guess is (based on the different styling) it's missing a container that is helping YARD detect it as a source block. Either that or YARD is trying to parse this as Ruby and the internal Ruby parser is failing.

Basically YARD itself is deferring this decision to either your markup formatter or Ruby's syntax parser (ripper), so if either of those fail, YARD falls back to "not Ruby code" and doesn't highlight. Not sure which one of these is failing.

[Hubro]

To clarify, the file in question is called README.rdoc and everything should be parsed as RDoc by YARD

[DanRathbun]

Just adding a "This happened to me" notice.

I'm using markdown as the markup, and I had an example snippet of code the was not color lexing.

But there was a clue in the way it was output. ... The beginning of several lines within the {...} block (and at the end for the closing curly,) were not lined up correctly.

Sure enough, checking the code,..there were tabs at the line beginnings instead of spaces.
Replacing all tabs with spaces solved it. The code statements all lined up and color lexing came back on.

I now realized that you cannot just cut & paste code snippets from webpages without "cleaning" them.

[thomthom]

@Hubro - did you figure out a solution for this?

I see something similar:

/**
 * Document-class: Foo
 *
 * Hello World - this is an example:
 *
 *   # This works. Marked as <pre class="code ruby">
 *   foo = 3 + 5
 *
 * And this is another example:
 *
 *   # This doesn't work. Marked as <pre class="ruby">
 *   class Foo
 *   end
 *
 * It appear that the CSS styles for whatever get interpreted as Ruby is
 * missing. And I don't understand what triggers the toggle.
 */


// Hello Foo World.
void Init_Foo() {

  g_rbFoo = rb_define_class("Foo", rb_cObject);

  rb_define_method(g_rbFoo, "world", VALUEFUNC(_wrap_world)
                   , 0);

  rb_define_method(g_rbFoo, "hello", VALUEFUNC(_wrap_hello),
    0);
}

The result:

The resulting HTML: https://gist.github.com/thomthom/bb182ae6b3b3c01ae7fd

[Hubro]

@thomthom Sorry no, I think I just gave up and moved on assuming it would probably be fixed in the future.

[lsegal]

@thomthom I can't reproduce that behavior on 0.8.7.6 or master. What markup format and provider are you using? Seems to work with rdoc v4.2.0 as the RDoc markup provider, i.e., with no flags passed to yard. If I pass in yard -m markdown, it doesn't markup ether code block, but that's because markdown requires 4 spaces for a code block, not 2. This is likely an issue with the specific markup provider, but without knowing which (and what version), it's hard to say for sure.

[thomthom]

I'm running YARD from master, using simply yardoc *.cpp.

[thomthom]

Mind you, I just ran gem list and it seems that I have rdoc (4.0.0). It should be noted that I'm running Ruby 2.0 as default - as that matches the Ruby environment I have to work with. I'll see if running a newer Ruby version or updating the rdoc gem fixes this.

[thomthom]

Sure enough - that was it. I guess I was under the presumption that installing YARD (or any gem) would cause the needed dependencies to update.
This fixes the issue for me. (I'll make a note of making sure all gems are up to date.)

[lsegal]

@thomthom YARD doesn't take any dependencies on markup libraries because RubyGems has no concept of "optional dependencies". YARD only needs rdoc if you use rdoc markup, similarly, it only needs a markdown library if you use .md files (and it certainly does not need all of the libraries that YARD supports).

That said, even if we listed rdoc as a dependency, YARD is technically compatible with rdoc all the way back to 2.x, so that's the dependency we would have listed (>= 2.x). This specific issue comes from a regression in an update that is otherwise compatible, possibly in an update that comes after YARD would have locked it's version number down, and is not something we can control or predict.

[lsegal]

Marking this as closed since the issue is due to a regression in rdoc.