ceylon/ceylon-compiler

ceylon doc: problem with backticks in inline code at the start of a line

Closed this issue · 3 comments

lucaswerkmeister commented

Compare the documentation of the following functions (use copy+paste, don’t type it out by hand: there’s a difference between 2 and 3):

"""foo
   `` `class Object` `` is a *meta literal*.
   bar"""
shared void beginningOfLine() {}
"""foo
    `` `class Object` `` is a *meta literal*.
   bar"""
shared void leadingSpace() {}
"""foo
    `` `class Object` `` is a *meta literal*.
   bar"""
shared void leadingNbsp() {}
"""foo
   other `` `class Object` `` is a *meta literal*.
   bar"""
shared void leadingOther() {}

Here’s how the markdown is rendered by Github:

  • beginningOfLine

foo
class Object is a meta literal.
bar

  • leadingSpace

foo
class Object is a meta literal.
bar

  • leadingNbsp

foo
class Object is a meta literal.
bar

  • leadingOther

foo
other class Object is a meta literal.
bar

(The line breaks are incorrect because GFM always inserts line breaks for newlines.)

And here’s how the markdown is rendered by ceylon doc:

  • beginningOfLine

foo
bar

  • leadingSpace

foo
bar

  • leadingNbsp

foo class Object is a meta literal. bar

  • leadingOther

foo other class Object is a meta literal. bar

That is, if a line starts with nothing other than spaces (meaning the identity of U+0020, not the Unicode category “Separator, Space [Zs]”, which also contains the No-Break Space U+00A0 as seen in leadingNbsp) and then a multi-backtick code block containing backticks `code` with backticks`, then strange behavior occurs.

This also occurs in the Eclipse IDE even though AFAIK they render documentation independently of ceylon doc; do they share the same Markdown library?

Side question: is the statement in the doc strings above even correct? The name “meta literal” is used in the grammar (that’s how I stumbled over this bug, in ceylon.formatter), but not in the spec.

Phew, that was a lot of meta-markdown :) Thanks a lot @tombentley for showing me Markdown’s multiple backticks feature a few weeks ago – without that, this would’ve been a nightmare.

lucaswerkmeister commented

Looks like an issue of your Markdown library, rjeschke/txtmark... should I move the issue there?

thradec commented

Looks like an issue of your Markdown library, rjeschke/txtmark... should I move the issue there?

yes, please, thanks a lot!