Match the block attribute list separately from delimited blocks

[mojavelinux]

The block attribute list should be matched separately from delimited blocks (i.e., structural containers). The match should recognize the following pattern:

[<blockname>,<positional attributes>,<explicit attributes>]

For example:

[ditaa,diagram-name,format=png]

Keep in mind that the blockname also accepts shorthand attributes:

[literal#output.console%nowrap]

There are no fixed block names in AsciiDoc since the block name is itself an extension point. We could recognize some of the block names, like source, to give it special treatment. Otherwise, these lines should be matched independently, just like an attribute entry line.

Our current block matches should be focused only on the structural container part. What happens in the block attribute list should not affect the highlighting of the delimited block, except in special cases like "source", admonition blocks and, perhaps, named paragraphs.

[mojavelinux]

In general, the block attribute line is independent from the block, except in cases like the source block, the admonition block and explicitly named paragraphs. Aside from those exceptions, we should assume that all the information about how to highlight the delimited block is determined by the fences (meaning the structural container).

In general, extensions are encouraged to honor the semantics of the structural container it is enhancing. For instance, an example block should allow complex content and a listing block should only allow verbatim content. Otherwise, it's impossible for the editor to keep track.

[ldez]

For you, is there a difference between explicit-paragraph-grammar.cson and section-grammar.cson ? I explain: For me it's the same pattern grammar, the fixed list of names is unnecessary. And the both are the heading of a paragraph.

wdyt?

[ldez]

maybe a difference:

• section-grammar.cson define elements are always link to a section heading.
• explicit-paragraph-grammar.cson define elements are always link to paragraph.

Am I right ?

[nicorikken]

@ldez but would that make any difference regarding highlighting? Maybe we can keep both lists, and if not matched, fall back to general matching? Or will we than fail on additional attributes?

To me it seems specific blocks [source...] and attribute lists [appendix...] will have to be matched, to add the proper name. There is a general fallback [...] Than the attribute lists can be handed of to a separate matcher which highlights all types of attributes neatly. Right, or am I missing something?

[mojavelinux]

@nicorikken what you're describing is what I envisioned. Obviously, certain block names that provide built-in behavior and we want to respond to those. However, there's such a thing as a generic block name that is handled by an extension. In that case, the name should be ignored and the block should be styled according to the delimiters (if possible).

Technically, there are no restrictions on the block name you give to a section title. Of course, that could change in the future as that's sort of an undefined part of the AsciiDoc language. Perhaps a grammar should be more restrictive there. Those names (e.g., appendix) are primarily for DocBook output, though. (abstract, colophon, dedication, preface, appendix, glossary, bibliography, index, synopsis).

It's also important to point out that a line that looks like a block attribute list is interpreted as a block attribute line no matter where it appears, unless it is inside a listing, literal or pass block. A block attribute line will terminate a paragraph.

[mojavelinux]

You can see a reference to that last point here: https://github.com/asciidoctor/asciidoctor/blob/v1.5.4/lib/asciidoctor/parser.rb#L956-L964

In general, there are 3 things that terminate a paragraph:

• blank line
• delimited block
• block attribute line

Within a list, a list item will also terminate a paragraph.

In the future, we may get more strict and say that only a blank line can terminate a paragraph...but there are a lot of cases to consider before making such a change.