Proposal to add standard form of open block
Of all the delimited blocks in the AsciiDoc language, the open block is the only one that uses a delimiter line (i.e., fence) that doesn't follow the pattern. Whereas a block delimiter is typically a line that's at least 4 characters in length consisting of a single repeating character (e.g., ====
), the open block delimiter is a line that has a fixed length of 2 hyphen characters (--
). (Arguably tables have a different delimiter too, |===
and !===
, but at least those delimiters can very in length).
This inconsistency poses several problems. First, it looks different, thus isn't immediately recognized as a block delimiter to someone learning the language or more difficult to spot for someone familiar with it. More important, it prevents open blocks from being directly nested. Normally, we might say it's best to avoid excessively nesting blocks. However, the open block is the one block that you would want to do this with. Nesting open blocks is a way to represent hierarchical elements not supported inherently in AsciiDoc. For example, nested open blocks can be an elegant way to support custom layouts for landing pages without restoring to embedded HTML. Another important use case for nesting open blocks is to allow an extension to repurpose an open block as a custom block, but still allow the user of that block to use an open block within it. By varying the delimiter length, that would be possible.
The reason the open block delimiter cannot be 4 or more characters long is because that delimiter is already reserved for a listing block (the listing structural container to be exact). Thus, a different delimiter is needed. The character that stands out as the obvious choice is tilde (~
), making the delimiter line at its shortest be ~~~~
.
Here's an example of how that would look:
~~~~
This is an open block.
~~~~
When nested, it would look like this:
~~~~
Here are some boxes:
~~~~~~
Box A
~~~~~~
~~~~~~
Box B
~~~~~~
~~~~
There are several reasons I think the tilde is the right character to choose:
- when used along in the English language,
~
is often shorthand for "approximately" or "about"; I translate to AsciiDoc to mean "no particular meaning" or "some form" - it used to be used as the delimiter for a source block in AsciiDoc.py, but was not carried forward into Asciidoctor; thus, it's never been repurposed in the AsciiDoc syntax and thus available
- the character sits in the middle of the line, making it look nice as a block delimiter
We could consider some other characters which aren't currently used as block delimiters in the AsciiDoc syntax. Next to each I've cited the problem I have with the alternative:
-
#
(####
) - looks very aggressive; could be perceived as a comment -
@
(@@@@
) - looks very busy -
%
(%%%%
) - hard to differentiate the characters, making it difficult to tell how long it is -
|
(||||
) - too tall -
,
(,,,,
) - too easily confused with CSV; just looks like some sort of data input -
$
($$$$
) - looks expensive ;) -
!
(!!!!
) - looks shouty -
?
(????
) - looks confused or like some sort of application fault
In the end, it seems to me like ~
is the clear choice. If someone has a counter proposal, please come forward and make a strong case why it should be considered.
By adding this standard form, I think we should mark the non-standard form (--
) as deprecated in the syntax. However, the grammar would still have to allow --
for backwards compatibility.
I think what we should remove is the ability for the open block to masquerade as another structural container. Having to change the parsing model based on the style attribute makes it extremely tricky to define a grammar. It may still be possible to allow the style to set the name of the block (from open to sidebar, for example), but it will still be parsed as an open block first. Thus, the open block couldn't masquerade as a passthough or verbatim block.
This issue is open for comment until March 22, 2023. At that point, the proposal will either be accepted or the comment period will be extended if there are still discussions that need to be settled.