To me the pipe is a little misleading (especially in combination with the dash) in making me instantly think about a table.
If you don’t like the pipe, you can use the colon. Nice things about having two different characters to use is:
you can choose which one looks better in which case (maybe one for side-marked and the other for delimited, or colons for when you’re putting a table in)
when nesting side-marked divs, alternating the side-marker is more readable
Would the initial line of dashed be needed every time or is it optional?
If it’s optional, then it doesn’t really hint towards how the syntax works for delimited cases.
If its obligatory, then it makes creating these boxes rather tedious again.
At least three dashes would be required. Not too tedious, IMO:
| --- {.warning #foo}
| This is the minimal and
| most general syntax for
| the div with class="warning"
| and id="foo".
| --- warning
| This is the minimal syntax
| for the div with just class="warning".
|--- warning
| The space after the pipe (or
| colon) is optional.
: --- warning ---
: You can choose to add
: trailing dashes if you like.
: -------- warning --------
: Use more dashes if you
: think it adds readability.
Having the three dashes then the metadata is reminiscent of how it’s done with code blocks (ex. “~~~{.haskell}” or just “~~~haskell”).
In the end, I think the syntax used has got to be readable, fairly minimal, and needs to look classic enough to not go out of style — and I think that suggests flatter characters for horizontal markings, and taller & thinner for vertical. IMO, the multiple colons is too much; it seems too styled, and also I think somehow looks dated.
A last factor to consider: Although the delimited syntax isn’t perfect
:-------- warning
This is an extremely
long warning consisting
of multiple lines and
maybe paragraphs even!
Content copy/pasted in.
It's delimited, for the
writer's convenience.
:--------
the side-marked style is arguably the more markdownish, readable, and would likely be used more often when the reader is expected to read the content in markdown.
Can’t see how you can’t have sidemarked colon via overloading definitions. The parser isn’t that much complicated. You are compairing between : and :: ( blankline+::: would indicate div fence start)
e.g.
Surrounding text
:: An Example
:: Of a very minimal
:: sidemarked div block
More surrounding text.
Term 1
: Obviously a Definition 1
Term 2
: Obviously a Definition 2
Also markdownish to me, means looks like something you would do in a text email. While : -- is more easier to parse in some sense, it is not as visually appealing as say.
::::::::::::::::::::::::::: WARNING :::::::::::::::::::::::::::
:: # rm -rf / – Deletes Everything! # ::
:: ::
:: The command rm -rf / deletes everything it possible can, ::
:: including files on your hard drive and files on connected ::
:: removable media devices. ::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
Plus markdownish, probbly also means “trivial to explain”. Its easer to tell people to just use lots of ::: rather than | --- . Much like its easier to just tell people to use backtick fences or indentation rather than matching brackets { code here }
One can either go down this path, or follow my suggestion from the description list thread and use ~ name : value or ~ name \n: value instead. Definition/description lists that start with a “value” without a name don’t make a lot of sense, so if you don’t allow those, then it would free the single colon as a marker for div blocks (and remove the need for look-ahead in definition lists).
But i actually like the double colon too. As i said: it has that symetry in it. Probably : vs :: is clear enough for the user, but I’m not sure.
I think using a double colon would be preferable to the single colon as it would ensure that the block marker is the same when it is used both vertically and horizontally (each double colon is a square in the barrier around the block). Allowing the block to be defined with both horizontal and vertical characters gives the writer a choice. Vertical colons are more Markdownish, similar in structure to blockquote syntax, whereas horizontal colons are more convenient to write. For vertical colons you could have a similar rule to blockquotes, only requiring a double colon at the start of every paragraph.
:::::::::::::: warning :::::::::::::
:: The soup must only be stirred ::
:: clockwise. Counterclockwise ::
:: stirrage will result in bland, ::
:: unexciting soup. ::
::::::::::::::::::::::::::::::::::::
★ They are unreasonably onerous to fully type out. I suspect few would type those closing double colons (and take the trouble to add the right number of spaces so they line up). You’d end up instead seeing all of
:::::::::::::: warning :::::::::::::
:: The soup must only be stirred
:: clockwise. Counterclockwise
:: stirrage will result in bland,
:: unexciting soup.
::::::::::::::::::::::::::::::::::::
:::::::::::::: warning :::::::::::::
:: The soup must only be stirred
:: clockwise. Counterclockwise
:: stirrage will result in bland,
:: unexciting soup.
:::::::::::::: warning :::::::::::::
The soup must only be stirred
clockwise. Counterclockwise
stirrage will result in bland,
unexciting soup.
::::::::::::::::::::::::::::::::::::
in the wild, with users guessing as to which is correct.
★ Side-marking with double colons (or any double any characters) don’t nest very well — that is, it’s a lot to type. This may be especially relevant for divs, where they’re often nested quite a bit.
★ If using colons with delimited syntax — along with nesting — you’re going to end up with multiple closing block delimiters that look like a wall of dots:
(A) it’s ok in md to use different characters for side-marking and delimiting (code blocks: spaces for side-marking, tildes or backticks for delimiting), and
(B) md historically uses only a single character for side-marking (ex. blockquotes).
Just like with trailing hashes ## for headers. It’s optional and may beautify it. But those who think that the document might be read in plaintext might want the box to stand out as a box.
all three are.
I think the partial examples also have a nice aspect. The “left and top only” looks like a floating box with some shaddow to me.
The complexity of nesting also depends on whether we allow “lazyness”. Imo lazy blockquotes look very strange when nested, but well, that’s the trade-off for easy authoring.
Single colons would indeed make typing a little easier if we treat the colon exactly like the > in blockquotes.
That would indeed be a compelling argument for your :--- suggestion, especially if we were to introduce similar fenced syntax for blockquotes (and maybe also codeblocks) list this:
But you could use the minimum number of colons needed (e.g. three maybe), or (optionally) use different lengthes to match different nesting levels visually:
(A), yes but this is not out of tradition, but out of necessity.
The tabbed codeblocks only exist because it’s easier to type (as most editors allow easy indenting. Original Markdown has no fenced blocks at all.
The blockquotes are copy-pasteable from e-mails etc. Nobody thought about fenced blockquotes then, because again, there were no fenced blocks back then.
tildes for code-blocks suck anyway. And i think we should go down the logical path of using tripple backticks (or the suggested general block format with ```—``)
(B) true. But why care. Hitting a character twice is not that hard compared to hitting the space bar hundreds of times for indent if the tab key doesn’t work properly in your editor. Also, i think the tradition of markdown is visual sexyness and overview in plaintext more than easy to type (as compared to other lightweight markups).
Having read the entire topic again, my opinions start to shift towards the original post more and more. I just don’t see the need for the three dashes. Thinking of the writers I have to instruct on how to type their reviews, I think I will tell them this way because so far as I can see now it has the balance between being easy to read and easy to type.
The gig was great!
! {.setlist}
1. Track One
2. A Different Tune
The after-party was OK.
The proposed variations in character (both exclamation mark and semicolon) and fencing (delimited and side-marked) are fine. The proposed syntax for nesting is also great. Not sure whether the end delimiter can be a blank line - I would like to have that explicitly mentioned in the definition when this goes live.
I am assuming the {.className} notation for classes and attributes that has become to most-used syntax will make it into the CommonMark definition one day.
The least controversial way forward, I agree. Just not on the three dashes. Well, I do see how it makes it better readable, I won’t vote against the three dashes.
I just don’t see the need for the three dashes. Thinking of the writers I have to instruct on how to type their reviews, I think I will tell them this way because so far as I can see now it has the balance between being easy to read and easy to type.
Well, I do see how it makes it better readable, I won’t vote against the three dashes.