commonmark / commonmark-spec

CommonMark spec, with reference implementations in C and JavaScript
http://commonmark.org
Other
4.89k stars 317 forks source link

Spec is confusing on type 7 HTML Blocks #780

Closed toptensoftware closed 1 month ago

toptensoftware commented 1 month ago

For the start condition of a type 7 HTML block the spec says:

line begins with a complete open tag

At various points the spec for an open-tag says they can contain:

and up to one line ending.

I was reading this as if a type 7 HTML block can start with an open tag that contains line breaks - but in fact they can't.

Perhaps the start condition should be worded as "line begins with and contains a complete open-tag", or more explicitly state that the "up to one line ending" doesn't apply for type 7 blocks.

Annastaciahubbard commented 1 month ago

Your above suggestion / explanation has worked for me in the past

wooorm commented 1 month ago

Some sort of “line begins with and contains a complete open-tag” seems good to me

jgm commented 1 month ago

The word "complete" was meant to do the work. But I'm happy to change it as suggested.

jgm commented 1 month ago

Pushing back a little: the current text does say: "begins with a complete open tag...all on a single line". Isn't that sufficiently explicit?

jgm commented 1 month ago

Note: "all on a single line" was added in 800e199b0df62c64b8eaee9a5996a5da6d2bf8bf and is not in the most recent release! I guess someone else had exactly the same problem you did. Isn't the fix sufficient?

toptensoftware commented 1 month ago

The word "complete" was meant to do the work

Yes, but "starts with a complete" makes it confusing - hence my suggestion of "starts with and contains".

Note: "all on a single line" was added

I was going off what's written here so didn't see the 'all on a single line' change.

That covers it, but I still think confusing because it reads like: "a line that starts with an opening tag which can contain new lines but all on one line".

Personally, I think it warrants an explicit comment to make this clear.