I think that using the delimited code block syntax as a model for a new div syntax is a good idea. It will be familiar to Pandoc users, and will be easy to remember.

Since delimited code blocks require only 3 or more tildes, I think a div syntax requiring only 3 or more characters would be consistent and desirable.

Using dots for delimited divs may not be the best choice because it's not uncommon to type "..." into a document (and "..." & "...." are too similar). Also, since the dot glyphs are at the bottom of a line, the closing dots look a bit odd hanging there all by themselves. Dashes would be nice but are too similar to the tildes used for delimited code blocks. Angle-brackets (greater-thans) might be nice, but are already used for blockquotes. "At" signs are a bit too obtrusive looking, IMO. Percent signs might be ok...

IMO though, forward slashes probably look the nicest:

/// {.some-class #some-id}
some text here some text here
some text here some text here
///

They look unobtrusive enough to me. The "///" is not a pattern that anyone uses in their writing with any regularity (that I know of). And I think that folks who have worked with html will think "closing html element" when they see "///", so that should make users feel fairly comfortable with them.

As for nested divs, I very much do not like the idea of using indentation. In markdown, indentation is for code blocks and for making lists look pretty. :) If you want to support nested divs, but in a way that makes it obvious how many levels deep you are, how about requiring a space between each set of 3 forward slashes:

/// {.foo}
some text here some text here
some text here some text here
some text here some text here
/// /// {.bar}
more text more text more text
more text more text more text
more text more text more text
/// ///
///

uvtc on 29 Dec 2011

As I noted on the mailing list, I like the looks of this:

{.Note #some-id}

paragraph one.

- list
- list
_______________________

Optionally the attribute could be put on the same line as the underlines.

(Note: currently the attribute parser requires the id to come first; this ought to be changed in any case.)

Nesting can be handled the way I handle it with delimited code blocks -- a block is only ended by a string of underline characters that is at least as long than the one that opens it. So, you can use long strings of underlines for outer divs, shorter strings for inner divs.

_________ {#outer-div}
blah
blah
_____ {#inner-div}
ok
_____
blah
blah
____________

jgm on 7 Jan 2012

Yes, I think that syntax fits nicely along with the syntax for delimited code blocks.

The only thing I don't like is using underscores, because:

their glyph is vertically too low on the line. It looks odd to use them, and they look weird hanging there when you close the id/class.
Pandoc Markdown is already using dashes for h2 headings, and for tables, and horizontal rules ... underscores look too similar to them. Too many straight horizontal lines everywhere in ones documents.
multiple underscores already mean "horizontal rule", so human readers wouldn't know if ___ means horizontal rule or closing delimited element

Since Pandoc is already using tildes for delimited code blocks, I think it would be consistent to also use tildes for generic delimited blocks -- _however_, maybe do it like so:

~ ~ ~ ~ ~ ~ {#outer}
blah
blah
~ ~ ~ {#inner}
ok
~ ~ ~ 
blah
blah
~ ~ ~ ~ ~ ~

That is, the repeated pattern is "~ " (with a space), rather than "~" (no space). Some benefits of this syntax:

less obtrusive than forward slashes or underscores
doesn't interfere with the syntax for horizontal rules
adds syntax consistency, that is: "all delimited blocks (code or otherwise) use tildes" --- easy to remember. For that matter: "Blocks of code are dense, so the tildes are dense." ;)
the tilde glyph is in the vertical center, so it looks nice and symmetrical

uvtc on 7 Jan 2012

FWIW I like the tilde-space idea over underscores

hansbkk on 23 Jan 2012

I think that it's desirable that the syntax for divs is
_clearly different_ from the syntax for both horizontal
rules and code blocks, so that neither of the three is
easily mistaken for the other by a human or computer
reader. A distinction between tildes and tildes/spaces
would be unfortunate for two reasons:

It would be directly contrary to the syntax for horizontal rules,
where the following are equivalent:

**** * * * * ---- - - - - ____ _ _ _ _

It would be easy to mistype tilde/space as tilde-tilde,
especially since the tilde key only is available as a
AltGr + deadkey combination on the keyboards of some
countries (admittedly including my own!). While it's
reasonably easy to hold AltGr and hit the right key
eight times to get four tildes in a row, alternately
holding down AltGr and hitting the key twice and
releasing AltGr and hit the spacebar would be a great
nuisance, and lead to frequent typos

The reason I originally suggested a row of four periods
as the syntax for div delimiters was that I was under
the false impression that ==== and ++++ were among
the permitted syntaxes for horizontal rules! My actual
preference was and is for a row of equals signs: as
that is sometimes used as a kind of section
delimiter/cut here in emails in would be a choice in
keeping with the markdown philosophy.

bpj on 25 Jan 2012

+1 for this. I would love to set attributes (especially classes for styling) on more generated entities than just code blocks.

thejohnfreeman on 25 Oct 2012

I agree with the ability to set attributes (at least, id, classes and languages) for other blocks than code blocks.

And having a RawSpan would be also interesting to be able to set attributes to any arbitrary text passage, not being an element. (I'm thinking of languages, but different font properties, such as small caps, fit here.)

The syntax for spans in extended markdown should be different than periods, because this would be misleading.

ousia on 18 Nov 2012

And how about square brackets for marking divs?

[[[ {.note #n32}
this is the div
]]]

ousia on 22 Nov 2012

Wow! This issue is still open. :) Just stumbled upon it searching for something else.

Not sure any of these proposals (including my own from a year ago) are significantly better than just using raw html.

This may be one of those cases where Markdown wins simply by being able to embed raw html.

uvtc on 11 Jan 2013

For your consideration:

Hi.

^^^{#some-id .some-class}
This doesn't
look half bad.
^^^

Next paragraph.

The carets make me think "metadata" (data, ^up there^, see?), and I can live with the space underneath much better than the space above (like you'd get if using dots).

That, together with some [span syntax]{.other-class} would be very nice. :)

uvtc on 22 Oct 2013

Also, the carets look nice; not too obtrusive. Almost look like an underline at the bottom, but go ok at the top too.

Clojure uses a similar caret syntax to mean metadata, and it looks pretty right to me.

And, I think Pandoc is currently only using the caret for footnotes and for superscript, so it wouldn't conflict to allow it to be used here for this purpose (which would always be at least three carats).

uvtc on 22 Oct 2013

What about something from Bash and similar shells?
http://en.wikipedia.org/wiki/Here_document

hholst80 on 13 May 2014

I think it's agreed that some syntax for div and span elements is needed to tidy up markdown code which uses them. This discussion has turned into an exercise in bike shedding.

Suggestions so far include

///
...
\~\~\~
___
^^^
[[[
:::

and various combinations of the above.

To move things forward - I'm personally a fan of ^ and using surround-marking instead of side-marking. I will implement this in the near future and then people can feel free to fiddle with the specifics as they please.

mpickering on 7 Dec 2014

For what it's worth, the most popular idea on the CommonMark forum is :::: http://talk.commonmark.org/t/generic-directives-plugins-syntax/444/100

I'm still undecided, including about side or surround marking, but I think I like ::: better than ^^^.

Also, if anything is done on this, it should work like fenced code blocks -- the opening sequence can be of variable length, and the closing sequence must be of equal or greater length. That allows these things to be nested.

jgm on 7 Dec 2014

^^^ somehow rubs me the wrong way, as it looks like three up-arrows, which doesn't make sense in this context. I still think === would be best as it looks like 'cut here', but if the CommonMark people are leaning towards ::: that's probably what we should use.

Disclaimer: I still feel that smallcaps should be ^^foo^^, so my first thought when seeing ^^^ is 'a block of smallcaps', which is rather silly of me.

bpj on 7 Dec 2014

BTW it has occurred to me that having successively _fewer_ marks for nested divs would lead to unpleasantness if you run out of markers. I'm not convinced that having an editor smack on a few
extra markers to the beginning of each matching line would do the right thing in all cases.

bpj on 7 Dec 2014

I really like === myself. There's more potential for a clash with setext headers, though, which may make ::: safer.

jgm on 7 Dec 2014

@jgm said: I really like === myself. There's more potential for a clash with setext headers, though, which may make ::: safer.

Absolutely true. I keep forgetting that because I always use only ATX-headers. My commandline wrapper is set to pass --atx-headers at all times.

bpj on 7 Dec 2014

Hi there. I'm completely new here, but these are my two cents anyway...
I like the idea of having distinct start and end elements an in

[[[ {.this}
suggestion.
]]]

because that makes the desired result really obvious to both humans and parsers. But markdown started off as a minimal markup, so here's an idea how to simplify this further:

{.this}
is a simple div with class "this".

  {.here}
    is a second div with class "here", inside the "this" div.
    The indentation is optional, but helpful.
  }
  Thus ends the "here" div.

{{.instead}
  of indentation, one could also allow several "{" to start a nested div.  

  But how to start divs without classes or ids, you ask.

  {} How about doing it this way?}

}}
That was the end of "instead" with an optional, additional "}".

{#last .idea}
  ending two divs in one line could be achieved
  with a simple space in between, like this:
} }

And I'm outside!

What do you think?

MarLinn on 26 Feb 2015

@jgm, would it be possible that syntax for generic division and spans make its way into release 1.14?

I would say that having different opening and closing characters (such as previously proposed [[[ and ]]]) helps to nesting and readabiliy, so that most errors can be easily recognized. (I’d say it also makes parsing easier.)

Indenting is more problematic because not everyone feels comfortable with a coding editor (or you may not have one in your mobile device [tablet or smartphone]). And it doesn’t necessarily increase readability.

But after more than five years that the original message had been posted in the mailing list, I guess it is time to implement a syntax for generic division and span elements.

ousia on 24 May 2015

1.14 is going to be released very soon, so I'm not adding
new features at this point.

+++ Pablo Rodríguez [May 24 15 08:31 ]:

[1]@jgm, would it be possible that syntax for generic division and
spans make its way into release 1.14?

I would say that having different opening and closing characters (such
as previously proposed [[[ and ]]]) helps to nesting and readabiliy, so
that most errors can be easily recognized. (I’d say it also makes
parsing easier.)

Indenting is more problematic because not everyone feels comfortable
with a coding editor (or you may not have one in your mobile device
[tablet or smartphone]). And it doesn’t necessarily increase
readability.

But after more than five years that the original message had been
posted in the mailing list, I guess it is time to implement a syntax
for generic division and span elements.

—
Reply to this email directly or [2]view it on GitHub.

References

https://github.com/jgm

https://github.com/jgm/pandoc/issues/168#issuecomment-105027444

jgm on 27 May 2015

I think the colons look good.

Would also be nice to see some [span syntax]{.cool-feature} make it in as well.

uvtc on 27 May 2015

jgm wrote:

I really like === myself. There's more potential for a clash with setext headers, though, which may make ::: safer.

Sorry for the bikeshedding. I agree with you and bpj that === looks the best. Is the concern that it could lead to a clash in the Pandoc implementation, CommonMark implementation, CommonMark spec, or just that it will visually clash?

uvtc on 27 Jul 2015

+++ John Gabriele [Jul 27 15 09:51 ]:

jgm wrote:
I really like === myself. There's more potential for a clash with
setext headers, though, which may make ::: safer.
Sorry for the bikeshedding. I agree with you and bpj that === looks the
best. Is the concern that it could lead to a clash in the Pandoc
implementation, CommonMark implementation, CommonMark spec, or just
that it will visually clash?

I think my main concern was the potential for ambiguities:

Is this a setext header
===========================
or just a paragraph
followed by a fenced block?
===========================

This could be avoided by requiring a blank line before the
fenced block, but in CommonMark we normally don't require
these lines (they're not needed before fenced code blocks,
for example).

Of course, we can just settle the ambiguity with an explicit
stipulation, as we already need to do for horizontal rules
and setext headers. So this may not be a big concern.

jgm on 27 Jul 2015

Is this a setext header
===========================
or just a paragraph
followed by a fenced block?
=========================== 
This could be avoided by requiring a blank line before the fenced block, but in CommonMark we normally don't require these lines (they're not needed before fenced code blocks, for example).

Either with === or ::: if no blank line is required before the fenced division, I think that nesting divisions would be harder than it should.

BTW, what is the gain in not requiring blank lines before code blocks? Sorry, but I don’t see it. At least from the writer’s perspective, it doesn’t make the text more readable.

ousia on 27 Jul 2015

Of course, we can just settle the ambiguity with an explicit stipulation, as we already need to do for horizontal rules and setext headers. So this may not be a big concern.

Oh my. My purpose in using markdown is to make my plain text look clear. Which means, I always put blank lines around blocks, and for that matter underneath headings, whether Pandoc requires it or not.

I think this is an easy one: just require the blank lines and be done with it.

uvtc on 27 Jul 2015

+++ John Gabriele [Jul 27 15 10:58 ]:

Of course, we can just settle the ambiguity with an explicit
stipulation, as we already need to do for horizontal rules and
setext headers. So this may not be a big concern.
Oh my. My purpose in using markdown is to make my plain text look
clear. Which means, I always put blank lines around blocks, and for
that matter underneath headings, whether Pandoc requires it or not.

Good for you. But not everyone does. It's established
practice in Markdown not to require blank lines before
fenced code blocks, or after headings. Requiring them here
makes things less consistent and will surprise users.

Generally, Markdown's approach is to be incredibly forgiving.
(Contrast reStructuredText.)

jgm on 27 Jul 2015

+++ Pablo Rodríguez [Jul 27 15 10:31 ]:

Is this a setext header

or just a paragraph

followed by a fenced block?
This could be avoided by requiring a blank line before the fenced
block, but in CommonMark we normally don't require these lines
(they're not needed before fenced code blocks, for example).
Either with === or ::: if no blank line is required before the fenced
division, I think that nesting divisions would be harder than it
should.

Nesting would be handled as it is with fenced code blocks.
The block is terminated by the first line of =s of length
equal to or greater than the initial one. That is simple
and is not affected by this question.

jgm on 27 Jul 2015

It's established practice in Markdown not to require blank lines before fenced code blocks, or after headings.

Ah, didn't know that. I've never seen a code block written without blank lines around it, and only rarely a heading without a blank line under it (maybe in a unix util changelog somewhere?). In either case, I'd assume the lack of blank line(s) was just a typo.

Generally, Markdown's approach is to be incredibly forgiving. (Contrast reStructuredText.)

Interesting. My impression has been that first and foremost, Markdown's approach is to look good/natural/readable, while secondarily being flexible (ex., regular vs. "lazy" lists, multiple table formats, etc.), and lastly being pretty forgiving. But that could be simply because I don't ask it to be forgiving. :)

Would there be any value in requiring at least an empty trailing {} for code blocks without a leading empty line? As in:

This is the end of a paragraph. Div block
with no attribs coming up.
=== {}
Div block without a newline in front of
it requires at least the `{}`.
===

?

Otherwise, could Pandoc use the heuristic that if the length of the line of equal signs is the same as the length of the line above, then it's a setext heading, otherwise it's the start of a div block?

uvtc on 27 Jul 2015

Alas pandoc already accepts non-equal length text and underline in headers.

I have nothing against the colons alternative -- in fact I like it.

bpj on 28 Jul 2015

It would be useful if this mechanism could also be used to generate arbitrary environments in latex, e.g.

:::{#someid .someclass}
This doesn't
look half bad.
:::

would become

<div id="someid" class="someclass"> 
  <p>This doesn't look half bad</p>
</div>

or

\begin{someclass}
  \label{someid}
  This doesn't look half bad
\end{someclass}

(I don't think label plays well in arbitrary latex environments, but I don't think it does any harm, and you're unlikely to use it unless you specifically need it.)

This would be extremely useful when you're generating both latex and html from the same source doc (as is common if you're writing a book that has both a website and a final printed pdf)

hadley on 31 Aug 2015

is this implemented? FP is almost 5 years old :older_man:

felixsanz on 16 Feb 2016

+++ Felix Sanz [Feb 16 16 02:02 ]:

is this implemented? FP is almost 5 years old :older_man:

My, the time flies. Yes, we should probably settle on
something and do this.

jgm on 16 Feb 2016

If my tiny opinion counts, this is the way to go:

::: {#id .class data-attr=""}
text inside a div
:::

Just like fenced codes but with :. Other markdown parsers do it that way too

felixsanz on 17 Feb 2016

+++ Felix Sanz [Feb 16 16 19:08 ]:

If my tiny opinion counts, this is the way to go:
::: {#id .class data-attr=""}
text inside a div
:::

Just like fenced codes but with :. Other markdown parsers do it that
way too

Which ones support that syntax?

jgm on 17 Feb 2016

official markdown-it container plugin: https://github.com/markdown-it/markdown-it-container

(It doesn't support {attributes}, but that's why exist markdown-it-attr and markdown-it-decorator)

felixsanz on 17 Feb 2016

If my tiny opinion counts, this is the way to go:
::: {#id .class data-attr=""}
text inside a div
:::
Just like fenced codes but with :. Other markdown parsers do it that
way too
Which ones support that syntax?

I’d rather prefer [[[ and ]]]. But if not, ::: syntax is better than no syntax at all.

Please, don”t forget the syntax for spans. In that case, links already use [ and ].

I think it is essential to implement a special syntax for both divs and spans in the next stable version (1.17, i guess).

ousia on 17 Feb 2016

:::
div
:::

:span:

is this even possible?

felixsanz on 17 Feb 2016

If I remember previous discussions correctly, they tended to be in favour of surround-marking (like fenced-code blocks but different symbol). No consensus was found over which symbol to use, however. But I think markdown-it using ::: is setting a strong precedent, and I think vitaly et al chose this following the discussion on talk.commonmark.org.

AFAIK the span syntax is pretty much agreed upon to be: a [span]{.myClass} in the text

mb21 on 17 Feb 2016

With the new link attributes we are only a pair of parentheses away from that span syntax.
For what it's worth I've written a filter which converts a link with an empty URL into a span so that I can write:

[this *is* the span content](){#id .class}

The only disadvantage is that such a 'span' can't contain links...

I agree about colon-fences for divs, especially since others have already adopted it, so forget everything I've said earlier to the contrary

bpj on 17 Feb 2016

Just one thing: since the start and end of a div can be much farther separated than what is usually the case with code blocks, and contain other divs it would be good if one be allowed to have more text as a comment on the same line as the closing fence, so that one can put the id of the div or something similar there, as a help to the human writer. I always put an HTML comment to that effect at the end of a long div. There could be an option to have the Markdown and LaTeX writers automatically insert a comment with the div id, if any, at the end. Note that it _is_ possible to do that by hand at present but the comment ends up on a line of its own.

<div class=foo>
Blah blah
</div><!-- #foo -->

<div class="foo">
<p>Blah blah</p>
</div>
<!-- #foo -->

So I'm thinking along the lines of

:::{#foo}
Blah blah

Blah blah...
:::<!-- #foo (This comment is ignored by pandoc!) -->

bpj on 17 Feb 2016

I think the only natural syntax for spans is [the square
bracket syntax]. We already parse these as inline
containers, so it makes sense. We'd have all these
combinations:

[regular span]{#id}
[link](url)
[link with attributes](url){#id}
![image](url)
![image with attributes](url){#id}

Probably

[regular brackets]

should not be a span. This occurs naturally in text.

jgm on 17 Feb 2016

I think long ago I suggested a side-marking syntax for divs,
similar to what is used now for block quotes. This has the
advantage that scope is visually clear. It is also very
consistent with original Markdown, since we already have
> for block quotes.

Nobody liked this at the time, but I still think it makes
sense (which might be why I've hesitated so much to adopt
one of the other proposals).

Example:

: {#id .warning}
: Here is a special warning section.
:
: It can go on as long as you like.
:
:: {#subid color=blue}
:: and it can contain sub-divs like this.
:: It's clear when this ends.
:
: Back to the outer div.

"Laziness" would apply just as with block quotes. So, you
could just do:

:{#id .warning}
This is a warning!
Lazy style.

+++ Benct Philip Jonsson [Feb 17 16 03:54 ]:

Just one thing: since the start and end of a div can be much farther
separated than what is usually the case with code blocks, and contain
other divs it would be good if one be allowed to have more text as a
comment on the same line as the closing fence, so that one can put the
id of the div or something similar there, as a help to the human
writer. I always put an HTML comment to that effect at the end of a
long div. There could be an option to have the Markdown and LaTeX
writers automatically insert a comment with the div id, if any, at the
end. Note that it is possible to do that by hand at present but the
comment ends up on a line of its own.

Blah blah

Blah blah

So I'm thinking along the lines of
:::{#foo}
Blah blah

Blah blah...
:::

—
Reply to this email directly or [1]view it on GitHub.

References

https://github.com/jgm/pandoc/issues/168#issuecomment-185169965

jgm on 17 Feb 2016

I like that symmetry of using the colons for both the delimited div syntax and also for the side-marking div syntax. (And colons are one of the handful of characters that look pretty good as a side-marking character. Actually, they look good as a side-mark _as well as_ bunched-up for start and end markers.)

I think long ago I suggested a side-marking syntax for divs, similar to what is used now for block quotes. This has the advantage that scope is visually clear. It is also very consistent with original Markdown, since we already have > for block quotes.

And, of course, also symmetrical with | for lineblocks.

* * *

Incidentally, I notice that if you currently write:

:{.some-class}
: this
: that
: other

it gives you a definition list (one term with multiple definitions).

uvtc on 17 Feb 2016

Ultimately, I think both syntax proposals are pretty good; one is analogous to blockquotes, the other to fenced code blocks... so we could even have both, but preferably not I guess.

btw, why were fenced code blocks introduced in markdown processors (in addition to indented code blocks)? I suspect some of the reasons would apply to this discussion as well...

mb21 on 17 Feb 2016

@jgm I think a side-marked div syntax would be very frustrating to use, because divs can be _big_, and you would have to remember to put the marker on every paragraph-ish throughout the div.

bpj on 17 Feb 2016

My two cents...

[regular span]{#id}

Looks very good for spans.

However, I do like neither === nor ::: for divs. ``` is ok for code blocks, but code blocks cannot be nested, while divs can.

I believe it is important to have different div begin and div end marks. It will help parser to detect missed mark.

Also, most programmers text editors can highlight matching brace/bracket/parenthesis and jump from open brace/bracket/parenthesis to closing one (and back). Thus, if div begin and div end marks are made of parenthesis-like characters (e. g. [[[ and ]]], or ((( and ))), or {{{ and }}}), we will have cool navigation across divs for free.

van-de-bugger on 17 Feb 2016

I think long ago I suggested a side-marking syntax for divs, similar to what is used now for block quotes. This has the advantage that scope is visually clear. It is also very consistent with original Markdown, since we already have > for block quotes.

And, of course, also symmetrical with | for lineblocks.

If you ask me, I must confess I hate both side–markings. I have no other choice than to use it for blockquotes. And lineblocks are even harder than the previous syntax (with the ending \). I avoid lineblocks as much as I can.

I agree, they may be visually clearer to read, but much harder to type. Please, don’t forget that _Markdown_ users shouldn’t be compelled to use a text editor for programmers (what @jgm called “a decent editor” [some of us are “indecent users”]).

Probably
[regular brackets]
should not be a span. This occurs naturally in text.

And even in that case, I don’t think that a span without attributes makes much sense.

Also, most programmers text editors can highlight matching brace/bracket/parenthesis and jump from open brace/bracket/parenthesis to closing one (and back). Thus, if div begin and div end marks are made of parenthesis-like characters (e. g. [[[ and ]]], or ((( and ))), or {{{ and }}}), we will have cool navigation across divs for free.

{{{ and }}}) should be avoided, since attributes use {#id .class}. Too confusing (or misleading).

I think that for consistency with spans, [[[ and ]]] should be selected for divs. But @jgm is the one that has to decide this.

BTW, @jgm, I wonder why is [span] is _the only natural way_ and it isn’t in the case of [[[division]]]. Visual and basic consistency for people (not in a logico–philosophical sense) is important for ordinary humans (they aren’t as familiar with computers as coders).

ousia on 17 Feb 2016

BTW, @jgm, I wonder why is [span] is the only natural way and it isn’t in the case of [[[division]]]`. Visual and basic consistency for people (not in a logico–philosophical sense) is important for ordinary humans (they aren’t as familiar with computers as coders).

BTW, can spans be nested?

Recently I added RDFa attributes to few my documents. I have managed it by m4, which inserts span elements, then md document with <span>s is passed to pandoc . I found that I need _nested_ spans, e. g.:

RDF_DESCRIPTION({ RDF_NAME({ XXX }) is *RDF_HEADLINE({ RDF_KEYWORD({ 
... }) ... RDF_KEYWORD({ [...] }). })* ... XXX is RDF_KEYWORD({ 
RDF_OFFER({ RDF_PRICE({ 0.0 },{ free software }) }) }). })

van-de-bugger on 17 Feb 2016

+++ van-de-bugger [Feb 17 16 13:26 ]:

My two cents...
[regular span]{#id}

Looks very good for spans.

However, I do like neither === nor ::: for divs. ``` is ok for code
blocks, but code blocks cannot be nested, while divs can.

It's important to allow nesting. The way this would be done
with ::: (say) is to say that the div ends when you hit a
string of 3 or more colons that is longer than the string
that opened the div. (We already have a similar rule for
fenced code, to allow inclusion of lines with backticks in
code, so this is consistent.)

::::::
outer div

:::
inner div
:::

outer again
:::::::

I believe it is important to have different div begin and div end
marks. It will help parser to detect missed delimiter.

Also, most programmers text editors can highlight matching
brace/bracket/parenthesis and jump from open brace/bracket/parenthesis
to closing one (and back). Thus, if div begin and div end marks are
made of parenthesis-like characters (e. g. [[[ and ]]], or ((( and ))),
or {{{ and }}}), we will have cool navigation across divs for free.

Yes, these are good points. But the [[[ format is really
ugly and doesn't look natural to me in the source.
I suppose one could do something like

[=========
outer div

[==
inner
==]

==========]

jgm on 17 Feb 2016

+++ van-de-bugger [Feb 17 16 14:40 ]:

BTW, [1]@jgm, I wonder why is [span] is the only natural way and it
isn’t in the case of [[[division]]]`. Visual and basic consistency
for people (not in a logico–philosophical sense) is important for
ordinary humans (they aren’t as familiar with computers as coders).

BTW, can spans be nested?

Yes.

jgm on 17 Feb 2016

+++ Mauro Bieg [Feb 17 16 12:59 ]:

btw, why were fenced code blocks introduced in markdown processors (in
addition to indented code blocks)? I suspect some of the reasons would
apply to this discussion as well...

I think there were two main reasons:

They allowed you to specify a language/syntax.
They allowed you to cut and paste code into the source
without adding tabs.

jgm on 17 Feb 2016

But the [[[ format is really ugly and doesn't look natural to me in the source.

It's up to you. My point is that div begin and div end markers should contain at least one pair of brackets/braces/parentheses in order to utilize existing feature of programmer editors.

van-de-bugger on 17 Feb 2016

@ousia writes:

I agree, they may be visually clearer to read, but much harder to type.
{snip}
I wonder why is [span] is the only natural way and it isn’t in the case of [[[division]]].

An original main goal of Markdown was not only to be as readable as possible, but also to be publishable as-is --- to not look as if it was marked up at all. Here's a choice quote from Gruber's daringfireball markdown page:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

Notice: no mention of being _writable_. [[[some div content]]] is easily parsable, writeable, and easy enough to read, but it looks an awful lot like markup.

In contrast, something like:

Cooking is fun and easy.

: {.warning}
: Do not overheat. Stir occasionally.
: If it sticks to the bottom, you're
: washing the pan.

looks like formatting anyone might write in an email and people would just know what it meant, and maybe start using that formatting too. This is necessarily subjective, and may not necessarily be easy to type. Some of markdown may be steeped in tradition. But I like to think that's the essence of what Markdown is going for.

(IMO, delimited blocks, "lazy" blockquotes and list items, and atx-style headers make Markdown easier to write (or copy/paste, or easier for a computer to generate), at the expense of looking not quite as pleasing.)

The colon is a handsome character. And it's not yet overused in Markdown. ;) Using it as a side-marker for divs, not only is it reasonably obvious what it means, but also it makes a nice "dotted line" down the left side of the page.

That is syntax I could see people just picking up and using because it means what it looks like, and is not _too_ much of a hassle to type. If you find it a bother, then you can always fall back on the :::{.warning} delimited syntax, or even the "lazy" style jgm pointed out.

uvtc on 18 Feb 2016

@jgm writes:

It's important to allow nesting. The way this would be done with ::: (say) is to say that the div ends when you hit a string of 3 or more colons that is longer than the string that opened the div. (We already have a similar rule for fenced code, to allow inclusion of lines with backticks in code, so this is consistent.)

That doesn't seem consistent to me. With fenced code blocks, you make the outer fence larger so it forces the inner to be part of the code block. The outer fence overpowers the inner fence; there's no nesting, as the inner fence ceases to be a "fence" at that point.

With divs, they're, of course, truly nesting. This is very different, and I think should look different.

It makes sense to me (if you're using the delimited syntax rather than the side-marked syntax) to always use $n colons:

:::{.outer}
Some content

:::{.inner}
Some inner content.
::: <!-- closes inner -->

Back to outer.
::: <!-- closes outer -->

and have Pandoc match each ::: to the nearest unclosed opening :::{...}.

If you really do want to have inners use a differing number of colons, then to be more consistent with the side-marking syntax, the inners should use _more_ colons:

::: {.warning}
Try not to make any loud noises while the bread is rising.

:::::: {.severe-warning}
I mean it! The loaf is delicate; any vibration will cause
dramatic and catastrophic deflation!
::::::

Also cover with a dishcloth to make it feel cozy.
:::

Lastly, like @bpj suggested, it would be great to be able to optionally comment the closing :::. It's fine if I have to do ::: , as long as Pandoc doesn't complain or insist the comment go on a separate line.

uvtc on 18 Feb 2016

[fenced code blocks] allowed you to cut and paste code into the source
without adding tabs.

So people were willing to introduce a new syntax basically because they didn't have an editor handy with an indent feature? And that's people working with code, since we're talking about code blocks... divs are far more likely to be used in editors without such features.

I don't know... maybe we'll have to introduce both side- _and_ surround-marking (as some seem to already assume in this discussion). We already have two code block syntaxes and it's not too bad. You can use whichever is more appropriate to the situation.

mb21 on 18 Feb 2016

@uvtc wrote:

@jgm writes:

It's important to allow nesting. The way this would be done with ::: (say) is to say that the div ends when you hit a string of 3 or more colons that is longer than the string that opened the div. (We already have a similar rule for fenced code, to allow inclusion of lines with backticks in code, so this is consistent.)

That doesn't seem consistent to me. With fenced code blocks, you make the outer fence larger so it forces the inner to be part of the code block. The outer fence overpowers the inner fence; there's no nesting, as the inner fence ceases to be a "fence" at that point.

With divs, they're, of course, truly nesting.

You may not even know how many nesting levels there are going to be when you type the fence at the top, so you would have to go back and add colons.

This is very different, and I think should look different.

I agree emphatically.

It makes sense to me (if you're using the delimited syntax rather than the side-marked syntax) to always use $n colons:
and have Pandoc match each ::: to the nearest unclosed opening :::{...}.

Like HTML renderers do.

If you really do want to have inners use a differing number of colons, then to be more consistent with the side-marking syntax, the inners should use more colons:

Agreed, but given the potential distance between the opening and closing of a div it may be hard to keep track of which nesting level you are on. One would practically be forced to attach a comments (perhaps even with matching brackets in them!) to your div delimiters to keep track.

bpj on 18 Feb 2016

@uvtc wrote:

@ousia writes:

I agree, they may be visually clearer to read, but much harder to type.
{snip}
I wonder why is [span] is the only natural way and it isn’t in the case of [[[division]]].

An original main goal of Markdown was not only to be as readable as possible, but also to be publishable as-is --- to not look as if it was marked up at all.

While I sin against that a lot in documents which are to be shown to others only in rendered form I think this is a really important point.
I use Markdown syntax when writing email more or less without thinking of it. I'm annoyed every time I reformat such a mail with pandoc and end up with backslash escaped literal punctuation.
While I can use my plain-to-email filter I'd rather not.

[[[some div content]]] is easily parsable, writeable, and easy enough to read, but it looks an awful lot like markup.

I agree. I'd say it looks awful, full stop!

In contrast, something like:
  Cooking is fun and easy.

  : {.warning}
  : Do not overheat. Stir occasionally.
  : If it sticks to the bottom, you're
  : washing the pan.
looks like formatting anyone might write in an email and people would just know what it meant, and maybe start using that formatting too. This is necessarily subjective, and may not necessarily be easy to type. Some of markdown may be steeped in tradition. But I like to think that's the essence of what Markdown is going for.

The problem with that syntax is that while it looks good for short blocks like in your example it gets too troublesome to work with for longer ones. Laziness (which I dislike) is not much help there, and would make it hard to keep track of what is a div and what is a definition.

(IMO, delimited blocks, "lazy" blockquotes and list items, and atx-style headers make Markdown easier to write (or copy/paste, or easier for a computer to generate), at the expense of looking not quite as pleasing.)

That's why we can have pandoc output Markdown! I disagree about atx-style headings though. The mixture of two kinds of header when you have more than two levels of headings is just awful.

bpj on 18 Feb 2016

@ousia:

I agree, they may be visually clearer to read, but much harder to type. Please, don’t forget that Markdown users shouldn’t be compelled to use a text editor for programmers (what @jgm called “a decent editor” [some of us are “indecent users”]).

@mb21:

[fenced code blocks] allowed you to cut and paste code into the source without adding tabs.

So people were willing to introduce a new syntax basically because they didn't have an editor handy with an indent feature? And that's people working with code, since we're talking about code blocks... divs are far more likely to be used in editors without such features.

This is getting OT, but...

These two quotes answer each other in a way: non-programmers overlook or are ignorant of the fact that advanced text editors have many virtues also when writing prose. After all they are called text editors, not _code editors_. Apparently there are also coders who underestimate their editors' potential (only for prose, hopefully!). I write about equal amounts of prose (Markdown of course) and code, but I do both in Vim, or those editors I have on my mobile devices, and I mostly use the same features. If anything I use some features more when writing prose: search/substitution w/o regular expressions, parenthesis matching, block selection (vipI> <esc> anyone?), joining blocks of lines, jumping between marks (set a mark, jump to where the link definitions are, write a link definition, jump back). As for fenced vs. indented code blocks vim-pandoc can apply the right per-language syntax highlighting to the former, which is very neat since at least for me the main virtue of syntax highlighting is for spotting errors.

bpj on 18 Feb 2016

@uvtc wrote:

An original main goal of Markdown was not only to be as readable as possible, but also to be publishable as-is — to not look as if it was marked up at all.

Well, that is simply impossible. If you use tags in a pure text file, they will be visible.

Notice: no mention of being writable. [[[some div content]]] is easily parsable, writeable, and easy enough to read, but it looks an awful lot like markup.

This is partially my fault, because I wrote a block element as an inline element.

[[[ {.class #id :lang}
some div content
]]]

You may object that I haven’t read enough poetry, but I don’t see this as especially ugly when compared with:

::: {.class #id :lang}
some div content
:::

And the beauty of

Cooking is fun and easy.

: {.warning}
: Do not overheat. Stir occasionally.
: If it sticks to the bottom, you're
: washing the pan.

is non-existent for me. Sorry, but this is markup. That is harder to write (try to do it in a simple text editor with your tablet or mobile phone) and harder to read (it is easier to be overlooked).

The colon may be a handsome character (I think i have some experience in typography, but I cannot see its handsomeness). What really bothers me is that the use of the colon may block its use for language (it’s a an older issue: #895, but it comes from #162 [and it is originally derived from https://code.google.com/archive/p/pandoc/issues/201, which is 6yo]).

Side-marking is harder to write and easier to overlook. I’d rather prefer (as @jgm seems to propose):

[=========
outer div

[==
inner
==]

==========]

@mb21 wrote:

I don't know... maybe we'll have to introduce both side- and surround-marking (as some seem to already assume in this discussion). We already have two code block syntaxes and it's not too bad. You can use whichever is more appropriate to the situation.

I asked for surround-marking for both lines and quotes. I only got the denial.

But you are right. I don’t know why there is double syntax for code blocks (or emphasis and strong emphasis, although this unrelated) and not for other divisions such as block quotes.

@bjp wrote:

[[[some div content]]] is easily parsable, writeable, and easy enough to read, but it looks an awful lot like markup.

I agree. I'd say it looks awful, full stop!

Well, you have the other syntax suggested by @jgm.

The main issue isn’t the character, but side- vs. surround-marking.

The problem with that syntax is that while it looks good for short blocks like in your example it gets too troublesome to work with for longer ones. Laziness (which I dislike) is not much help there, and would make it hard to keep track of what is a div and what is a definition.

This happens with blockquotes that contain nested lists. To add that to my Markdown document, I had to convert HTML code to Markdown with http://pandoc.org/try and paste it into my document.

I agree, they may be visually clearer to read, but much harder to type. Please, don’t forget that Markdown users shouldn’t be compelled to use a text editor for programmers (what @jgm called “a decent editor” [some of us are “indecent users”]).
[...]
This is getting OT, but...

These two quotes answer each other in a way: non-programmers overlook or are ignorant of the fact that advanced text editors have many virtues also when writing prose. After all they are called text editors, not _code editors_.

Who said that code isn’t text? Sorry, but I think code is also text.

Even if I’m totally wrong in my previous statement. I’m not a developer myself, only an average user. I discuss markup, because I think is important for other users (not especially for myself).

My first question is: do you expect from users that they write their Markdown documents using emacs, vim or similar advanced editors?

Well, I’ll never do this myself. But it isn’t about me. I’m planning two books on pandoc. I‘m afraid both are in Spanish (English versions may follow). One of them is http://www.aprender-pandoc.tk (sorry, all info is in Spanish and text is missing).

I plan to explain the extreme usefulness of pandoc. But unnecessarily complicated syntax (from the below-average user perspective [not from standpoint of a coder]) is a real pain to learn something that is already extremely complex for her (I use the feminine as generic).

Language tagging is a pain (we don’t have special attributes), side-marking is harder and the lack of attributes in the vast majority of elements is also a problem (because it is difficult to understand why the element-attribute structure only works with titles, code and urls [especially for the newbie]).

I may have a main problem: it is about the default. I think that the default is only the predetermined option when you have other ones. Well, default in pandoc seems to be the only way of doing some things.

Don’t get me wrong. I’m happy with pandoc. And I’m extremely thankful to @jgm for this awesome piece of software. (Consider that otherwise, I wouldn’t write a line about it.) But I think it would be even more awesome for even more users when it didn’t require coding abilities for the average user.

ousia on 19 Feb 2016

+++ Pablo Rodríguez [Feb 18 16 15:09 ]:

And the beauty of
Cooking is fun and easy.

: {.warning}
: Do not overheat. Stir occasionally.
: If it sticks to the bottom, you're
: washing the pan.
is non-existent for me. Sorry, but this is markup. That is harder to
write (try to do it in a simple text editor with your tablet or mobile
phone) and harder to read (it is easier to be overlooked).

I certainly agree it's harder to write. But I don't see the
point about "harder to read." The line of colons serves
to set this paragraph off as if in a box -- which is not so
different from how it might appear in a typeset book.
It's impossible to look at part of this section and forget
that it's in a special section (as you might with
surround-marking, especially if the section is long).

When there is a tradeoff between hard to write and hard to
read, Markdown favors "hard to write." An example is
the syntax for nested lists, which require indentation.
Compare that to asciidoc, wiki markup, and other systems
that do this:

outer
* inner
** deeply nested
** inner
outer

This is much easier to write than an indented list
structure, especially on a tablet or phone. But it makes
the source less readable.

jgm on 19 Feb 2016

I enthusiastically agree with @jgm. It's worth noting that arbitrary divs are going to be a fairly esoteric feature that will be used by relatively few markdown authors.

hadley on 19 Feb 2016

@jgm commented about side-marking:

I certainly agree it's harder to write. But I don't see the point about "harder to read." The line of colons serves to set this paragraph off as if in a box -- which is not so different from how it might appear in a typeset book. It's impossible to look at part of this section and forget that it's in a special section (as you might with surround-marking, especially if the section is long).

Sorry, it was my faulty wording. With “harder to read” I meant “easier to be overlooked”. That’s one of my main objections to side-marking. And colons contribute much better than square brackets to the easiness to be overlooked.

@hadley added:

I enthusiastically agree with @jgm. It's worth noting that arbitrary divs are going to be a fairly esoteric feature that will be used by relatively few markdown authors.

I’m afraid I don’t agree with him in this point. And I disagree with your reasoning. I’ll tell you why.

Divs are especially required in pandoc because its document model doesn’t grant attributes for all elements. This is a huge problem, because _Markdown_ seems to be easy HTML markup for the rest of us. Well, the problem is that HTML grants (at least) id, class and language attributes to all elements. pandoc grants them to headings, code and some urls. (Sorry for repeating myself, but this is a huge design problem.)

With a basic issue (ousia/from-pandoc-to-context#19): centering a single paragraph is a real pain.

And with a more elaborate context: you cannot get this PDF file and this ePub file from the very same source, unless you have divs and spans (no conversion to a ConTeXt source file was used, just in case you wonder). I cannot code, but I think you need magic for that without divs and spans.

ousia on 19 Feb 2016

@jgm, are there any news on this issue?

Sorry for asking again, but you have to make the final choice.

ousia on 28 Feb 2016

+++ Pablo Rodrguez [Feb 28 16 01:19 ]:

[1]@jgm, are there any news on this issue?

When there's news, you'll read it here. I just haven't had
time lately to think about this.

jgm on 28 Feb 2016

@jgm, are there any news on this issue?

When there's news, you'll read it here. I just haven't had time lately to think about this.

If you allow me the sentence (it isn’t an advice, not even a suggestion), sometimes is time to decide (thinking should be over). No matter which is the final result, some users will disagree.

@hadley, do you really think that divisions are a pretty esoteric feature with the case of paragraph centering?

ousia on 29 Feb 2016

@uvtc

An original main goal of Markdown was not only to be as readable as possible, but also to be publishable as-is --- to not look as if it was marked up at all.

I have to second this. I'm surprised it needs mentioning at all, since as @uvtc linked, it is stated in the original design of Markdown. Every discussion of Markdown features should be framed in this context. If you need "a better HTML", there are a million alternatives (Jade and Haml come to mind). Let Markdown remain what it is.

thejohnfreeman on 29 Feb 2016

In case there's any confusion, and to be clear: the proposed div syntax is to have _both_ the side-marking syntax as well as the fenced/delimited/surround style.

The side-marked syntax:

looks better to the reader (IMO),
looks less like markup,
is a little more difficult to type, and
is consistent with > for blockquotes, | for line blocks, and 4-spaces for code blocks.

The fenced syntax:

is easier to type,
is arguably more convenient for larger divs, and
is consistent with ~~~ for fenced code blocks.

So, of course, you could use whichever you prefer. :)

Incidentally, I think @jgm 's syntax for nesting the side-marked version of divs makes a lot of sense:

: {.note}
: Please do not tap the glass or
: put any food into the tank.
:
: : {.warning}
: : Attempting to pet the sharks
: : is very much not recommended.
:
: Do not taunt or mock the octopi.

uvtc on 29 Feb 2016

+++ John Gabriele [Feb 29 16 08:24 ]:

In case there's any confusion, and to be clear: the proposed div syntax
is to have both the side-marking syntax as well as the
fenced/delimited/surround style.

I think just having side-marked syntax is still on the table.
I don't find the arguments for the fenced syntax all that
compelling.

jgm on 29 Feb 2016

Oh, I see. Thanks. I'd figured that the same rationale that applies to code blocks is also relevant for divs: making copying/pasting content more convenient.

* * *

As a data point, my main use _of the delimited div syntax_ would be when I have substantial content to go into a div. I'd then write

::: {.some-class}

::: <!-- / .some-class -->

then copy/paste the content in between them.

_(Sorry for the edits; accidentally submitted comment before it was done baking.)_

uvtc on 29 Feb 2016

@thejohnfreeman, I don’t need simpler HTML, i need a real light-weight language.

Many thanks for mentioning the ability to be publish the code as an essential design feature in Markdown.

What I don’t understand is why side-marking is essentially publishable and fenced/delimited/surround-style is not.

Code remains code. How about multiparagraph footnotes? Why are they essentially more publishable fenced divisions? And why are they different from fenced code blocks?

What I think it is really a pity is that the alleged publish-ability is considered before ease to type code and to read (to recognize, not to overlook) it.

ousia on 29 Feb 2016

What I don’t understand is why side-marking is essentially publishable and fenced/delimited/surround-style is not.

I'd say that this is a combination of historical convention, Markdown style, current conventions of other implementations, jgm's personal taste, as well as other's input here and on the mailing list, plus maybe some of the input and consensus on CommonMark. It's necessarily a little subjective.

uvtc on 29 Feb 2016

I agree that it makes sense to have both forms. I personally like side-marked : and delimited :::, with nested sections having longer, not shorter, markings. Easy copy-paste would be my main driver for delimited syntax, as it is for code blocks.

thejohnfreeman on 1 Mar 2016

I also think it makes sense to have both forms. _Removing_ side markers from a range of lines longer than a screenful isn't fun. In Vim you can set up 'formatoptions' and 'comments' so that side markers repeat automatically for each new line but removing markers isn't as easy. You need to jump around and set marks, then use :s or some plugin to remove (one level of) side markers. Besides I wouldn't want to set up : as a comment character because of definition lists which I use comparatively often.

I suspect definition list marking and div marking would clash with each other rather easily, so if we introduce side marking for divs we should use some other character than the colon, like the semicolon (which wouldn't look as good!)

bpj on 1 Mar 2016

I'd forgotten that, if you have large blocks of text to go into a div, without having to use side-marking, that you can just do so with raw html (<div class="some-class">...</div>). I suppose that's why there's a question of the utility of adding a fenced div syntax.

I suspect definition list marking and div marking would clash with each other rather easily, so if we introduce side marking for divs we should use some other character than the colon, like the semicolon (which wouldn't look as good!)

The pipe | would be wonderful as a generic (therefore, div) side-marking character. Alas, it's already used for line-blocks (quite a specialized use case)... (I wonder which is (would be) used more: line blocks or div blocks?) Could the pipe be used for divs but also be able to give you a lineblock?

| Generic div
| block here. 

|{.some-class #some-id foo="bar"}
| Another block,
| but with class, id,
| and some attrib.

|{.some-class foo="bar" .lineblock}
| another block, but
| with a class, some attrib,
| and it's also a line block

uvtc on 1 Mar 2016

+++ Benct Philip Jonsson [Mar 01 16 08:34 ]:

I suspect definition list marking and div marking would clash with each
other rather easily, so if we introduce side marking for divs we should
use some other character than the colon, like the semicolon (which
wouldn't look as good!)

That's true, the conflict with definition list syntax makes
the colon less than ideal. One natural possibility would be
the exclamation mark.

! {.warning}
! Don't do this unless you
! have backed up your files.

The exclamation marks make a kind of line, and they also
connote "pay special attention to this."

jgm on 1 Mar 2016

@uvtc wrote:

I'd forgotten that, if you have large blocks of text to go into a div, without having to use side-marking, that you can just do so with raw html (
...
). I suppose that's why there's a question of the utility of adding a fenced div syntax.

Well yes, but HTML div/span syntax looks _a lot_ like markup, hence goes very much against the Markdown philosophy quote you posted earlier in this thread. I started using Markdown (before pandoc) because I find text marked up with HTML well nigh impossible to read fluently and hence dead ugly. I'll grant that HTML div syntax inside Markdown is a good deal less interrupting than HTML span syntax, because it reads as a kind of heading in many cases, but ugly it is.

bpj on 1 Mar 2016

I wrote:

I suspect definition list marking and div marking would clash

@jgm wrote:

That's true, the conflict with definition list syntax makes
the colon less than ideal. One natural possibility would be
the exclamation mark.

I was going to suggest the exclamation mark, but I had a feeling there may be some context where an exclamation mark would legitimately end up at the beginning of a line. I don't know why.

The exclamation marks make a kind of line, and they also
connote "pay special attention to this."

I didn't think of that. That's excellent. It would actually read better than the colon as a fence marker too. When you have many colons in a row it might be difficult to see how many there actually are.

!!!{.lorem}
Quia ab est et quia exercitationem exercitationem quia. Ut ut
quia modi unde et sapiente. Est et amet autem nihil mollitia
repudiandae sit. Est labore omnis consequatur sapiente
consequuntur vel sed facere.
!!!

It has the same "pay special attention" feel too.

bpj on 1 Mar 2016

+++ Benct Philip Jonsson [Mar 01 16 09:37 ]:

I was going to suggest the exclamation mark, but I had a feeling there
may be some context where an exclamation mark would legitimately end up
at the beginning of a line. I don't know why.

Well, an image in Markdown begins with a !. We'd have to
require that the ! be followed by a space. This would be
slightly inconsistent with the existing rules for block
quotes, which don't require a space after > -- I actually
think a space ought to be required there too, but the custom
is pretty well established now of not requiring it.

jgm on 1 Mar 2016

@jgm wrote:

Well, an image in Markdown begins with a !. We'd have to require that the ! be followed by a space. This would be slightly inconsistent with the existing rules for block quotes, which don't require a space after > -- I actually think a space ought to be required there too, but the custom is pretty well established now of not requiring it.

That's it. I use images (especially inline ones) seldom enough for that to not register immediately.

I notice that line blocks already require a space, and I'm fine with that. I think the use case for block quotes is a little different, at least for me. I often reformat mailing list replies with pandoc, and when those contain quotes these may be alternately loose or compact depending on the mail clients/editors other participants have used. The same is not true of line blocks or divs which will as a rule be entered by oneself in documents destined to be rendered into some other format(s).

bpj on 1 Mar 2016

! strongly denotes an exclamation (good for .warning, .caution, .alien-invasion-tip, etc.). I think semicolon ; would work better, especially for non-exclamatory divs, like:

; {.quietly}
; Teddy bear parking for nap time is
; in the nursery. Blankies provided.

and more generic divs, eg.:

; {.toc}
; Contents
;
;   * Introduction
;   * Examples
;   * Complaints
;   * Retribution
;   * Conclusion

(Added bonus: (at least on _my_ keyboard) don't have to hit the shift key for ;.)

Looks good for delim-style too, IMO, if it turns out that's added as well:

;;; {.main-box}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec a diam
lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam
viverra nec consectetur ante hendrerit. Donec et mollis
dolor. Praesent et diam eget libero egestas mattis sit amet vitae
augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur.
;;;

uvtc on 1 Mar 2016

@uvtc, What I and @jgm are getting at is more the "attention" than the "warning" aspects of the exclamation sign. I don't care a lot since my hopes of getting the semicolon as a marker for terms in definition lists, Mediawiki style, is probably not going to be fulfilled.

bpj on 2 Mar 2016

I think that using bang ! for div syntax is less than great taste because of how strongly it denotes exclamation. If I squint my eyes and try to not see it as exclamation, then it looks very much like the line-block syntax.

(BTW, if Pandoc is ever to support comment syntax (my money is on %), I bet it ends up with both side-marked as well as fenced variants. For casual readers not too familiar with markdown, ! and !!! could be mistaken for  markers.)

Personally, I think the | would be ideal for divs, even though it would mean breaking back-compat with line-blocks.

uvtc on 2 Mar 2016

Just to look at what others are doing: python markdown implements admonitions like this:

!!! danger "Don't try this at home"
    A dangerous tip

which renders:

<div class="admonition danger">
<p class="admonition-title">Don't try this at home</p>
<p>A dangerous tip</p>
</div>

I find it really clean, but for larger divs it would be painful, because of indentation

ghost on 21 Mar 2016

Just to look at what others are doing: python markdown implements admonitions like this:
!!! danger "Don't try this at home"
    A dangerous tip
which renders:
<div class="admonition danger">
<p class="admonition-title">Don't try this at home</p>
<p>A dangerous tip</p>
</div>

That looks like a good reason _not_ to use the bang for a general div syntax, which is what we are looking for here.

FWIW I've experimented a bit with semicolon both as a side marker and as a fence marker, and I definitely could get used to it.

bpj on 24 Mar 2016

+++ Benct Philip Jonsson [Mar 24 16 10:20 ]:

That looks like a good reason not to use the bang for a general div
syntax, which is what we are looking for here.

I don't think we should feel too constrained by what one
python implementation has done.

jgm on 24 Mar 2016

@andya9 writes:

Just to look at what others are doing: python markdown implements
admonitions like this:
!!! danger "Don't try this at home"
    A dangerous tip

Although that would be easy to type, it would violate two prime Markdown directives of being easy to read and not looking too much like markup. Also, it would look a lot like a code block at a casual glance. Also it would be introducing a whole new syntax element to pandoc markdown.

I think the main problem being faced here, and why this is so difficult, is that Markdown syntax is supposed to be obvious and look like what it means, but there's really no way to do that for generic divs. So the best you can hope for is to:

look fairly good to the eye,
not get in the way too much, and
mesh well with existing syntax.

Although I think pipes | would look great as a generic side-marker, unfortunately they don't lend themselves to a possible future delimited style:

||| {.some-class #some-id}
Not sure that using
pipes as delimiters
looks very good.
|||

Also, it would be difficult to stop using them for line blocks, since they actually _do_ look kinda' like what they mean there. Further, using pipes for generic div syntax would conflict with using them in a possible future alignment syntax (see issue #719). So I withdraw my suggestion for using them for generic div blocks.

@bpj wrote:

FWIW I've experimented a bit with semicolon both as a side marker and as a fence marker, and I definitely could get used to it.

Same here. And after looking at it more, I think it actually looks better than the colon for this purpose, since:

the colon reminds me of definition lists (especially when using a
single one for side-marking); the semicolon is neutral (doesn't
really have any strong connotations), and
for side-marking, the semicolon glyph has a just enough more length to
make it a more pleasing to my eye than the colon.

uvtc on 24 Mar 2016

@uvtc Good points!
Another thing to consider is: what about spans? I think they should share a similar syntax to divs. In that case colons would look better than semicolons, but probably conflict with other syntax

ghost on 24 Mar 2016

@andya9 , @jgm already addressed spans in https://github.com/jgm/pandoc/issues/168#issuecomment-185349665.

uvtc on 24 Mar 2016

+++ andya9 [Mar 24 16 12:09 ]:

[1]@uvtc Good points!
Another thing to consider is: what about spans? I think they should
share a similar syntax to divs. In that case colons would look better
than semicolons, but probably conflict with other syntax

I think using the existing square brackets syntax for spans makes
the most sense. So you can have

[link](url){#id .class}
[span]{#id .class}

jgm on 24 Mar 2016

@uvtc @jgm Thank’you for the pointer. Yes, it’s beautiful! I like it too, it will be easier to insert in the existing syntax.

ghost on 24 Mar 2016

@uvtc wrote:

@bpj wrote:

FWIW I've experimented a bit with semicolon both as a side marker and as a fence marker, and I definitely could get used to it.

Same here. And after looking at it more, I think it actually looks better than the colon for this purpose, since:

the colon reminds me of definition lists (especially when using a single one for side-marking); the semicolon is neutral (doesn't really have any strong connotations), and

Actually the semicolon also reminds me of definition lists because of the MediaWiki DL syntax, which I think Pandoc should have adopted. But that's another issue!

for side-marking, the semicolon glyph has a just enough more length to make it a more pleasing to my eye than the colon.

There I think colons look better, but we can't use them because they clash with definition lists.

bpj on 26 Mar 2016

What about:

:::: {#id .class}
First level div

::2:: {#id .class}
Second level div
::2::

::2::
Other second level div
::2::

::::

The aside notation would probably be a pain for long divs

ghost on 28 Mar 2016

Not to discourage you but please read the history of this discussion! We have already been through the pros and cons of fence/side marking, colons versus other characters and fence-length-as-for-code-blocks or not. There is no need to rehash that!

Numbered levels for divs doesn't seem like a good idea: you would have to change the numbers everywhere if you move a div out of its previous context.

bpj on 28 Mar 2016

Everything has pros and cons, why not just do something already?

"it's about progress not perfection".

Everyone will be happy with one solution and mad at other. Let's just pick one and do it. The most popular, the syntax that other markdown parsers uses, whatever.

This issue is 5 years old. Are you guys going to reach the 10-year record?

@jgm go _benevolent dictator for life_ this time :8ball:

felixsanz on 28 Mar 2016

👍2

@felixsanz I agree with you in principle but whichever solution jgm chooses it doesn't hurt to know _which_ pros and cons there are. What if we had adopted the colon syntax only to discover afterwards that it clashed with definition list? (Well it had probably been caught by the tests, but that's one way of discovering a con.) I have a feeling we are almost there; it looks like @jgm seriously considers at least the side-marking bang syntax. It would certainly be better than nothing, and we could add a fencing syntax later, but seeing the disagreement on whether the number of characters in the fence shall be significant or not side marking would step around that issue. As for bangs or semicolons jgm might as well toss a coin as far as I'm concerned!

bpj on 28 Mar 2016

@bpj Sorry for the noise; my main intervention was for suggesting a possible solution towards nested divs (I don’t think numbered blocks were already suggested); as for the comment on asides, I put it in as jgm seems inclined towards them, but I really don’t think they would work as well as in blockquotes (where they already are a stretch, actually)... imagine using them to mark a 1000+ verses poem...

As for numbers not being convenient: we use them in html headings, so why not here? Also, if you want to move a nested blockquote you’ll need to change >> to > anyway, so...

ghost on 28 Mar 2016

To help us all, and @jgm in particular, to choose I made this file with an example of each what seems to me to be the remaining contenders, showing what a few short paragraphs of nested divs would look like in each style. I urge you all to print them out or else arrange to see them side by side, since that helps to make their relative effect visible. I added separate examples of lazy side-marking so that we don't forget to consider what those look like. I attach the file rather than posting it as one gigantic comment. That will also make it easier for everyone to look at them in their favorite text editor.

div-alternatives.txt

bpj on 28 Mar 2016

👍1

BTW I actually changed my mind after having seen them all side by side in several gvim windows.

bpj on 28 Mar 2016

I think using the existing square brackets syntax for spans makes
the most sense. So you can have

link{#id .class}
[span]{#id .class}

@jgm, could we consider the discussion syntax for spans (and only for spans) as finished?

I think it would be important that the implementation of this issue takes no longer than five years.

ousia on 28 Mar 2016

+++ Pablo Rodríguez [Mar 28 16 13:29 ]:

I think using the existing square brackets syntax for spans makes
the most sense. So you can have

[1]link{#id .class}
[span]{#id .class}
[2]@jgm, could we consider the discussion syntax for spans (and only
for spans) as finished?

Yes, I think so.

jgm on 29 Mar 2016

As I said, both syntaxes (side and surround marking) have their pros and cons, depending on the use case, so currently I’m thinking eventually we should have both. But maybe we can start with just one, let’s say side-marking (since I’ve a feeling that that’s still what jgm prefers personally), and roll that one out with the span syntax.

mb21 on 29 Mar 2016

@bpj wrote:

made this file with an example of each what seems to me to be the remaining contenders, showing {snip}

Thanks, bpj. Though, I don't understand the "lazy" style div syntax with nesting (also with no empty lines between lazy divs). For example, does

; ; {.foo}
Maiores adipisci aut at. Rerum voluptatibus ut beatae sit ullam sit
aspernatur. Temporibus similique aut quidem et alias officiis dolorum.

translate into <div><div class="foo">Maiores adipisci ...</div></div>?

Also it looks like you're closing those lazy-style divs (like delimited syntax), but I don't see why.

BTW I actually changed my mind after having seen them all side by side in several gvim windows.

Which do you prefer now?

One thing I think is noticeable when looking at a doc containing a lot of ! & !!! divs is that it seems like there's too much "yelling" in there. That would grate on me after a while.

uvtc on 29 Mar 2016

[...] But maybe we can start with just one, let’s say side-marking (since I’ve a feeling that that’s still what jgm prefers personally), and roll that one out with the span syntax.

@jgm, would you agree in implementing side-marking syntax for divisions and the syntax for spans in the next release?

ousia on 29 Mar 2016

@uvtc said:

@bpj wrote:

made this file with an example of each what seems to me to be the remaining contenders, showing {snip}

Thanks, bpj. Though, I don't understand the "lazy" style div syntax with nesting

That's probably because I don't fully understand how lazy style with blockquotes works! :-)

(also with no empty lines between lazy divs). For example, does
; ; {.foo}
Maiores adipisci aut at. Rerum voluptatibus ut beatae sit ullam sit
aspernatur. Temporibus similique aut quidem et alias officiis dolorum.
translate into <div><div class="foo">Maiores adipisci ...</div></div>?

Yes, That's the idea, though normally the outer div would probably have some content before or after the inner div.

Also it looks like you're closing those lazy-style divs (like delimited syntax), but I don't see why.

It wasn't supposed to look that way. What I intended was empty lines at the end of those divs.
Again my deficient understanding of laziness in blockquotes showing...

BTW I actually changed my mind after having seen them all side by side in several gvim windows.

Which do you prefer now?

I prefer side marking over fence marking, because nesting gets clearer and because the closing fences in particular look weird. I think the reason that backticks and tildes work as well as they do with fenced code blocks is that visually those characters don't extend more vertically than horizontally. Both bangs and semicolons extend more vertically than horizontally, which makes them ill-suited for fences. Moreover to the extent that I can stand laziness at all I actually think bangs look better with lazy paragraphs because they somehow stand out better.

One thing I think is noticeable when looking at a doc containing a lot of ! & !!! divs is that it seems like there's too much "yelling" in there. That would grate on me after a while.

The only (slight) problem I have with bangs is that I after some 20 years of daily hacking mostly in Perl and using ⚠ U+26A0 WARNING SIGN [1] to mark 'bad' forms in my dictionary work have grown a strong association of preposed bangs with negation. I even use <C-K>!! to enter the warning sign in Vim, having no use for the original meaning of that digraph (pipe). I actually feel that rather strongly when seeing several divs fenced with !!!.

bpj on 29 Mar 2016

@jgm, could we consider the discussion syntax for spans (and only
for spans) as finished?
Yes, I think so.

Having experimented a bit with a filter which converts links without an URL into spans I've discovered an edge case: pandoc interprets

\foo[Doloremque Sint](){#bar .foo}

as

[Para [RawInline (Format "tex") "\\foo[Doloremque Sint]",Str "(){",Str ".foo}"]]

I.e. as a TeX command with an argument in square brackets followed by literal parentheses, brace, etc.
Presumably this would be the same with the proposed span syntax so that

\foo[Doloremque Sint]{#bar .foo}

would become

[Para [RawInline (Format "tex") "\\foo[Doloremque Sint]{.foo}"]]

which would be unfortunate since currently this is a very useful hack when targeting both HTML and LaTeX:

\foo<span class="foo">Doloremque Sint<span>

Would you consider to resolve such cases in favor of the tex followed by span interpretation when the first thing in the braces looks like an id or class?
Please note that the TeX argument interpretation always can be forced with

\text{\foo[Doloremque Sint]{#bar .foo}}

There certainly are possible workarounds like filters which overload classes or attributes of a certain form adding the raw TeX before the span, but it would be nice if such were unnecessary.

bpj on 29 Mar 2016

+++ @bpj wrote:

I prefer side marking over fence marking, because nesting gets clearer and because the closing fences in particular look weird. I think the reason that backticks and tildes work as well as they do with fenced code blocks is that visually those characters don't extend more vertically than horizontally. Both bangs and semicolons extend more vertically than horizontally, which makes them ill-suited for fences. Moreover to the extent that I can stand laziness at all I actually think bangs look better with lazy paragraphs because they somehow stand out better.

I've suggested that, for generic divs, pandoc-markdown use the same character for side-marking as for delimiting. Maybe I've been mistaken and it's not actually very markdownish (after all, code blocks use 4-spaces for side-marking, _but_ use tildes or backticks for delimiting). Using the same character for both may be sacrificing readability for symmetry.

Consider:

Delimited div coming up.

+++ {.some-class}
The plus sign glyph nicely extends horizontally.

It also suggests the *addition* of
something to what's being delimited here.
+++

Now a side-marked div:

! {.some-class}
! Lorem ipsum dolor sit amet, consectetur
! adipiscing elit, sed do eiusmod tempor
! incididunt ut labore et dolore magna aliqua.
!
! Ut enim ad minim veniam, quis nostrud
! exercitation ullamco laboris nisi ut
! aliquip ex ea commodo consequat.

The above syntax eliminates the (IMO) unsightly !!!, which is my main complaint about the bang.

Also, I've seen that darn +++ 18 times already in this thread. Maybe put it to good use.

uvtc on 29 Mar 2016

+++ Benct Philip Jonsson [Mar 29 16 11:33 ]:

which would be unfortunate since currently this is a very useful hack
when targeting both HTML and LaTeX:
\fooDoloremque Sint

This really is a hack, and I'm not too inclined to
accommodate it. It would be much better to use a filter
that intercepts a span with class "foo" and turns it into
a corresponding LaTeX command. Indeed, it would be simple
to write a general-purposes filter that did this, and even
make it available as a binary, so people wouldn't have to
reinvent the wheel.

jgm on 29 Mar 2016

@jgm said

+++ Benct Philip Jonsson [Mar 29 16 11:33 ]:

which would be unfortunate since currently this is a very useful hack
when targeting both HTML and LaTeX:
\fooDoloremque Sint

This really is a hack, and I'm not too inclined to
accommodate it. It would be much better to use a filter
that intercepts a span with class "foo" and turns it into
a corresponding LaTeX command. Indeed, it would be simple
to write a general-purposes filter that did this, and even
make it available as a binary, so people wouldn't have to
reinvent the wheel.

OK. I have a filter which intercepts divs with classes ending in a period -- which pandoc accepts and which looks rather nice as .foo. with the Pandoc attribute syntax --, and both removes that period and inserts the raw TeX. That feels like a hack to me, but I do want some general mechanism so that I don't have to write a bespoke filter for every set of concerned classes I use. Perhaps more robust would be to have the filter look for a data-tex=foo attribute and (1) insert the raw TeX, (2) add foo to the classes and (3) delete the data-tex attribute. That way you would still get valid HTML when the filter is unavailable, although it's more to type.

bpj on 29 Mar 2016

@jgm, if you have set the syntax for spans, would it be possible to implement it in the development version?

This would be also great to have language markup (first in HTML and XML codes, then in TeX markup), such as in:

Law translates both [ius]{:la} and [lex]{:la}.

ousia on 10 Apr 2016

More Catonis instare rem prodesse non credo! :-)

bpj on 10 Apr 2016

@bpj, if you want to improve communication in an issue that is about to be five years old, I don’t think Latin is the best way to do it.

Sorry, but I’m afraid that my Latin knowledge cannot know what the sentence might mean. I can only guess and I don’t know how it should be applied to my previous comment.

But probably we need longer to even think of deploying what is already settled in this issue (I mean, the syntax for spans).

ousia on 10 Apr 2016

Which was more or less what I said! Sorry about wearing my jocular hat!

bpj on 10 Apr 2016

No problem, @bpj, but I’m not sure what you meant. If I have to quote my guessed translation to get the actual one, here you have it: “I don’t believe in the way Cato stands for it would benefit anyone”. (What Cato did and how he did anything are also unknown to me.) The actual translation is much appreciated :smile:.

I don’t really think that we need to wait longer to deploy the span syntax. And I’m not doing it myself, because coding is all Greek to me.

Do you really think we need more time to deliberate again about what is already decided? I would say so, but with Latin quotes I can only guess :wink:.

ousia on 10 Apr 2016

No, but we should not conflate issues. I believe there are separate issues both for the span synatx and the lang attribute shortcut. Never mind the Latin phrase, it was a bad paraphrase of a badly remembered quote inspired by your use of Latin words as examples.

bpj on 10 Apr 2016

I know (I opened issue #895 [and reported originally at Google Code more than six years ago ago]) and I agree: it was only a way of showing the real improvement with a dedicated syntax for spans.

ousia on 10 Apr 2016

I am considering another possible syntax, and I admit that I'm joining this party about five years late, but this exclusion has been driving me a little nuts :P I've even resorted to writing my own regex parser to parse for these particular patterns.

I'm thinking, text goes inside of a block; so why not have something like this:

(.the-class #the-ID)
    || This is some text and some more markdown that should be inside of
    || ## This markdown
    || Sometimes I want (.color)||color to surround my text||, because then
    || it has far more emphasis and is much easier to see

I feel like it's very explicit, and the double vertical lines clearly show where the styles should be applied, maybe a lazy syntax such as this one:

(.the-lazy-way) || 
    This is a block that I can write in a really lazy way because I don't
    want to type out those double lines everywhere, but I have to apply
    spans inside of my code (.example-item)|| like this ||.

May also be a good idea. Finally, if a specific element type is required, for example; if this should have all been housed inside of a div, then I can write:

(.the-lazy-way)[div] || 
    This is a block that I can write in a really lazy way because I don't
    want to type out those double lines everywhere, but I have to apply
    spans inside of my code (.example-item)|| like this ||.

What are the thoughts on that?

saivan on 13 Apr 2016

Double pipes look good, but they could be confused for nested line blocks.

But I really do like the idea of using the pipe for side-marking. It's very natural to use | that way. It's so good for side-marking that I don't think Pandoc should limit its use to line blocks...

Pandoc-markdown could add another multi-character markup syntax. It already does so with #. for numbered lists and ### for ATX-style headers.

(I'd actually suggested a 2- and 3-character side-marking syntax a while back for left-, right-, and center-justified text, all of which involve the pipe. See #719.)

Consider:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.

.| {.some-such}
.| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
.| eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
.| ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
.| aliquip ex ea commodo consequat.
.|
.| .| {.even-moreso}
.| .| Duis aute irure dolor in reprehenderit in voluptate velit
.| .| esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
.| .| occaecat cupidatat non proident, sunt in culpa qui officia
.| .| deserunt mollit anim id est laborum.
.|
.| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
.| eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
.| ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
.| aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat.

uvtc on 13 Apr 2016

Double pipes look good, but they could be confused for nested line blocks.

Both samples look great, but they are hard to type without a programming editor. Which I think it’s a crazy idea.

(I'd actually suggested a 2- and 3-character side-marking syntax a while back for left-, right-, and center-justified text, all of which involve the pipe. See #719.)

Sorry, but I must be missing something. If Markdown is about logical elements and not about format, why is the proposal about formatting and not about granting the paragraph element attributes (so that it can handle classes)?

ousia on 13 Apr 2016

Both samples look great, but they are hard to type without a programming editor. Which I think it’s a crazy idea.

I don't think they're substantially harder to type than any other Markdown syntax.

And, as noted in the above discussion and on the Daringfireball Markdown page, the overriding goal of Markdown is to be as readable as possible (so, readability beats writability). Quoting John Gruber: "The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions."

I think that's why Markdown wins. Apparently, a lot of people are willing to put in slightly more typing effort if it results in a better-looking document.

uvtc on 13 Apr 2016

I don't think they're substantially harder to type than any other Markdown syntax.

They may not be harder than any other side-marking syntax. And I think these marks scare any new user with no technical background.

BTW, it is easier to write <div> tags than the lightweight syntax replacement in your sample. (The lightweight part, no matter which design principles Markdown might aim to follow, isn’t clear to me in this point.)

Side-marking has also another “feature”: what happens when you have to modify the text? Would you have to rewrite (almost) all lines in the paragraph to have a good-looking result?

Sorry, but I think that maybe the solution may be more complicated than the original issue. I mean, I guess any lightweight markup is supposed (at least, in my mind) to make the writing much easier. And this would be great when extended to any average user, not only to people with programming skills.

ousia on 13 Apr 2016

Side-marking has also another “feature”: what happens when you have to modify the text? Would you have to rewrite (almost) all lines in the paragraph to have a good-looking result?

Yes, either that...

..._Or_ use Pandoc to re-format whatever appears as too much laboring:

 pandoc \
      -f markdown \
      -t markdown \
        input-with-sidemarking-not-looking-very-nice.md \
      --columns 100 \
      -o output-with-sidemarking-looking-very-nice.md

Sorry, but I think that maybe the solution may be more complicated than the original issue. I mean, I guess any lightweight markup is supposed (at least, in my mind) to make the writing much easier.

If you want more Markdown syntax features, you'll have to add more syntax elements to Markdown...

If an element is too complicated to use, then don't use it, and limit yourself to those which you find easy enough.

And this would be great when extended to any average user, not only to people with programming skills.

If you are an "average" user without programming skills and want to use it just to write simple documents, why would you want to use many more elements than:

headlines (2 or 3 levels)
paragraphs
bold and italic words
ordered and unordered lists
quotations/block quotes
maybe hyperlinks
maybe images

? -- The (very basic) Markdown formatting rules for these seven style elements allow already for quite sophisticated documents. If you want to use more, you have to learn more. And once you learn more, you are starting to develop personally beyond the skills of an "average" user... How far you go, is up to you.

KurtPfeifle on 13 Apr 2016

I think using something like the double pipe serves to act like a bracket. It unambiguously shows where the classes should be applied, and it avoids looking "marked up", which can't be said for inline span blocks and inline divs.

On top of that, they could provide an easy way for users who aren't just trying to convert to html to apply styles to their work. For example, pandoc could allow users to apply a blue color to sections marked up like this:

I want the next few words to be (blue)|| blue for a while ||.

Theres no reason why that can't support other markup formats.

saivan on 14 Apr 2016

Hi, another guy late for the party. It's a very long thread and I've tried hard to read everything but I still might have missed something that has already discussed. So let me write down my assumptions/summary from the thread and see if I misunderstood anything:

Assumptions/summary

Please correct me if I'm wrong on any of the following assumptions:

This new syntax(s) is/are functionally identical to the current native pandoc divs (not mentioned here but seems a fair assumption?)
most of the discussions is around
1. which kind of syntax to use: fenced vs side-marked
2. which particular syntax (e.g. symbols) to use
which particular syntax (symbol) to use is not very important, but it's more important to _have_ a certain syntax (probably people find out the opinions are too diverge and there's no clear winner)
which kind of syntax (fenced vs side-marked) to use however is still controversial, some prefer both to be available, but @jgm said:

I think just having side-marked syntax is still on the table. I don't find the arguments for the fenced syntax all that compelling.

Some of my thoughts on the different kinds of syntax

Fenced syntax is already there

If assumption (1) is correct, then a fenced syntax of divs is already in pandoc's syntax since native HTML divs is already native pandoc divs, and HTML divs is fenced.

If so, I think the discussion is then to have a fenced syntax that is markdown-ish rather than plain HTML. And I personally think it is very important for pandoc to have a native syntax for every native features, not HTML syntax only (it is my primary intention to open #2761: the native pandoc small caps syntax is in HTML).

The same point can be argued for or against having a new fenced syntax. To against it, one can say there's already one if you absolutely have to use it. To support it, one would say there's already one so we should improve it by making it native, markdown-ish. Clearly I'm the later kind since _I hate having native pandoc syntax being plain HTML_.

Another minor thing to mention is, inline vs block. Just like code, sometimes it can be one line, sometimes very long, so it is useful to have both inline and block kinds of syntax. While may divs tends to be long, sometimes it can be very short (an example is when pandoc is used with a CMS). So I think it is useful to have both. But this is really minor and shouldn't waste too much time on this according to assumption (3).

The problems with side-marked syntax

Some of the problems I think side-marked syntax have:

Compatibility With Other Markdown Editor

To me, I need to edit markdown in a markdown editor, not general text editors. For example, one of the important feature I need is ToC. And no matter how powerful some text/code editors are (e.g. Atom, TextMate), they can't give me a ToC panel to have an overview or jump between sections.

My habit is not important at all but just an example. The point is, I guess many pandoc markdown users also edit them in some form of markdown editor (e.g. MultiMarkdown Composer, Macdown, Byword, etc.).

So the problem with side-marked divs is now obvious, e.g. if a heading is in a side-marked divs, most probably the markdown editor is not going to recognize it as a section and show it in the ToC panel. Other similar features e.g. code block, block quotes, etc. will face the same problem.

Note that I'm not saying the HTML rendered by those markdown editor, but the features of those markdown editor _within_ the editor pane, e.g. TOC panel, syntax highlight, etc.

Difficult to Move the Divs Around

More often than other things, the "fence" of divs often get changed and it's very difficult to do that in side-marked syntax. It's really different than, e.g. code block, that when you paste you know in advance the whole thing is a code block and once pasted it can be "forever" settled (and even in this case, code block is not side-marked). Similarly for block quotes (unless sometimes people use block quotes creatively/wrongly as a styling. Another problem of not having a universal divs/spans that target every output format. More on this later).

Conclusion: Fenced Syntax Is More Important, Against Side-Marked Syntax _Only_

To make it clear, the problem with side-marked syntax only arises if this is the only native pandoc syntax (excluding the HTML non-markdown-ish one). It certainly will be ok if both kind of syntax are provided and the end-users can choose the one appropriate for the situation.

And in my opinion the need of the fenced syntax is bigger than the side-marked one since the fenced one is already there and should be improved by making it markdown-ish, not plain HTML.

Expanding the functionality of native pandoc divs (and spans?)

Regarding the LaTeX Hack, @jgm said:

This really is a hack, and I'm not too inclined to
accommodate it. It would be much better to use a filter
that intercepts a span with class "foo" and turns it into
a corresponding LaTeX command. Indeed, it would be simple
to write a general-purposes filter that did this, and even
make it available as a binary, so people wouldn't have to
reinvent the wheel.

I love the idea of "expanding the reach of pandoc native divs (& spans)". Currently it is not doing anything to the, say, LaTeX output. I personally target HTML and LaTeX generations at once for most of the time.

I'm just brainstorming. For example,

it will be great if the native pandoc divs (& spans) has a standard transformation to LaTeX code and one can control it in the template.
May be an command line option is provided to activate/disable this feature.
There may be a need to turn this feature on/off per use within the document (such that a certain divs/spans are only in the HTML-related output). May be something like markdown=1 kind of syntax?

In my opinion, this is even more important (to expand the functionality of native pandoc divs) than finding a better syntax for it (if assumption 1 is correct).

Another related issue is that, I think the documentation on this needed to be improved. From reading the documentation, _one will not know native pandoc divs has no effect on LaTeX generation_, for example.

Lastly, I notice none of the above very long discussions used a heading at all. So please pardon me using so much. It is how my brains work and I don't know how else to organize my thought.

ickc on 16 Apr 2016

This really is a hack, and I'm not too inclined to
accommodate it. It would be much better to use a filter
that intercepts a span with class "foo" and turns it into
a corresponding LaTeX command. Indeed, it would be simple
to write a general-purposes filter that did this, and even
make it available as a binary, so people wouldn't have to
reinvent the wheel.

This might be an example of the kind of functionality/hack needed:

<!-- \begin{flushright} --><div align="right">
text on the right
<!-- \end{flushright} --></div>

The above code in MultiMarkdown would becomes

\begin{flushright}
text on the right
\end{flushright}

in TeX, and

<!-- \begin{flushright} --><div align="right">
text on the right
<!-- \end{flushright} --></div>

in HTML, which are both desirable results.

But there seems no way to do it in pandoc.

ickc on 18 Apr 2016

+++ ickc [Apr 17 16 21:51 ]:

But there seems no way to do it in pandoc.

You can do it quite easily with a filter.

jgm on 18 Apr 2016

You can do it quite easily with a filter.

I should have put a parenthesis saying (except with a filter). In other words, the pandoc language can not do that. i.e. there's no toggle that I can only activate part of the codes in a certain output format.

In the case of HTML, some thing like

<div>
blah blah
</div>

will always at least have the blah blah,

and

\begin{abc}
blah again
\end{abc}

can never have the blah again showing up in other output (except when -R is used so that the whole thing is shown).

Even if I don't mind to repeat the whole thing, it cannot be done:

<div align="right">
text on the right
</div>
\begin{flushright}
text on the right
\end{flushright}

This is almost ok except the text inside the div will still show up in the tex output. It is because the way raw html and raw latex handled in pandoc is fundamentally different. An html "begin&end" block will still appears in LaTeX output, but the LaTeX "begin&end" block will disappears (for the whole thing).

I am saying all these because I support your idea of turning the native pandoc divs and spans, through an official filter, to _do something_ in LaTeX. Because it is something that cannot be done currently (without filter). And if the hypothetical filter becomes official, it is not only a filter but a feature in the pandoc language (the pandoc native divs and spans).

e.g. a possible syntax for native pandoc divs and spans to do something in TeX:

<div tex-env="flushright" align="right">
testing
</div>
<span tex-com="textrm">
testing
</span>

becomes

\begin{flushright}
testing
\end{flushright}
\textrm testing

In a certain sense, it is kind of a generalization of <span style="font-variant:small-caps;">Small caps</span>, that a certain native HTML span (and native pandoc span) can becomes a native LaTeX command.

ickc on 18 Apr 2016

@ickc something like this is under discussion, see #2542 (although the title of that issue hasn't been changed to reflect the broadened discussion..)

mb21 on 18 Apr 2016

I'd written:

Double pipes look good, but they could be confused for nested line blocks.

Ah, I was mistaken. Line blocks don't nest (unlike blockquotes (>)). And line blocks require a space after the pipe (unlike blockquotes). So, I think you could use the double pipe as a 2-character side-marking syntax to indicate divs without conflicting with line blocks.

Looks nice.

Feed your goldfish regularly.

|| {.warning}
|| Do not over-feed your goldfish.
|| One child repeatedly over-fed
|| his goldfish until it had to be
|| moved to a pond where it reached
|| a length of 8 meters and weighed
|| over 1100 kg.

Appropriate foods include...

uvtc on 20 Apr 2016

Sorry if it doesn't seem to relate to this thread, but I think Spans and Divs' syntaxes and their functions (in terms of what they will output) should be related.

@jgm

You can do it quite easily with a filter.

@mb21

@ickc something like this is under discussion, see #2542 (although the title of that issue hasn't been changed to reflect the broadened discussion..)

I made a filter in pandocfilters/latexdivs.py at master · ickc/pandocfilters: <div latex="true" class="note abc">...</div> will becomes \begin{note}...\end{note}.

I wish a similar syntax can make into the official pandoc language so that a filter is not needed.

In principle a similar thing can be done for spans (<span latex="true" class="text abc">...</span> will becomes \text{...}), but there's an extra complication that the Span is in a Para.

ickc on 22 Apr 2016

@chdemko make a filter doing a similar thing: chdemko/pandoc-latex-environment: Pandoc filter for adding LaTeX environement on specific div.

Instead of having latex="true" in the divs like I did, he defines the classes that will be a LaTeX environment through YAML front matter, like this:

latex-environment:
  test: [class1, class2]
---
<div class="class2 class1">content</div>

will be rendered in LaTeX formatting as

\begin{test}
content
\end{test}

Could @jgm comment on if any of these syntax can make into the official pandoc language?

ickc on 22 Apr 2016

@ickc if you are prepared to kludge if with HTML comments you might want to try this filter which kludges it with code/code block elements. https://gist.github.com/bpj/e6e53cbe679d3ec77e25

The main advantage is that the LaTeX/other format stuff won't show up in generated HTML (you will have to run the filter when generating HTML though), and you can specify explicitly which/any format each raw code is.

bpj on 22 Apr 2016

👍1

@ickc if you are prepared to kludge it with HTML comments you might want to try this filter which kludges it with code/code block elements. https://gist.github.com/bpj/e6e53cbe679d3ec77e25

I hope you don't mind I added it to the Pandoc Filters · jgm/pandoc Wiki.

It would be very useful for me to include TikZ/PSTricks graphics. I am thinking about using yours together with the Input File scripts in Scripting with pandoc. So that the RAW LaTeX is put in a separate files, and wrote a script to compile that file as a PDF, and use your method to included the generated PDF in HTML but RAW LaTeX in LaTeX.

ickc on 23 Apr 2016

@ickc wrote:

It would be very useful for me to include TikZ/PSTricks graphics. I am thinking about using yours together with the Input File scripts in Scripting with pandoc. So that the RAW LaTeX is put in a separate files, and wrote a script to compile that file as a PDF, and use your method to included the generated PDF in HTML but RAW LaTeX in LaTeX.

A dedicated filter which detects the output format and does the right thing, including generating the PDF file as needed would probably be easier to work with. As you can see from the usage notes I mainly use the code2raw filter to sneak raw LaTeX code into the preamble through metadata variables. In most cases there are more elegant ways to make content conditional on the output format. The code2raw filter is good for quick one-off hacks though.

bpj on 23 Apr 2016

@uvtc wrote:

I'd written:
Double pipes look good, but they could be confused for nested line blocks.
Ah, I was mistaken. Line blocks don't nest (unlike blockquotes (>)). And line blocks require a space after the pipe (unlike blockquotes). So, I think you could use the double pipe as a 2-character side-marking syntax to indicate divs without conflicting with line blocks.

Imagine nested divs with that syntax! It would become eyeball-unparsable pretty quickly.

bpj on 23 Apr 2016

Imagine nested divs with that syntax! It would become eyeball-unparsable pretty quickly.

Mm. That's a good point. Syntax that nests should look good when nested.

Ok.

Some givens:

|| may indeed be too cumbersome for use with nested divs
divs nest, but line blocks don't (and so do not need a syntax that nests well)
it's tough to beat | and > for side-marking characters

But another note about line blocks that's been a bee in my bonnet: I type addresses in emails often, but almost never use line blocks (or lines ending with backslashes) because recipients can't easily copy/paste them. If I _were_ to use line block syntax, folks would wonder why the heck I'm adding those funny characters in when I type addresses. It's not markdownish. Line-blocks could really use a delimited syntax.

Consider:

Hi.

| A side-marked div with no
| attributes. Uses a side-marking
| that looks like a "single line".

Lorem ipsum.

| {.some-class}
| A side-marked div with an attribute.
| This seems like a natural way to
| write this.

Lorem ipsum.

--- {.some-class}
A delimited syntax for divs. Also uses a
"single-line" marking, like `|`, but
horizontal. I think this may be the most
obvious markdownish syntax for a generic
delimited container.
---

Lorem ipsum.

|| A side-marked syntax for line
|| blocks. Uses a "*double* vertical
|| line" side-marking to emphasize,
|| "these are lines in a line block".

Lorem ipsum.

===
A delimited syntax for line blocks.
Note, it also uses a double-line,
like `||`, but horizontal.
===

Done.

Of course, this breaks backcompat. And would also require pandoc to be more strict about rules for setext headers (require a blank after) and horizontal rules (require blank lines before and after).

@jgm, what do you think of the possibility of a "pandoc_markdown_strict" mode that:

requires a blank line under setext headers
requires a blank line above and below HRs
any other strictures you think might be desirable (ex. require a space after > when blockquoting, as you mentioned earlier in this thread, require list and sublist content always be indented by 4 space, etc.)

(which, I'd like to think, could enable the div and newer lineblock syntax as described above)?

* * *

Added bonus regarding using double-pipe for line blocks: it would go nicely with some proposed suggestions (by yours truly) for future right-align and center-align syntax (#719) --- all three of which would (1) start with a pipe, (2) consist of multiple characters, (3) and keep each line on its own line:

|| line block
|| here

|>           right align
|>                  here

|<>   center align
|<>       here

uvtc on 25 Apr 2016

Another place I just saw where ------ is commonly used to mark what is practically a div:

> > Will you make it?
>
> Ok, I'll be there!

Great, see you this weekend!

-- John

---------------------------
This email and the attachments herein
are copyright the sender, and in no way
suggest or guarantee that the sender will
be corporeally or temporally available
this weekend, or any other weekend,
for any planned or unplanned activities
with this or any other recipient.
---------------------------

uvtc on 27 Apr 2016

Another place where I often find I need a delimited divs syntax:

I went to the url you told me about, but didn't understand
the instructions. It said:

----------------------------
Dear Applicant,

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur.

Completed forms due by Oct 31 or Dec 25!
----------------------------

Should I send the forms in on Hexember 19?

I could imagine maybe wanting to use some kind of delimited blockquote syntax for that, but it's not really quoting someone per se, but rather copying/pasting content from elsewhere.

I've seen Python programmers sometimes use triple quotes for this, but I think triple quotes are unpleasant to look at.

I think side-marking with pipes would look best here:

I went to the url you told me about, but didn't understand
the instructions. It said:

| Dear Applicant,
|
| Lorem ipsum dolor sit amet, consectetur adipiscing elit,
| sed do eiusmod tempor incididunt ut labore et dolore
| magna aliqua.
|
| Ut enim ad minim veniam, quis nostrud exercitation
| ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
| Duis aute irure dolor in reprehenderit in voluptate velit
| esse cillum dolore eu fugiat nulla pariatur.
|
| Completed forms due by Oct 31 or Dec 25!

Should I send the forms in on Hexember 19?

but again, for practicality, there are times when you want to copy/paste a large block quickly, and it may even be one that you expect others to want to subsequently copy/paste (as plain text) and not have to deal with side-markings (analogous to the situation with delimited code block syntax).

uvtc on 17 May 2016

@uvtc Please note there is already a | delimited block format in Pandoc that changes how white space is handled. That particular example of yours is also an exact match for using the existing block quote syntax as that's semantically what that content is.

This issue that needs to be addressed here is for content that has some attribute other than being a simple block-quote. For that using an open and closing block format (with attributes of course) seems like a much more versatile solution than a left delimited option.

alerque on 17 May 2016

@alerque , I understand that there is already a _side-marked_ | syntax, and that it's used in Pandoc for line-blocks. I'm proposing that it's worthwhile in this case to consider breaking backward compatibility in the following ways:

change side-marked line block syntax from | to ||
add a new delimited line-block syntax: ===
add a new side-marked generic div syntax: |
add a new delimited generic div syntax: ---
to accommodate this, make Pandoc markdown a little more strict about a handful of items which it now is pretty flexible on (or maybe provide a --pandoc-md-strict mode).

My rationale for those changes is given in my most recent 3 posts here, and is also partly distilled from the years of comments in this thread. My hunch is that

it's the best way to go,
breaking backcompat could be painful for some (how many people are using line blocks?), and
it's probably worth it in the long run.

From what I've seen, @jgm has historically been thoughtful in making changes/additions to pandoc-markdown syntax, and disinclined to break backcompat. Also, this thread has been going for quite some time, and folks are probably very tired of discussing it. On the bright side, I haven't yet run out of jokes to include in my sample pandoc-markdown blocks. ;)

uvtc on 17 May 2016

I would like to know whether there is any progress related to this issue.

Sorry, but after so much time, the implementation has reached this conclusion (click on the image to watch a >9s clip):

A question and a comment:

Since the syntax for <span> seems to be already clear, would it be possible to have it implemented without having to wait for the syntax for <div>?
Please, remember that it is just a comment. If Markdown resembles HTML syntax, there is a feature there: XML tagging is surround marking, not side marking.

ousia on 15 Sep 2016

+1 on the [[[ syntax:

Using side-syntax seems ends up being too noisy as divs might span many lines
If you have nested blocks, the colon syntax ::: is hard to visually grasp (because the beginning of a div look almost the same as the end of another)
I tried other marks ('<<<', '{{{') and they seemed either a bit ugly or confusing (similar to existing usage, like quotes).

Finally, I also agree with @ousia in that brackets are better but colons are also fine and definitely better than nothing.

[[ center
This text is centered

[[[ alert
And this is an *alert*
]]]

This is also centered
]]

sergiocorreia on 22 Sep 2016

@sergiocorreia +1 for having inner divs use more markers than outer divs.

Seeing your example it is at least clear where each div starts and ends. I still think there should be the option of putting a comment after the closing marker though.

However I also see that many square brackets in a row are still jarring to my eyes. Two is about as much as I can take, three is beginning jar.

So what about a compromise (knowing well that compromises tend to make noone happy...)

[[::: center
This text is centered

[[::::: alert
And this is an *alert*
:::::]]

This is also centered
:::]]

bpj on 26 Sep 2016

Looks nice but the main problem I see is that it requires 10-12 characters for each div. Maybe we can make the colons optional?

sergiocorreia on 26 Sep 2016

Well, I guess we only need one bracket and a minimum of two colons. I tend to use a lot of backticks on my codeblocks because I have a key sequence which inserts two backticks with the cursor between them, so I hit it at least twice, or three to six times if I expect there to be any backticks inside the codeblock. It isn't the actual number of chars so much as how they look and how easy they are to type.

Come to think of it: when brackets indicate nesting there is never any need to type more colons than the minimum!

[:: center

This is centered.

[:: alert
   This is an *alert*
::]

This is still centered.
::]

bpj on 26 Sep 2016

@sergiocorreia and @bpj, just a single detail.

As far as I knew, I thought that the syntax for #identifiers and .classes was set in stone.

It is already in use in the few elements that allow attributes (such as titles).

Do you also want to discuss the syntax for attributes or had I misread something in your samples?

ousia on 26 Sep 2016

@ousia you are right, but code blocks also have an alternative to {.classname} in:

    ~~~ classname
    lorem ipsum
    ~~~

For simplicity, I think we should just keep the same convention as code blocks and allow class names with both the shortcut and brackets.

In any case, I like the [[ , :: and [:: notations for divs. We can also look at what others are doing (e.g. asciidoc has several types of delimiter blocks, for literal text, source code, etc.)

sergiocorreia on 26 Sep 2016

@sergiocorreia, I didn’t know that.

It’s perfect for me to have alternative versions for the attribute syntax.

With the markup characters themselves, maybe the whole issue would be to have a timeline for implementing the span and division syntax.

Otherwise, we are discussing this _ad infinitum_ (or “To infinity... and beyond!” :wink:).

ousia on 27 Sep 2016

👍1

After re-reading everything and going through the commonmark discussion, I would just go with :::

Assuming we use [] for spans, then [[ doesn't play well with nested spans.
The other blocks don't have symmetric notation (e.g. ~~~) and there is not much confusion about it, so I think having [:: might be too complicated

It would also be easy to implement, as it would be the same as ~~~ except that we parse the contents as markdown and not as source code.

sergiocorreia on 27 Sep 2016

👍1

@sergiocorreia, I’m not enthusiastic about :::, but to have the feature implemented is essential to be able to remove XML markup in Markdown documents.

But the final decision comes from @jgm and we have to wait for his final move on this issue.

ousia on 27 Sep 2016

@sergiocorreia:

The other blocks don't have symmetric notation (e.g. ~~~) and there is not much confusion about it, so I think having [:: might be too complicated

It would also be easy to implement, as it would be the same as ~~~ except that we parse the contents as markdown and not as source code.

But with code blocks we never have actual nested code blocks inside each other. With divs there is a real problem with this. If we don't use symmetric markings inner divs must have more/less markers, which soon can become a lot, since divs must be able tonest arbitrarily deep. Moreover the intuitive thing for divs would be to have more markers on inner divs, but that would be the the opposite of the way it works with code blocks. I have realized that with symmetric marking both those problems will go away, since we then can use the same fixed-length div marker at any nesting level.

There is no conflict with spans if the div marker is [:: ... ::]: if you want to put double colons at the start/end of a span or link text you can escape them with backslashes. There would be such a conflict if the div marker was just _n_ square brackets though!

bpj on 27 Sep 2016

we could also implement a div syntax and keep it behind an extension flag which is disabled by default to gain some more experience in what works for different people that are willing to put up with a non-definitive syntax...

mb21 on 28 Sep 2016

The trouble with adding practical but less-attractive markup to Pandoc-markdown is that it compromises Markdown's goals: that it be easy and natural to read, and look good as plain text (even to someone who's never heard of markdown). The markup is supposed to blend in so well that it almost doesn't look like markup at all. This makes it harder to write, and harder to parse, but it's also what differentiates Markdown from asciidoc, reST, et al.

Blocks side-marked with | and > work beautifully for this. Blocks fenced/delimited with something basic and symmetrical like ~~~ (or, as I've suggested previously, --- and ===) work well too; it actually looks like you drew a marking above and below to indicate the block. But as soon as you start using special bunches of matched characters (such as [[[ ... ]]]), then the markup becomes conspicuous. The non-markdown-savvy reader begins to wonder if your cat walked across your keyboard while you were typing.

uvtc on 29 Sep 2016

👍2

I would actually prefer the === fence syntax over all others,
but as @jgm has already pointed out it conflicts with setext headers,
and --- conflicts with both setext headers and YAML blocks, and then most sensible fence character candidates conflict with horizontal rules.

Of the options left I really prefer ::: fences, with increasing number of colons for inner divs.

My attempt at a compromise was apparently like most such attempts making noone happy.

Almost anything is better than the HTML syntax, though...

bpj on 30 Sep 2016

As I recall, the last conclusion a few months ago seemed to be @jgm prefer side markings but not surround marking (I might be wrong).

But the recent discussions seem to center around surround marking.

I personally also prefer surround marking:

It's location is then the same as the current syntax, which allow batch processing to convert old files to use the new syntax.
It won't confuse other _markdown editor_. Any other markdown editor not using pandoc (practically all) won't be confused by the new syntax (which will only ignore the 2 surround marking in their own lines that it doesn't understand.).
And lastly, since the current pandoc div is surround marking, let's at least give a native markdown-ish syntax for it.

👍 on the ::: by the way. Seems best (least worse) after method of elimination.

I also agree to implement it first, even if partially. We might get the span and the surround marking div done first and leave the controversial side mark syntax for div in a future discussion.

ickc on 2 Oct 2016

👍2

@jgm, I wonder whether there is anything the users could do to help to implement (and solve) this issue.

::: seems to have many adepts.

A good alternative compromise would be to implement both surround- and side-markings. The block element code has both (tab or four spaces and three backticks).

ousia on 3 Oct 2016

I just reread this huge thread and wanted to summarize my thoughts.

I still favor side marking but I suspect it's the minority view. Options discussed:

: can conflict with existing definition list syntax (this is pretty bad and I don't see a good way to solve it)
! can conflict with image markup, if we don't require a space (as consistency with > side marking would require)
| conflicts with existing line block markup and couldn't be used without breaking existing documents
; is visually less nice than the others but doesn't have conflicts.

I'm not terribly happy about any of these options, but ; is probably the best.

Another option which I don't think was discussed above (though it was discussed at talk.commonmark.org) would be just overloading the existing block quote syntax. The idea would be that a block quote that starts with a pandoc attribute specification would be parsed as a Div. Example:

> {.warning #mywarning}
> This is my warning!

Advantages of this approach:

no need for new special characters
very light changes required in the Markdown parser
should look good with existing Markdown syntax highlighting in editors
degrades nicely when rendered by non-pandoc Markdown parsers.

Disadvantages:

you can't have a plain Div with no attributes (though you could always use {} for this case)
> has a strong connotation of "blockquote"

To my mind, the advantages outweigh the disadvantages here.

For surround-marking, ::: may be the best option. I suppose if we did the > approach for side-marking, a matching surround-marking syntax would be

>>> {.warning}
This is a warning
<<<

This is a bit ugly and markup-ish, but it has the advantage of distinguishing open and close markers.

Surround-marking raises a number of tricky questions of precedence, e.g. how do you deal with

``````
:::

:::

``````

Side-marking is less problematic in this respect.

jgm on 26 Oct 2016

👍3

Great to see this moving forward again!

: can conflict with existing definition list syntax (this is pretty bad and I don't see a good way to solve it)

maybe the term of a definition list shouldn't be allowed to start with a colon? I doubt this would break many existing documents and definition lists seem to require a blank line before the first term already...

Overloading the existing block quote syntax is actually an interesting idea. Although having basically the same syntax for what's a different element in the pandoc AST feels kind of wrong... but probably that's just me.

About the issue of precedence in surround-markings: I guess what most people would expect is for whatever opens first to greedily take precedence (might also be simpler to implement in parsers):

``````
:::

:::

``````

is transformed to:

``````

```

``````

mb21 on 26 Oct 2016

maybe the term of a definition list shouldn't be allowed to start with a colon?

That's not the issue. Consider:

my term

: my definition

Currently this is a valid definition list in pandoc.

I guess what most people would expect is for whatever opens first to greedily take precedence (might also be simpler to implement in parsers)

That's one possible choice. But usually in pandoc code blocks/spans bind more tightly than other constructions.

jgm on 26 Oct 2016

:+1: Block-Quote Side-Marking

I love the use of block quote syntax. It felt natural and degrades gracefully in any markdown editors. Personally it totally changed my preference between side-marking and surround-marking. Now I would prefer this side-marking syntax over any of the surround-marking just because of the "support" in the markdown editors I used.

Surround-Marking: Symmetric vs. Asymmetric

I tried to go through the list of pandoc markdown syntaxes that are either symmetric of asymmetric:

Symmetric
- header: #
- code blocks: ~~~, ``</li> <li>YAML: <code>md5-1e8cb626475eff8cfabc43b38603b58f</code></li> <li>emphasis: <code>md5-dedc7034c62c9de61d61daaaef8c0289</code>, <code>md5-d289f8083708ec46a05e5092a81a3b62</code></li> <li>strikeout: <code>md5-8e855029aa5502d2ab9280d22f8eb7b6</code></li> <li>super/subscripts: <code>md5-492a603a67bdf509557015223a03b4c0</code>, <code>md5-e8bf64ba908370bc72b4708b2ea91668</code></li> <li>Verbatim:
- Math: $, $$
Asymmetric
- link: [], ()
- YAML: ---...

So having an asymmetric syntax for a div seems kind of odd.

And then concerning those markdown features that has both side-marking and surround-marking:

code blocks
metadata blocks

Both of them actually uses different characters for side-marking and surround-marking respectively. So it seems not necessary to use the same > character for surround-marking div.

Visually, it is actually not bad (to me). It has a strong sense of begin and end (albeit may be a bit too strong, making it a bit distracting). But will reversing the order make more sense? _i.e._

<<< {.warning}
This is a warning
>>>

The ::: syntax looks less distracting, natural, calm. I agree it adds extra complexity. But I remember @jgm said somewhere (probably a comment on allowing csv_tables as yet another table syntax) that concerning markdown syntax, (I paraphrase) the visual component is more important than the ease in programming/writing. In this sense, it seems ::: is a better markdown syntax.

P.S. Or is it? I forgot if we have discussed symmetric vs. asymmetric before. Since div can be nested, asymmetric surround-marking might make it visually easier to discern the nesting.

ickc on 26 Oct 2016

From a parsing point of view, the >>>/<<< surround markers and the ::: surround markers are about equally complex to implement. The issue about precedence I noted before comes up for both of them. With ::: surrounds, we'd want to allow varying lengths to make nesting possible; with >>>/<<< this wouldn't be necessary. As someone commented above, a small advantage of asymmetric markers is that an editor could be programmed to jump between them.

Between <<< and >>>, I think I like >>> better as the opener -- it's like an arrow saying, look, here's a special thing!

jgm on 26 Oct 2016

With sufficient nesting, the >>> and <<< markers look a lot like git merge conflict markers.
That can lead to interesting results when merging documents.

emwap on 26 Oct 2016

👍2

Good point about the merge conflict markers. I suppose another alternative that would keep the continuity with > would be:

>----- {.warning}
You can use any number of hyphens >= 3.
<----

jgm on 26 Oct 2016

Ah, right. I see the (obvious) clash with definition lists now...

Support in existing editors is a strong argument for blockquote-like syntax. However, what if we ever were to support adding attributes to blockquotes? e.g.

> {.pull}
> my pull quote

mb21 on 26 Oct 2016

👍1

Just throwing this out there, but my primary use case for this _is_ blockquotes that need class attributes. It's not my only use case, just the most frequent one I run into. I was going to overload the div's as stand-ins for special blockquote types.

alerque on 26 Oct 2016

Adding attributes to block quotes makes sense. I've read a few times that people want the author of a quote in a different style, which you could achieve with:

> {author="John Smith"}
> Lorem ipsum dolor sit amet,
> consectetur adipisicing elit

About <<< syntax,

FWIF, since it is not symmetric, there is no need for nesting it (no need for <<<<<<<<<) so it shouldn't conflict with git
I would prefer <<< ... >>> instead of >>> ... <<<, which feels "wrong"

Another nice use for divs is as placeholders, for adding TOCs or includes:

<div id="toc"></div>

<div include="../common/disclaimer.md"></div>

These could translate as

::: toc
:::

::: include
../common/disclaimer.md
:::

Or

<<< toc
>>>

<<< include
../common/disclaimer.md
>>>

(Having these as one-liners would be amazing but probably make it harder for the parser)

sergiocorreia on 26 Oct 2016

I was going to overload the div's as stand-ins for special blockquote types.

Well of course you could still do this with the side-marked > syntax. Indeed, this should be better for you than alternatives, since it will still look like a block quote. The only question is whether we'd going to need a way to add attributes to regular block quotes, too, and if so whether this would conflict with the proposal above. Unfortunately this gets into a discussion about syntax for adding attributes to arbitrary elements which would gum up an already overloaded issue thread. Certainly there are some ways of doing it that wouldn't conflict, e.g.

{attributes}
[ the block ]

jgm on 26 Oct 2016

>----- {.warning}
You can use any number of hyphens >= 3.
<----

This visually looks like HTML comments though.

ickc on 26 Oct 2016

@mb21:

Ah, right. I see the (obvious) clash with definition lists now...

Support in existing editors is a strong argument for blockquote-like syntax. However, what if we ever were to support adding attributes to blockquotes? e.g.

{.pull}
my pull quote

What about a pseudo-attribute?

{.pull quote=1}
my pull quote

We already have the <htmlblock markdown=0> pseudo-attribute.

@ickc:

    >----- {.warning}
    You can use any number of hyphens >= 3.
    <----
This visually looks like HTML comments though.

Not overly, since there is no ! after the < and the order of > and < is inverted, and if it does that's not the end of the world, especially since links will also look like a special case of the now implemented (thanks @jgm!) span syntax. In fact it looks a lot like one type of marking many people use for marking large quotations in email, which IMO is a Good Thing.

As you all might have guessed I like this syntax a lot, and so does jgm apparently.

bpj on 27 Oct 2016

I would just go with colons, as it fits better with existing markdown style (~~~, etc.). It would also be useful if these could be set as one-liners:

::: toc :::

Gets transformed into <div class="toc"></div>. This would make custom extensions much easier, as empty divs could be used as placeholders, something hard to do with filters and arbitrary placeholder strings.

sergiocorreia on 27 Oct 2016

Well a one-liner could be

>--- toc ---<

Unlike with code blocks that wouldn't clash with anything.

bpj on 27 Oct 2016

Some observations, then a possible solution.

① Side-marking syntax: people tend to have strong preferences about the character they want to use, and there's not many available ascii choices (!, ;).

② I'd previously suggested:

| {.foo}
| This is a div with class="foo". Lorem ipsum dolor sit
| amet, consectetur adipiscing elit, sed do eiusmod
| tempor incididunt ut labore et dolore magna aliqua.
| Ut enim ad minim veniam, quis nostrud exercitation
| ullamco laboris nisi ut aliquip ex ea.

but even _that_ looks a little lacking, what with that "{.foo}" sitting up there alone at the top. It's not very obvious to the reader what it's supposed to mean. Also, it would look better if the {.foo} trailed after something, like it does with "[hey](./bar){.foo}" or "~~~{.foo}".

③ ">" is an _ok_ side marker in general, but what makes it fit best for blockquotes is that it's a sort of arrow that indicates indenting to the right. Works perfectly for quoting conversations, but I think adds confusion if overloading it for divs as well. I think there's a better solution (getting to that).

④ The matching >>> and <<< looks too much like markup, and html, and git conflict markers. And it could easily be mistyped as <<< ... >>>, >>> ... >>>, or <<< ... <<<.

⑤ Back to using syntax that's obvious, here's something that's perfectly obvious to the reader:

+++ Pedro said:
> If you vote for me, all of your
> wildest dreams will come true.

It's official, I'm voting for Pedro.

We see that all the time and know exactly what it means.

I think there's a similar Emacs minor mode (though I don't know which) that gets you something like:

,---[Pedro said]
| If you vote for me, all of your
| wildest dreams will come true.
`---

Both of those syntaxes work --- people understand on-sight that the first line is some kind of header.

I even sometimes write things like:

---- Important stuff ----
Leave a pumpkin out for
Jack Skellington this
Halloween.
-------------------------

Headers work.

* * *

So, I think the following would work well for Pandoc markdown:

Hi.

! --- {.warning}
! Toast is very hot. Butter
! with care, and handle only
! with tongs.

; --- {.info}
; Tea is now available in
; the dining car. Please sip
; quietly.

☣ --- {.danger}
☣ The management strongly
☣ suggests you not order the
☣ seafood platter this evening.

; --- {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; sed do eiusmod tempor incididunt ut labore et dolore
; magna aliqua. Ut enim ad minim veniam, quis nostrud
; exercitation ullamco laboris nisi ut aliquip ex ea.
;
; | --- {.bar}
; | Commodo consequat. Duis aute irure dolor in reprehenderit
; | in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
; | Excepteur sint occaecat cupidatat non proident, sunt in culpa
; | qui officia deserunt mollit anim id est laborum.
;
; ♩ --- {.music}
; ♩ A little bird told me that
; ♩ many hands make light
; ♩ work! ☺ Your garden gloves
; ♩ are by the mulch pile.

> --- {.baz}
> This is a blockquote (not a
> div), but with class="baz".

┆ --- {}
┆ This is an empty side-marked div,
┆ for times when you really need it.
┆ Incidentally, this side-mark character
┆ is amazing. Unicode unicorn unicode
┆ unicorn unicorn unicode.

Bye.

That is, you get to choose your own side-mark character by having the first line of the block be your side-mark character, followed by three or more hyphens/dashes, plus {...} (or just {} for an empty div).

And a pretty good-looking delimited/fenced/surround syntax follows naturally from that:

Hi.

; --- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---

Though, I think that looks better with more hyphens:

; --------------------------------------------- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---------------------------------------------

Benefits of this solution:

Everyone gets to use whatever side-mark character they want. Yay!
The side-marking syntax is pretty symmetrical with the delimited syntax.
The little div headings actually add some readability (headings work).
Delimited syntax only adds one leading character, and then lets you use dashes, which look great. Yay!
Looks good. Feels like good style.

uvtc on 29 Oct 2016

👍3

On the one hand I get where you're coming from @uvtc. Some of the examples you show do look really good. On the other hand I'm not sure you're solving the right problem.

Everyone gets to use whatever side-mark character they want.

This is probably not actually a benefit. Sure it might make some people happy getting to use the delimiters of their choice, in the long run that might not be best for the Markdown ecosystem. If we ever hope the block syntax Pandoc uses will be adopted by other parsers, we have to keep it from getting out of hand.

Pandoc's Haskell based parser wouldn't have too much trouble implementing this syntax, but I can think of other Markdown parses that would have conniptions trying to parse your suggested formats. Likewise syntax highlighting in editors would be complicated to build and, even in the editors that were able to support it, would incur significantly more overhead in doing so than some of the simpler solutions using per-arranged delimiters.

alerque on 29 Oct 2016

@uvtc I like the idea quite a lot. (Side note: long ago, pandoc used to support that emacs-style of quoting as an alternative blockquote syntax!)

@aleque It's reasonable to worry about whether this would be able to catch on more widely, since we want to avoid further fragmentation. But I don't think any Markdown implementation that uses a real parser (as opposed to just doing a bunch of regex substitutions) would have trouble with the proposed syntax. For example, it would be no straightforward to handle it in commonmark.js (JavaScript) or cmark (C). There are still a bunch of implementations that just do regex substitutions, but I'm not particularly inclined to make accommodations to them.

The point about syntax highlighting is worth considering. But Markdown is already a nightmare in that department (particularly with things like laziness in block quotes).

It would be interesting to raise this on talk.commonmark.org on one of the threads about generic div syntax, to see what kind of reactions it gets.

jgm on 29 Oct 2016

I like @uvtc's example. But I agree with @alerque that the freedom to choose the character might hurt. I'm from a different perspective though: learning curve. I think in order for a syntax to be easy to learn, there shouldn't be too much different choices for the same outcome — one more other way to do it might just confuse the beginners. Sometimes for different reasons (e.g. historical: * vs. - vs. _ in different context; ATX vs. setext), it might be necessary. But in this case, the only benefit of this arbitrariness is to accelerate the time we need to settle for a syntax, i.e. short term benifit. In the long run, I think it actually hurts for the said reason.

Regarding talk.commonmark.org, should someone, or did someone already, communicate over there?

edit: github markdown sanitized the link...

ickc on 29 Oct 2016

👍1

@uvtc: while I like the idea your examples show that the practice would be
way too hairy. I think it violates the _publishable as is_ principle, since
a casual reader would be bewildered rather than informed.

I really hope that the >--- ---< syntax isn't off the table already,
since it solves what is really my greatest worry, namely nesting. With this
syntax it is immediately clear that each >--- opens a new division and
each <--- closes the most recently opened division, so it won't be
necessary to count characters when eyeballing a document.

I don't worry about the arrow semantics. They may mean "stand out" rater
than "indent", and a div is intended to stand out one way or another.

Also while I'm not enthusiastic about the idea to overload blockquote
syntax it is better than nothing. The consideration that it degrades
gracefully is weighty.
You still see that this part stands out in some way.
(Incidentally I prefer <em class="small-caps"> to using <span> for the
very same reason, even though it means I have to kill italicization in CSS.)

Den 29 okt 2016 08:35 skrev "ickc" [email protected]:

I like @uvtc https://github.com/uvtc's example. But I agree with @alerque
https://github.com/alerque that the freedom to choose the character might
hurt. I'm from a different perspective though: learning curve. I think in
order for a syntax to be easy to learn, there shouldn't be too much
different choices for the same outcome — one more other way to do it might
just confuse the beginners. Sometimes for different reasons (e.g.
historical: * vs. - vs. _ in different context; ATX vs. setext), it might
be necessary. But in this case, the only benefit of this arbitrariness is
to accelerate the time we need to settle for a syntax, i.e. short term
benifit. In the long run, I think it actually hurts for the said reason.

Regarding , should someone, or did someone already, communicate over there?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/jgm/pandoc/issues/168#issuecomment-257074615, or mute
the thread
https://github.com/notifications/unsubscribe-auth/ABG3UzfRf9KWg1sg1o0Z9xeqAxOGjSv0ks5q4uk1gaJpZM4AOGXV
.

bpj on 29 Oct 2016

I don't really get the concern about providing lots of ways to do a custom div. First, Markdown already provides lots of ways to do many things: lots of characters to use for list items or hrules, two different styles of headings, several different ways to make links, two different characters to use for emph and strong, two ways to make code blocks. You may think these were bad design decisions, too, but they haven't hindered Markdown from catching on.

Second, although many characters are allowed on @uvtc's proposal, the _rule_ itself is extremely simple. The rule says you can use _any_ character. That's quite easy to remember. It's no harder to remember than, say, the rule that you can only use :.

I don't think the point of allowing many different characters was to make it easier to come to agreement about a syntax. As I understood it, @uvtc's idea was that an author might visual want different sorts of characters in order to make different sorts of sections stand out in distinctive ways. This is clearest in the example using musical notes, but think also of using ! for warnings.

Allowing any character, though, does slightly decrease expressive options with other block types. E.g. if we allow #, then

# --- {.class #id}

would count as a div rather than a heading with an attribute and a single em dash as its contents. It's a bit hard to imagine cases where you'd want such a heading, but if we go this way we need to be aware of this consequence.

jgm on 29 Oct 2016

Another point about @uvtc's suggestion worth discussing is

> --- {.baz}
> This is a blockquote (not a
> div), but with class="baz".

I can see it reconciles the need of setting classes on blockquotes. But it breaks the rule of "any character". (And it also breaks the possibility of using blockquote syntax as div for markdown editor compatibility.)

I suggest if we use @uvtc's syntax, the blockquote attributes should be done in other way:

As suggested previously:

> {.great}
> Quote of
> the day.

Or, using another character suggested by @uvtc in the illustration:

> +++ {.great}
> Quote of
> the day.

Or, to emphasize it is a quote:

>>> {.great}
> Quote of
> the day.

Another minor point is, the spaces there should be optional, just like the current blockquote does, right?

ickc on 29 Oct 2016

I meditated on the syntaxes suggested by @uvtc, focusing on how unifying the side-marking and surround-marking syntax is, and how it should handle nested surround-marking:

Variation 1: Same as the nested side-marking example used by @uvtc, except side-marks are gone and additional closing surround-marks. The disavantage is when the outer nest is removed, each of the inner nest has to be modified.

; --- {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; | --- {.bar}
Commodo consequat. Duis aute irure dolor in reprehenderit
in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa
qui officia deserunt mollit anim id est laborum.
; | ---
; ♩ --- {.music}
A little bird told me that
many hands make light
work! ☺ Your garden gloves
are by the mulch pile.
; ♩ ---
; ---

Variation 1': same as variation 1, when same character is used. This shows the advantage of visually cleaner nesting (comparing to 2'):

;--- {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
;;--- {.bar}
Commodo consequat. Duis aute irure dolor in reprehenderit
in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa
qui officia deserunt mollit anim id est laborum.
;;---
;;--- {.music}
A little bird told me that
many hands make light
work! ☺ Your garden gloves
are by the mulch pile.
;;---
;---

Variation 2: This one simplifies the example above, and uses the benefits of "all characters allowed" to use a different character for a different nest. It is still visually clear, while solves the problem when removing the outer nest:

; --- {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
| --- {.bar}
Commodo consequat. Duis aute irure dolor in reprehenderit
in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa
qui officia deserunt mollit anim id est laborum.
| ---
♩ --- {.music}
A little bird told me that
many hands make light
work! ☺ Your garden gloves
are by the mulch pile.
♩ ---
; ---

Variation 2': same as variation 2, when same character is used. Just like HTML div, visually difficult to see the nesting:

;--- {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
;--- {.bar}
Commodo consequat. Duis aute irure dolor in reprehenderit
in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa
qui officia deserunt mollit anim id est laborum.
;---
;--- {.music}
A little bird told me that
many hands make light
work! ☺ Your garden gloves
are by the mulch pile.
;---
;---

If only 1 variation is to pick, variation 2 seems best to balance between the ease of typing and the visual clues: each _deeper_ nest requires a different character ((non-)exception is when it is _not_ a deeper nest, that one closed before another open).

As a side note, another way of taking advantage of "any characters allowed" is to use incremental numbers/letters, kind of like using enumerated list (where the no. sequence can be arbitrary in the source).

ickc on 30 Oct 2016

Regarding using "> --- {.foo}" to style blockquotes, @ickc wrote:

I can see it reconciles the need of setting classes on blockquotes. But it breaks the rule of "any character".

Ah. Good point ickc.

When an author writes

> The sausages are
> in the basement.

they expect they're getting a blockquote. If they were to later style that:

> --- {.spooky}
> The sausages are
> in the basement.

it should not change the blockquote to a div. Same with lineblocks.

So, I think a choice would have to be made:

Option 1: Special-case the native Pandoc-markdown side-marking syntaxes (> and |). Any other character gets you a div. Unfortunately though, this means that if in the future Pandoc supported a _new_ native side-marker, for example,

! This is a possible
! future-pandoc
! image block.

^ This is a possible
^ future-pandoc
^ metadata block!

$ This is a possible
$ future-pandoc
$ video-pod (wha?) block.

etc.

then Pandoc would have to special-case those as well, breaking any docs that had used those characters to side-mark their divs.

Option 2: Forget the idea of using _any_ side-marking character and just use semicolons:

Hi.

; --- {.info}
; Tea is now available in
; the dining car. Please sip
; quietly.

; --- {.danger}
; The management strongly
; suggests you not order the
; seafood platter this evening.

; --- {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; sed do eiusmod tempor incididunt ut labore et dolore
; magna aliqua. Ut enim ad minim veniam, quis nostrud
; exercitation ullamco laboris nisi ut aliquip ex ea.
;
; ; --- {.bar}
; ; Commodo consequat. Duis aute irure dolor in reprehenderit
; ; in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
; ; Excepteur sint occaecat cupidatat non proident, sunt in culpa
; ; qui officia deserunt mollit anim id est laborum.
;
; ; --- {.music}
; ; A little bird told me that
; ; many hands make light
; ; work! ☺ Your garden gloves
; ; are by the mulch pile.

> --- {.baz}
> This is a blockquote (not a
> div), but with class="baz".

; This is an empty side-marked div,
; for times when you really need it.

; --- {.info}
Delimited style. Lorem ipsum dolor sit amet, consectetur
adipiscing elit, sed do eiusmod tempor incididunt ut
labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip
ex ea.
; ---

Bye.

uvtc on 30 Oct 2016

it should not change the blockquote to a div. Same with lineblocks.

Why not use a different character for --- for blockquote/lineblock attributes?

e.g. (almost all examples copied from @uvtc):

> +++ {.center}
> The sausages are
> in the basement.

| +++ {.some-class foo="bar" .lineblock}
| another block, but
| with a class, some attrib,
| and it's also a line block

! +++ {.awesome}
! This is a possible
! future-pandoc
! image block.

^ +++ {.stream}
^ This is a possible
^ future-pandoc
^ metadata block!

$ +++ {.uhd}
$ This is a possible
$ future-pandoc
$ video-pod (wha?) block.

ickc on 31 Oct 2016

@ickc , I don't think you can use the +++, as it's already commonly used in headers of email replies. Though, I may be getting confused here --- I think you're suggesting +++ to try and sidestep the problem of what to do with > --- {.foo}, but this may be getting too complicated; that should be a styled blockquote --- if you want a styled div around the blockquote, just wrap it:

; --- {.foo}
; > Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; > sed do eiusmod tempor incididunt ut labore et dolore
; > magna aliqua. Ut enim ad minim veniam, quis nostrud
; > exercitation ullamco laboris nisi ut aliquip ex ea commodo
; > consequat.

@bpj , I think that the issues with >--- ---< delimited markers are:

they look too much like markup,
they're easy to get wrong (ex, ---> <---, <--- --->),
they _would_ be symmetrical with > if Pandoc were overloading > for divs, but that I think is the wrong way to go (as discussed above),
they break consistency with how Pandoc-markdown already only uses matching delimiter markers, and
stylistically, I think they won't catch on. This is just my subjective opinion, but I think it's a little too decorative to catch on. The syntax that works (and, IMO, that people will use) will be just enough to get the point across, but no more.

* * *

I don't see the problem with delimited style and nesting. Can't the parser just see the closing ; ------- and then go look for the nearest unclosed ; ------- {.foo}?

; --- {.outer}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
; --- {.inner}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
; --- (this closes .inner)
; --- (this closes .outer)

* * *

Incidentally, for the special case of line blocks in html, since there's no "<lineblock>" tag, I suspect it would make sense for:

| --- {.foo}
| 1060 West Addison
| Chicago, IL

to result in the regular html paragraph output simply wrapped in a div with class="foo".

* * *

Another minor thing I noticed about using fun side-marking characters, is that it may add some needless redundancy:

! --- {.warning}
! Wait, you don't need to
! use exclamation marks,
! I already see the word
! "warning" in the header!

uvtc on 31 Oct 2016

Strongly agree that +++ cannot be used for divs. OTOH, it could be very useful for extensions of block quotes, but that's a topic for a separate thread.
Also strongly agree with @uvtc in that >--- ---< won't catch on.
For side markings, pipes and semi-colons work, and of those pipes seem to be way easier to read:

Without a header:

| 1060 West Addison
| Chicago, IL

With a header (we don't really need --- there):

| {.address}
| 1060 West Addison
| Chicago, IL

For delimited markers:

:::
1060 West Addison
Chicago, IL
:::

With a header:

::: address
1060 West Addison
Chicago, IL
:::

As well as single-liners (very useful in filters) :

::: address :::

Or

::: {.address} :::

In summary...

I propose we use pipes | for side markers and colons ::: for delimited markers.

sergiocorreia on 31 Oct 2016

@jgm wrote:

It would be interesting to raise this on talk.commonmark.org on one
of the threads about generic div syntax, to see what kind of reactions it gets.

Ok. Hope I wasn't too brash, but it looked like discussion on this went in many directions and has been dormant for a while, so I went and created a new thread at talk.commonmark.org: https://talk.commonmark.org/t/div-block-syntax/2283

@sergiocorreia , as (I think) he indicated above-thread, @jgm doesn't seem interested in breaking backcompat and repurposing pipes "|" for use in a div syntax.

Also, I disagree with you on the need for "---" in the div header, as I think it adds the necessary indication that you're looking at a header of some sort, rather than some content that the writer inexplicably decided to put into curlies.

Regarding using ":::" for delimiters, I think that idea has been proposed but didn't get much traction. Personally, I don't think it looks great as a delimeter.

uvtc on 31 Oct 2016

@uvtc

I don't see the problem with delimited style and nesting. Can't the parser just see the closing ; ------- and then go look for the nearest unclosed ; ------- {.foo}?

; --- {.outer}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
; --- {.inner}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
; --- (this closes .inner)
; --- (this closes .outer)

Yup, that why I said,

Just like HTML div, _visually_ difficult to see the nesting:

The 4 different variations up there each has different nuances.

Personally, taking advantage of the "any characters allowed", variation 2 looks best.

After looking at your example, I can see may be there's no need to make the blockquote supporting attribute:

> --- {.foo}
> > Lorem ipsum dolor sit amet, consectetur adipiscing elit,
> > sed do eiusmod tempor incididunt ut labore et dolore
> > magna aliqua. Ut enim ad minim veniam, quis nostrud
> > exercitation ullamco laboris nisi ut aliquip ex ea commodo
> > consequat.

Using the "any characters allowed" rule, the 1st nest is a div. Then the 2nd nest is a blockquote. One small problem is now a "blockquote with attributes" looks visually like a 2nd level blockquote.

I initially wasn't a big fan of "any characters allowed". But after reading the supporting argument around it, and trying to play around with it, I now think that it is too useful to give up, especially in the variation 2 above. By the way, variation 2 is not a must, variation 2' permit variation 2, where variation 2' is exactly the one in my quote of yours above.

Edit: when I say "variation 2 is not a must", it means "_requiring_ each of the inner nest use a different character is not a must". As long as "any characters allowed", variation 2' implies variation 2.

ickc on 31 Oct 2016

Re:

> --- {.foo}
> > Lorem ipsum dolor sit amet, consectetur adipiscing elit,
> > sed do eiusmod tempor incididunt ut labore et dolore
> > magna aliqua. Ut enim ad minim veniam, quis nostrud
> > exercitation ullamco laboris nisi ut aliquip ex ea commodo
> > consequat.

Using the "any characters allowed" rule, the 1st nest is a div. Then the 2nd nest is a blockquote.

Yow! Part of what makes Markdown so good is that things look like what they are. ">" looks like blockquote/indent. If you had one of the above >'s mean a blockquote, but the other a div, then I think that would be inconsistent and a mistake.

I think my previous suggestion to use _any_ character was wrong. Well intentioned though! Since I thought how wonderful it would be to use bangs for warnings/cautions. Or how great those vertical triple-dash unicode characters would look! {Sigh.} But I was too greedy. The drawbacks are too much. It would eat up all those characters that you may later want to use for other kinds of blocks, and it would cause too much confusion with the existing side-marked blocks (see prev paragraph). And besides that, I think it would make delimited blocks look just a bit too arbitrary (ex.: "why does this one have '; ---' delimiters, but others use '| ---', '+ ---', etc.?").

uvtc on 31 Oct 2016

One possible way to look at this, is that we’re looking for a generic block syntax. I know we didn’t want to complicate this div-syntax discussion even further, but arguably a div is nothing more and nothing less than a _generic block container_, so please bear with me.

From MDN:

The HTML <div> element (or HTML Document Division Element) is the generic container for flow content, which does not inherently represent anything.

From this perspective, we’re looking for a syntax to possibly _represent anything_. But depending on the class set in the attribute block, or depending on which marker is used, the block is then converted to either a HTML div element, a blockquote, an aside, address or any other HTML5 element etc. Whether this conversion is done by pandoc itself or a custom filter is secondary from the point of view of the markdown syntax.

That's why I like @uvtc's proposal; you can choose whatever marker you feel like suits your specific block. While you might still want to add a class to make things more explicit, filters could also match on the marker.

If the attribute block were required, the triple dashes probably wouldn't be necessary, and no clashes with definition lists. So this:

! {.warning}
! Toast is very hot.
! Handle with care.

could be converted to the pandoc AST analog of:

<div class="warning" marker="!">
  Toast is very hot. Handle with care.
</div>

The equivalent in surround-marking (here three or more markers would be required):

!!! {.warning}
Toast is very hot.
Handle with care.
!!!

I also think we should require the space after the marker – to reduce clashes (e.g. with the image syntax) and because it looks better. Maybe the requirement for the marker should be any non-alphanumeric character, also excluding the list markers (-, *, +) and # to avoid clashes with headings. There could also be a short list of preferred markers that syntax highlighters could implement, e.g. !, ;, : and |

The existing blockquote syntax and pandoc's line block syntax would be just special cases of this more generic side-marking syntax, while fenced code blocks would be a special case of the surround-marking variant of this syntax – with the historical quirks of not requiring the attributes and having the spaces following the marker be optional.

That these special markers are converted by the pandoc markdown reader to special elements (blockquote, line block and code block) instead of a generic div should only concern the more advanced users that write filters or CSS that matches on specific classes. For the text authors, that only use existing filters or that are following markdown style guides for specific projects, this should all be very natural.

And yes, in pandoc, using the pipe marker would possibly have the additional (handy) quirk of preserving linebreaks.

| {.address}
| John Doe
| 200 Main St.
| Berkeley, CA 94718

For surround-marking, there's also the following possibility: you could leave out the attributes, if you instead write a single word which would represent the classname:

!!! warning
Toast is very hot.
Handle with care.
!!!

which we incidentally already know from fenced code blocks:

``````

x = 42;

``````

To reduce the probability for clashes, we could always increase the minimum number of markers, which looks nicer anyway:

♩♩♩♩♩♩♩♩♩♩♩ music
A little bird told me that...
many hands make light
work! ☺ Your garden gloves
are by the mulch pile.
♩♩♩♩♩♩♩♩♩♩♩

mb21 on 1 Nov 2016

👍3

@mb21 writes:

There could also be a short list of preferred markers that syntax highlighters could implement, e.g. !, ;, : and |

Ah, yes. As has been pointed out, markdown already has two separate ways to do italics (* and _), two separate ways to do bold, a few different unordered list markers, etc. Allowing for a couple of different ways to do divs:

; --- {.outer}
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam.
;
; ! --- {.inner}
; ! quis nostrud exercitation ullamco laboris nisi ut
; ! aliquip ex ea commodo consequat. Duis aute irure
; ! dolor in reprehenderit in voluptate velit esse cillum
; ! dolore eu fugiat nulla pariatur. Excepteur sint.
;
; occaecat cupidatat non proident, sunt in culpa qui
; officia deserunt mollit anim id est laborum.

would make it easier on the eyes when you've got nested divs, and also to give you prettier "caution/warning" divs:

! --- {.warning}
! Multiple div side-markers
! ahead. Keep your hands
! on the keyboard at all times.

The core reasons for my ; --- proposal though are:

you get to use mostly dashes for delims, which looks good (better than rows of colons or bangs)
you get to use that taller/vertical leading side-mark character for side-marking, which looks good
you get a "header", which IMO actually adds readability and ... looks good. :)

Also, it may also yield a handy shorthand; for when simply adding a "{.class}", make the curlies and the dot optional:

! --- warning
! Multiple div side-markers
! ahead. Keep your hands
! on the keyboard at all times.

uvtc on 1 Nov 2016

In a reply on talk.commonmark.org, zzzzBov wrote the syntax using trailing dashes in the header, like:

! --------- warning ---------
! Multiple div side-markers
! ahead. Keep your hands
! on the keyboard at all times.

Allowing optional trailing dashes in the header seems quite natural, and looks great. (And it's also similar to how you can use the trailing # marks in ATX headers.)

uvtc on 1 Nov 2016

With a header (we don't really need --- there):

| {.address}
| 1060 West Addison
| Chicago, IL

...until the day line blocks can have attributes.

bpj on 1 Nov 2016

With a header (we don't really need --- there):

I think the --- has several nice functions:

It sets the block off visually and helps keep the
attributes from running into the rest visually.
It distinguishes the beginning of the block from the end,
which is particularly important in the surround style,
since distinct beginning and ends allow nesting.
It helps remove ambiguities -- e.g., if colons are used,
we could use the --- to distinguish divs from definition
list definitions. This is less of an issue if we limit
it to semicolons.

jgm on 1 Nov 2016

Agreed, the --- has some nice qualities. However, I still think it's not strictly necessary. Nesting with surround-marking could also be done by different length markers:

::::::::::::::::::::::::::::::::::::: {.info}

!!!!!!! {.warning}
Multiple div side-markers
ahead. Keep hands off.
!!!!!!!

:::::::::::::::::::::::::::::::::::::::::::::

and ambiguities could also be resolved by requiring the attributes.

Stylistically, initially mostly the surround-marking bothered me. What does the seemingly lost semicolon do there all on its own?

; --------------------------------------------- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---------------------------------------------

However, I realized that I took issue mostly with the semicolon, not the dashes. This looks good to me:

: --------------------------------------------- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
: ---------------------------------------------

and this as well:

+ --------------------------------------------- {.info}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
+ ---------------------------------------------

So, that leaves me neutral towards the ---. All else being equal, I think simpler is better which would favour leaving the dashes out. But it does indeed have a few redeeming qualities.

With a header (we don't really need --- there):

| {.address}
| 1060 West Addison
| Chicago, IL
...until the day line blocks can have attributes.

from the perspective of what I described in my post above, this would be rendered by pandoc as the following (note the <br>):

<div class="address">
  <p>1060 West Addison<br />
  Chicago, IL</p>
</div>

More interestingly:

> {.aside}
> my quote goes here

would be rendered as:

<div class="aside">
  my quote goes here
</div>

until one day the pandoc AST supports attributes on blockquotes, and then the rendering would switch to:

<blockquote class="aside">
  my quote goes here
</blockquote>

I think as long as we communicate this cleary, so people can plan ahead, it's kind of natural. Basically we're saying: this is actually a blockquote but currently the AST doesn't support this so we use a generic div instead, so that you can use CSS and filters to do with it what you want.

Using the syntax:

> --- {.aside}
> my quote goes here

would make this a div forever, while still being very confusing to read as it _looks_ like a blockquote. But yeah, maybe that should just be legal (to have the simple rule of "any character" goes), while being discouraged as confusing.

mb21 on 2 Nov 2016

I'm not being _entirely_ facetious here, but

<div>
div text in here
</div>

seems pretty simple and if the div tags are on their own lines, relatively unobtrusive. nesting and attributes are easy too. not a completist solution I agree, and it leaves even a hardened cynic such as myself with a nagging feeling that the world ought to be a better place...

njamescouk on 2 Nov 2016

TL;DR

My summary on the discussions recently:

surround-marking div: no obvious winner, and many proposals depends on the exact side-marking div
side-marking div potential winners:
1. overloading block-quote syntax
2. "any characters allowed" + ---{} header syntax
big question: what to do when existing (block-quote/line-block-)side-markings collides with the proposed div-side-marking?
- technically, it is ok for div-side-marking to collide with block-quote/line-block-side-marking, a few solutions has been proposed (utilizing the header-row)
- so it basically comes dome to aesthetic preferences
poll

Elaboration

The discussions around surround-marking has no obvious winners, and many proposals are imitating the side-marking. So it seems the choices around surround-marking would becomes more obvious after we settled for a side-marking.

Then there's 2 major new proposals that got some traction: overloading block-quote, and the any-characters-allowed syntax. Both of them share the same problem that a side-marked div can looks like a block-quote (/line-block).

So I think it is quite important to know the consensus on the question of if we want them collide or not.

Poll

I don't know if you guys like to have a quick poll. I'm going to proposed one here, by overloading the emoji reaction on the top-right corner of this block.

:Laugh: Yes, allow the div-side-markers to collide with the block-quote/line-block side-markers
:Hooray: No, do not allow the div-side-markers to collide with the block-quote/line-block side-markers
:Confused: collide or not, it is fine with me
:Heart: it depends on the exact syntax

ickc on 2 Nov 2016

❤3 😄3 😕1

jgm mentioned in the commonmark thread that the div syntax should be a general block container syntax. In that case, I'll reproduce here what I posted there (if only for my little poem in the lineblock at the end!).

* * *

Most-general syntax, here specifying a div (here with class="foo"):

; --- div {.foo}
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

without any styling:

; --- div
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

though, you wouldn't write that that way, since you could instead just do:

; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

Leaving out the block-type (and only supplying the styling) defaults to giving you a div:

; --- {.foo}
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

An html5 <aside> block, with class="foo" and an extra helping of those handsome dashes:

; ------------ aside {.foo} --------------
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

and here with no styling:

; --------------- aside ------------------
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

Blockquotes:

; --- blockquote {.foo} ---
; Lorem ipsum datsun pompom carfax ronco
; enzo corvette blowfish sockdrawer fob
; condor shoehorn pickle doorstop manwich.

That works, but you'd likely much rather just write that instead using "markdown-native" syntax (">"):

> --- {.foo} ---
> Lorem ipsum datsun pompom carfax ronco
> enzo corvette blowfish sockdrawer fob
> condor shoehorn pickle doorstop manwich.

> Of course, blockquote
> with no styling.

Lineblocks --- there's no _general_ block syntax because there's no actual <lineblock> tag, but we've still got the specific "|" syntax:

| --- {.foo} ---
| Lorem ipsum datsun carfax
| ronco enzo corvette lomax

| And, of course, line
| block with no styling.

You'd be giving up the shorthand syntax (where you could drop the curlies and the dot and write ; --- warning instead of ; --- {.warning}), but I think that's probably reasonable, since it's not that much of an extra readability cost to pay (and noting that divs simply aren't going to be as seamless as blockquotes, code blocks, and line blocks, which have their own native syntax and which are used all the time).

uvtc on 3 Nov 2016

@uvtc While I can see the usecase for --- aside generating a HTML <aside> element, I'm not sure how this would be best represented in the pandoc AST, since we only have a div there. Also: wanting to specify the class is at least as common. And what do you do with things like warning that have no corresponding HTML element? So I suggest leaving the shorthand syntax for classnames on divs. You can always use filters to transform <div class="aside"> to a HTML aside element.

mb21 on 8 Nov 2016

👍1

It's been previously suggested that ">" _could_ be overloaded for use as a generic block syntax, but that's problematic since > looks like "indent this to the right", and has meant blockquote since time immemorial.

If overloading an existing side-marker is on the table, this would work very well:

| --- {.foo #bar baz="moo"}
| One general block syntax to rule them all.
| Lorem ipsum dolor sit amet, consectetur a
| adipiscing elit, sed do eiusmod tempor et
| incididunt ut labore et dolore magna alums
| Ut enim ad minim veniam, quis nostrud ex.

|------------ foo ------------
| Shorthand for the simple case
| of `| --- {.foo}`. Extra dashes
| on either side are allowed. And
| you can omit the leading space
| if you like.

|-----
| Block with no particular styling
| (for html output, this would get
| you a plain div).

And of course,

| Unadorned, this still
| gets you a regular line
| block.

Delimited would be:

|------------------------------------------ {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip
ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore
eu fugiat nulla pariatur. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.
|------------------------------------------------

As @jgm had pointed out, with a generic block syntax, the renderer would figure out how to render |---{.foobar} depending on what's available in that output format (eg, for html, if there's a "foobar" tag, you'd get <foobar>, otherwise you'd get <div class="foobar">).

uvtc on 8 Nov 2016

👍1

I see... indeed, looks like a good idea that the HTML writer could render <div class="foobar"> as <foobar> if there's a foobar HTML element...

mb21 on 16 Nov 2016

I'm still pondering the best implementation of @uvtc's any-charachter-goes-idea.

side-marking

For side-marking, I seems to me we have a choice to either go with something analogous to the existing blockquote syntax, with the difference that we'd have to require the space after the marker and require the attribute block to avoid ambiguities (with image syntax and definition lists respectively). The result is looks quite clean though:

! { .warning }
! Toast is very hot.
! Handle with care.

Or alternatively go with @uvtc's original idea with the triple dashes, which also opens up the variant where we can replace the attribute block with a word that represents the class name:

+ ----- aside ------
+ my quote goes here
+ and it continues

And maybe it really should be _any_ character (including alphanumerics):

A ----- aside ------
A my quote goes here
A and it continues

P ----- pull -----
P my pull quote
P goes here
P and it continues

surround-marking

While --- is a nice way to symbolize the opening of side-marked divs, where the side-marker forms this vertical line on the left, I'm still not quite convinced of the --- for surround-marking. Especially for shorter blocks and if there are are only three and not more dashes, I just don't like the visual clutter of the different markers that are neither forming a coherent horizontal or vertical line:

+ --- aside
my quote goes here
+ ---

Or as @uvtc put it:

I think it would make delimited blocks look just a bit too arbitrary (ex.: "why does this one have '; ---' delimiters, but others use '| ---', '+ ---', etc.?").

The following work much better for me:

+++ aside
my quote goes here
+++

:::::: aside ::::::
my quote goes here
:::::::::::::::::::

----- aside ------
my quote goes here
------------------

Edit: as @bpj pointed out, the --- clash with setext headers, and potentially with horizontal rulers, so we would have to restrict this syntax to a few known markers (e.g. +, :, ;).

The above syntax is analogous to fenced code blocks, with these two differences:

the trailing markers on the opening line are ignored
we'd probably still have to require either the classname or an attribute block to distinguish the opening from the closing markers, in order to allow nesting (although this could potentially be side-stepped by coming up with a rule about the line lengths).

I'm not certain whether this would be easy enough to parse, or too ambiguous. Maybe it's okay as long as we limit it to non-alphanumeric characters? Or in the end we could also limit it to five or so different markers, which isn't quite as versatile as allowing all, but still provides the visual cues when nesting.

But maybe using the (in my opinion slightly uglier) syntax with the --- is a fair price to pay for avoiding the minor troubles outlined above, and to be more consistent with the side-marking version. The syntax can be written nicely if the writer puts in the effort. As I said before, the following looks quite good to me as well:

: ----------------------- info -------------------------
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
: ------------------------------------------------------

mb21 on 16 Nov 2016

As @jgm had pointed out, with a generic block syntax, the renderer would figure out how to render |---{.foobar} depending on what's available in that output format (eg, for html, if there's a "foobar" tag, you'd get <foobar>, otherwise you'd get <div class="foobar">).

There is at least one output format where that would be problematic: LaTeX (of course! :-). Your template or some package it loads may define an environment foobar and the renderer would have no way of knowing whether that is the case. I guess that the renderer could simply assume that that is the case unless you say |---{.foobar .nolatex}, or conversely assume that it isn't the case unless you say |---{.foobar .latex}, but it must be kept in mind. Also how would the LaTeX renderer handle additional attributes? Should |---{.foobar .baz .quux biz="buz" tic="tac"} become \begin{foobar}[biz={buz}, tic={tac}]{baz}{quux} automatically? That seems a bit risky to me, as in: better leave it to filters to mogrify divs into something else.

bpj on 17 Nov 2016

👍1

@bpj agreed, I don't really see this affecting many other writers besides the HTML writer...

mb21 on 17 Nov 2016

Yeah, @mb21, regarding delimited syntax,

---------------- foo ------------------
Lorem ipsum dolor sit amet, consectetur
adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris
nisi ut aliquip ex ea comodo consequat.
---------------------------------------

does indeed look substantially better than

|--------------- foo ------------------
Lorem ipsum dolor sit amet, consectetur
adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris
nisi ut aliquip ex ea comodo consequat.
|--------------------------------------

In fact, I'd say that for delimited syntax, the former is probably optimal and would catch on right away. The latter (with the leading |) doesn't look as good (looks like affectation), though has symmetry with the side-marked syntax.

But as you commented, not sure how easy the former would be to parse, or how unambiguous it is. FWIW, to this human reader it looks pretty unambiguous. ;)

BTW, regarding the side-marked syntax, I think

| ---------------- foo ------------------
| Lorem ipsum dolor sit amet, consectetur
| adipiscing elit, sed do eiusmod tempor
| incididunt ut labore et dolore magna
| aliqua. Ut enim ad minim veniam, quis
| nostrud exercitation ullamco laboris
| nisi ut aliquip ex ea comodo consequat.

looks about as good as it gets, and would likewise catch on very quickly. It looks classic, just the right amount of syntax, and clearly looks like what it means.

| --- pro-tip
| Application of melted butter
| to warm popcorn may result in
| buttery enlightenment.

uvtc on 17 Nov 2016

@uvtc, as @jgm pointed out to me further up this thread the problem with ---- or === as delimiters is that they clash with setext headings:

----- foobar -----
Quam Beatae Omnis
-----------------

Vitae libero sit nam ut.
------------------------

Which is the end of the div and which is a level 2 heading? It's not even entirely unambiguous to a human, and don't come telling me that the length of the dashed lines should disambiguate! :-)

bpj on 18 Nov 2016

👍2

@bpj Ah, yes, right. In that case, as @mb21 notes, the : looks alright in delimited syntax. I'll bet if you allow both the | and the : characters to be used, the pipe will probably be most commonly be used for side-marking:

| --- foo ---
| Lorem ipsum dolor sit amet,
| consectetur adipiscing elit.
| sed do eiusmod tempor incidi
| ut labore et dolore magna.

: --- foo ---
: Lorem ipsum dolor sit amet,
: consectetur adipiscing elit.
: sed do eiusmod tempor incidi
: ut labore et dolore magna.

whereas the colon will probably see the most use with the delimited syntax:

|---------- foo ------------
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
sed do eiusmod tempor incidi
ut labore et dolore magna.
|---------------------------

:---------- foo ------------
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
sed do eiusmod tempor incidi
ut labore et dolore magna.
:---------------------------

uvtc on 18 Nov 2016

@uvtc's syntax strikes me as the most elegant and would also address issue #719:

; --- div {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam.

Although I, personally, wouldn't nest the side-mark version, it could resemble:

; --- div {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam.
;
; ; --- div {.foo}
; ; Lorem ipsum dolor sit amet, consectetur adipiscing
; ; elit, sed do eiusmod tempor incididunt ut labore et
; ; dolore magna aliqua. Ut enim ad minim veniam.

Limiting the side-mark to semi-colons seems like a future-proof approach. For consistency, a block might resemble:

; --- div {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam.
; ---

With nesting:

; --- div {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam.

; --- div {.bar}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam.
; ---

; ---

Reservations on other ideas from this topic:

I dislike the notion of using a different number of tokens for indenting -- I don't want to count (3 colons, 6 colons, etc.).
The "extra helping" of dashes seems superfluous and potentially confusing with header marks, and could clash with setext headings.
+++ was also part of +++ ATH0, for any old timers reading this.
Overloading existing side-markers will increase parsing complexity without strong justification.
This implies that colons should not be used, to avoid potential conflicts with definition lists.
I'd rather not type in multiple characters per blocked line (e.g., ||).
Emacs syntax isn't all that easy to remember; semi-colons, though, are simple.

DaveJarvis on 6 Jan 2017

👍2

As i need this i took a shot at implementing this issue as defined in https://github.com/jgm/pandoc/issues/168#issuecomment-270833294 .

First version that compiles (but was not tested) is in my fork in the issue168-branch: https://github.com/Drezil/pandoc/tree/issue168

That was just a fast hack in 4 hours .. don't expect too much. Also this is only the Reader, not the Writer as of yet.

To not clutter this issue here more than it should be you should open an issue in my fork and try to break it with some test-cases (that you would have to provide.. -.-).

When the change is stable i will open a pull-request to get this merged asap.

Drezil on 12 May 2017

Looks great; does it support class names and ids? ({.foo})

sergiocorreia on 12 May 2017

it should. At least i call attr' <- option nullAttr attributes ;)

Drezil on 12 May 2017

Implementation of this issue (as far as the reader is concerned) is now complete, afaik.

Pull-Request is open and ready to merge.
More discussions about the PR (coding-style, tests, ...) should be done in the PR itself ;)

Drezil on 15 May 2017

For clarity, what nested syntax was implemented? The one with side-marks:

; --- div {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing
;
; ; --- div {.foo}
; ; Lorem ipsum dolor sit amet, consectetur adipiscing

The one without:

; --- div {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing

; --- div {.bar}
Lorem ipsum dolor sit amet, consectetur adipiscing
; ---

; ---

Or both?

Also, does whitespace matter? That is, will the following nest:

; --- div {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing
; --- div {.bar}
Lorem ipsum dolor sit amet, consectetur adipiscing
; ---
; ---

Or, if side-marks were implemented:

; --- div {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing
; ; --- div {.foo}
; ; Lorem ipsum dolor sit amet, consectetur adipiscing

DaveJarvis on 15 May 2017

; --- div {.foo}
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam.
;
; ; --- div {.foo}
; ; Lorem ipsum dolor sit amet, consectetur adipiscing
; ; elit, sed do eiusmod tempor incididunt ut labore et
; ; dolore magna aliqua. Ut enim ad minim veniam.

will turn to

<div class="foo">
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
<div class="foo">
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.
</div>
</div>

(the empty line causes the paragraph, no empty line causes plain; as always)

and

; --- div {.foo}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam.

; --- div {.bar}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam.
; ---                                                                                                                                                                                                                                       

; ---

to

<div class="foo">                                                                                                                                                                                                                           
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>                                                                                 
<div class="bar">                                                                                                                                                                                                                           
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.                                                                                        
</div>                                                                                                                                                                                                                                      
</div>

p-tag again because of empty lines. if you leave them out you get plain.

Drezil on 16 May 2017

👍1

Tempted to support this form:

; --------------------------------------------- {.info #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---------------------------------------------

and allow this variant

; ----------- info ----------------------------- {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ----------------------------------------------

It would be required to specify some attributes (possibly just a class name, which could be done in the second way): this ensures that we can distinguish begin and end lines, since the end lines would lack attributes.

I'd say the space after the ; should be optional, and that at least three - characters are needed to separate the ; from any attribute specifier.

@mb21 has raised a concern about the aesthetics of the initial ;.
I think + is out; too many ambiguities with lists. : might work, but to my eye ; is a bit more attractive, and : is used for definition lisnts. In the end, it probably doesn't matter too much as we'll get used to any choice. Semicolon will never naturally occur at the beginning of a line, so that's good.

jgm on 20 Aug 2017

👍2

Variants tend to increase parsing complexity.

; --- {.info #ident}
...
; ---

CSS class selector syntax begins with a period, which could cause confusion by requiring that the element name use a period. Since the #symbol denotes a page anchor, it may be counter-intuitive to have the above document produce the following HTML fragment as the CSS selector is info.ident:

<info class="ident"><p>...</p></info>

Perhaps nobody will confuse HTML/CSS syntax with the proposed syntax, making it a non-issue--also, I don't know the internals of pandoc, so the proposed syntax could be easier to implement.

Would ConTeXt output resemble the following:

\startinfo[ident]
...
\stopinfo

DaveJarvis on 21 Aug 2017

@mb21 has raised a concern about the aesthetics of the initial ;.
I think + is out; too many ambiguities with lists. : might work, but to my eye ; is a bit more attractive

Beauty is in the eye of the beholder ;) I still don't really like the asymmetry in the semicolon and thus would favour the colon.

Or go with what was discussed on commonmark thread and implemented in markdown-it:

:::::::::::::::::::: info :::::::::::::::::::: {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Then again, eventually we'll have to choose one and not everyone will be completely happy either way. I would really like for a syntax to finally be adopted, thus I'm fine with the semicolon-based one as well.

mb21 on 21 Aug 2017

CSS class selector syntax begins with a period, which could cause confusion by requiring that the element name use a period.

I could be wrong @DaveJarvis, but I don't think @jgm's proposal here was to set elements at all, it was to set a class property on a <div> element. In that event the syntax suggested would be quite intuitive for CSS users. If some other transformation changed <div class="info"… into <info… that would be for a later step and unrelated to this block syntax.

If the proposal is to output arbitrary tags that's a bit different. Perhaps keywords _not_ prefixed by hash or dot? But it doesn't seem like that will generalize very well beyond export to HTML, XML, and TeX formats. I think sticking to attributed divs is the best way to get this going.

alerque on 21 Aug 2017

; --- {.info #ident}
...
; ---
CSS class selector syntax begins with a period, which could cause confusion by requiring that the element name use a period.

@DaveJarvis, I think this is intended. Compare it to the inline [span text]{.class #id}.

Would ConTeXt output resemble the following?

```
\startinfo[ident]
...
\stopinfo

Sorry, but how would you deal with that in the preamble?

\definestartstop[info]

ConTeXt deals with XML natively. I would be better to do the following:

\startbuffer[demo]
<doc>
    <div>
        <p>Lorem ipsum dolor sit amet, consectetur,</p>
        <p>sed do eiusmod tempor incididunt ut</p>
        <p>magna aliqua. Ut enim ad minim veniam</p>
    </div>
    <div class="info" id="ident">
        <p>Lorem ipsum dolor sit amet, consectetur,</p>
        <p>sed do eiusmod tempor incididunt ut</p>
        <p>magna aliqua. Ut enim ad minim veniam</p>
    </div>
    <div class="info">
        <p>Lorem ipsum dolor sit amet, consectetur,</p>
        <p>sed do eiusmod tempor incididunt ut</p>
        <p>magna aliqua. Ut enim ad minim veniam</p>
    </div>
</doc>
\stopbuffer

\startxmlsetups xml:initialize
     \xmlsetsetup{#1}{doc|p}{xml:*}
     \xmlsetsetup{#1}{div[not (@class or @id)]}{xml:pure:div}
     \xmlsetsetup{#1}{div[@class='info' and not @id]}{xml:div:info}
     \xmlsetsetup{#1}{div[@id='ident']}{xml:div:ident}
\stopxmlsetups

\xmlregistersetup{xml:initialize}

\startxmlsetups xml:doc
     \xmlflush{#1}
\stopxmlsetups

\startxmlsetups xml:pure:div
     \start\darkyellow\xmlflush{#1}\stop
\stopxmlsetups

\startxmlsetups xml:div:info
     \start\darkblue\xmlflush{#1}\stop
\stopxmlsetups

\startxmlsetups xml:div:ident
     \start\darkred\xmlflush{#1}\stop
\stopxmlsetups

\startxmlsetups xml:p
     \startpar\xmlflush{#1}\stoppar
\stopxmlsetups

\starttext
    \xmlprocessbuffer{main}{demo}{}
\stoptext

Being the output (something similar to):

info-ident-1

ousia on 21 Aug 2017

ConTeXt deals with XML natively. I would be better to do the following:

Imagine starting with .Rmd files (Markdown with R statements). These are read by an R processor to produce .md files. The .md files are then piped into Pandoc to produce .tex files. ConTeXt reads the .tex files to produce the final .pdf file.

Now imagine .Rxml files (XML with R statements). These are processed into .xml files, which are then transformed by XSLT to produce .md files that, once passed through Pandoc, can share the same preamble as the .Rmd files.

Even though ConTeXt can read XML, using Pandoc to generate native ConTeXt (.tex) documents is rather convenient. Producing custom ConTeXt environments, based on the Markdown syntax discussed in this thread, would be rather useful.

Sorry, but how would you deal with that in the preamble?

The preamble is defined independently of the output produced by Pandoc. For example:

\input preamble

\starttext
  \startfrontmatter
    \input cover

    \startstandardmakeup
      \input copyright
    \stopstandardmakeup
  \stopfrontmatter

  \startbodymatter
    \input body
  \stopbodymatter
\stoptext

Here, the \input body line reads in from Pandoc's ConTeXt output and the \input preamble imports the preamble.

DaveJarvis on 21 Aug 2017

Even though ConTeXt can read XML, using Pandoc to generate native ConTeXt (.tex) documents is rather convenient. Producing custom ConTeXt environments, based on the Markdown syntax discussed in this thread, would be rather useful.

I’m afraid that my experience with ConTeXt and pandoc tells me this would be a bad idea.

Divisions (as well as spans) as XML elements are generic containers. In my documents, divisions (<div> elements) are used to mark title, copyright, dedication and colophon pages. They mark text divisions, such as parts, chapters and sections, mainly. I also use them to add the signature date in forewords.

Generic containers may be defined by what each user needs. Defining blocks (environments are something different in ConTeXt) to translate text divisions from Markdown may be the wrong approach. Mainly because each user may have different needs.

Sorry, but how would you deal with that in the preamble?

The preamble is defined independently of the output produced by Pandoc.

I meant something different.

\starttext
\startinfo[ident]
This is only a sample.
\stopinfo
\stoptext

In the sample above, how can you compile only the text with ConTeXt?

I never had the need to do something like that, but I would like to know how to do it.

ousia on 21 Aug 2017

In the sample above, how can you compile only the text with ConTeXt?

There's no way ConTeXt can know the definition ahead of time. The output from Pandoc must be piped through another process to add definitions for the new environments using a \defineX macro. Defining environments is a well-known approach when using ConTeXt for paragraphs, measures, frames, enumerations, headings, and just about everything else.

Thus, the info environment could be defined as follows:

\defineparagraphs[info][n=3,before={\blank},after={\blank}] 

% The first column occupies 10% of the text's width and is rendered bold. 
\setupparagraphs[info][1][width=.1\textwidth,style=bold] 

% The second column occupies 40% of the text's width. 
\setupparagraphs[info][2][width=.4\textwidth]

It could also be defined as an indented list, emphasized text, a framed environment with a fancy border, a generated figure, etc. The definition must be parsed by ConTeXt prior to reading the sample document:

\input preamble % This line needs to be added by another process.

\starttext
\startinfo[ident]
This is only a sample.
\stopinfo
\stoptext

This retains separation of content from presentation. Additionally, it could be a parameter passed into Pandoc to indicate how the ConTeXt output should be generated when it encounters a div syntax. This isn't a case of "either XML or native ConTeXt." Software can do both with enough elbow grease.

Perhaps @adityam would care to chime in?

DaveJarvis on 21 Aug 2017

It is always tricky to think how the distinction between ids and classes carries over to other markup languages. With ConTeXt, I see two possibilities:

Map ; --- {.id #class} to \startid[class]. An example of this will be ; --- {.framed #topbar} which is then mapped to \startframed[topbar]. It is then up to the user to include a \defineframe[topbar] definition somewhere to affect its output. If the used id is a predefined environment, then this will work even if the class is not predefined (in most cases, I think).
Map ;--- {.id #class} to \startclass[setups=id]. An example will be {.myspacing #topbar} which is then mapped to \starttopbar[setups=myspacing] and it is then up to the user to define a topbar environment and a myspacing setups.

But no matter what approach one takes, if the objective is to make sure that no matter what ids and classes are used in div markers in the markdown document, the resulting ConTeXt document must always compile, then the only way to do that is for pandoc to keep track of the classes/id, and add appropriate \definestartstop or similar at the top of the preamble (and hope that the user redefines them to something sensible).

I agree with the statement that ousia made: when it gets to compiling complicated documents generated using pandoc (in ConTeXt), it is much simpler to ask pandoc to generate XML output and process that output using ConTeXt. (The pandoc input need not be XML. It can be markdown or anything else that pandoc can process).

adityam on 22 Aug 2017

I definitely agree with mb21,

:::::::::::::::::::: info :::::::::::::::::::: {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Looks much better, perhaps we could even skip the curly braces and have:

:::::::::::::::::::: info :: #ident :::::::::::::::
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Because I absolutely needed this feature in a project I'm working on, I implemented a pyparsing module in python that implements this syntax:

[[.className]](div)
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

It works really well and I'd be happy to commit that code as a filter, although I'm not sure how successful I'd be at implementing this into pandocs core. Any thoughts there?

Note, that div is optional here, and if it isn't specified, like:

[[.className]]
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

It will default to a div when exporting html. When exporting text, the innertext is kept, and everything else is removed.

saivan on 22 Aug 2017

But no matter what approach one takes, if the objective is to make sure that no matter what ids and classes are used in div markers in the markdown document, the resulting ConTeXt document must always compile,

While it compiles, the following example is missing \starttext and \stoptext from its output:

# Chapter 1

Testing.

> This is a quoted environment.

Testing.

pandoc -t context -i test.md -o test.tex using v1.16.0.2 generates:

\section[chapter-1]{Chapter 1}

Testing.

\startblockquote
This is a quoted environment.
\stopblockquote

Testing.

The blockquote contents are missing from the PDF file. This is a rabbit hole, though.

Generating a \definestartstop (or similar) that can be overridden makes sense. This will cause extra work in some cases and it would be convenient if the autogenerated definitions could be suppressed and deferred to a manual solution. To be concrete:

# Chapter 1

::: .info :: {#ident} ::
Informational text
:::

Then running pandoc -t context --suppress-defines -i test.md -o test.tex produces something like:

\starttext
\startchapter[title={Chapter 1}] % Or \chapter{Chapter 1}
\startinfo[ident]
Informational text
\stopinfo
\stopchapter % Not needed with \chapter{...}
\stoptext

Whereas running pandoc -t context -i test.md -o test.tex (the default) produces something like:

\definestartstop[info]

\starttext
\startchapter[title={Chapter 1}] % Or \chapter{Chapter 1}
\startinfo[ident]
Informational text
\stopinfo
\stopchapter % Not needed with \chapter{...}
\stoptext

That would be a flexible workflow, which would easily allow post-processing to create:

\input preamble

\starttext
\startchapter[title={Chapter 1}] % Or \chapter{Chapter 1}
\startinfo[ident]
Informational text
\stopinfo
\stopchapter % Not needed with \chapter{...}
\stoptext

Without this, it is not trivial to determine where to insert \input preamble to override the default start/stop environment for info.

DaveJarvis on 22 Aug 2017

First, to clear away a couple of confusions:

This is just supposed to be a syntax for creating the Div element in the pandoc AST. The question of how this element should be rendered in some output format (say, HTML or ConTeXt) is a separate one and shouldn't be discussed here, to avoid clutter. I do think it's important not to default to rendering it as \startfoo, since that will make the ConTeXt output broken without special definitions. But all of this can be discussed later.
In my proposal, the alternative form
```
; --- info --- {#foo}
```
is exactly equivalent to
```
; ------ {.info #foo}
```
info here is not the element name; it is simply a class. By default, this would render in HTML as <div id="foo" class="info">..., though of course one could interpose a filter that converted this into something else for a particular output format.

There remains the aesthetic issue:

; ----------- info ----------------------------- {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ----------------------------------------------

vs

:::::::::::::::::::: info :::::::::::::::::::: {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::

I go back and forth on this, but I tend to think the ---- works better as a separator; it calls attention to itself less than the bulky ::::.

@saivan suggests an interesting alternative; I don't know if it has been discussed above (I didn't reread all 222 comments), but it should be discussed. That is to use indentation to mark out the special block. (We already do this for block content inside footnotes and list items.) In a version closer to the conventions used in pandoc, this would be:

{.class #ident}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

    Another paragraph here.

Four spaces indent would be required, though we could allow "laziness" as with footnotes:

{.class #ident}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

    Another paragraph here.

This is clean and simple, and makes nesting very easy to see (at the cost of being a bit more difficult to type).

jgm on 22 Aug 2017

I go back and forth on this, but I tend to think the ---- works better as a separator; it calls attention to itself less than the bulky ::::.

With the minimal character sample, that would read:

; --- {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
; ---

vs

::: {#ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea.
:::

I think that using only one character is an interesting feature.

This is clean and simple, and makes nesting very easy to see (at the cost of being a bit more difficult to type).

On the indented proposal, I agree it is clear and simple.

The problem arises when you have to include elements that already use indentation inside (such as multi-paragraph footnotes and lists).

ousia on 22 Aug 2017

@saivan suggests an interesting alternative; I don't know if it has been discussed above (I didn't reread all 222 comments), but it should be discussed. That is to use indentation to mark out the special block. (We already do this for block content inside footnotes and list items.)

I don't think this is a good idea, as you change meaning of some parts (i.e. para) if you edit some "distant" part (i.e. removing the div-start-marker).

{.foo}
bar
[... long things...]
# more markdown

with special things
in it

and you delete the {.foo} then the whole thing will be interpreted as code and not parsed as markdown anymore (iirc).
With the other mentioned things (footnotes, bullet lists, ...) this is only a minor issue as these tend not to span long distances in the markdown-text itself - whereas with divs you almost always get a lot of marked up content inside those areas.

i can quickly adapt my PR to leave out the explicit "div" and support multiple "-" instead of exactly 3.

@jgm: do you have some code inside pandoc which parses partial attributes? I would like Attr to be a Monoid so i can just stack up Attrs while parsing the first line and mappend them.

As i was writing some filters this issue pops up a lot for me. But this is another issue i will open up seperately.

Drezil on 22 Aug 2017

@Drezil said:

I don't think this is a good idea, as you change meaning of some parts (i.e. para) if you edit some "distant" part (i.e. removing the div-start-marker).

I agree with this (in its entirety, not just the part I quoted.

As for the character in the left margin of the fence line, couldn't the syntax use pretty much any punctuation character other than - * + #, since what is most compactly expressed with the regex [[:punct:]]-{3,} will be distinctive enough whatever [[:punct:]] is. NB I'm not saying that the syntax should allow 'any' punctuation character, rather that there are several other choices than the semicolon to pick for the syntax. Personally I would prefer : with the mnemonic "something begins here" or ! with the mnemonic "this needs special attention". This said both ; and : are very close to '-' on my Swedish keyboard, so I don't think that ; would be a very bad choice for me personally, it's just the "medium break here" semantics that feels wrong somehow.

bpj on 22 Aug 2017

@saivan suggests {snip} to use indentation to mark out the special block. (We already do this for block content inside footnotes and list items.)

The indentation to indicate extra paragraphs in a list item, for example

~~~

this is a list item
with multiple lines

as well as
multiple paragraphs.

~~~

is distinct and readily discerned from the indentation for code blocks.

Two distinctive, well-known, and accepted syntax elements in markdown are (1) sidemarked > means blockquote and (2) sidemarked indent by 4 spaces means a code block. I think it would unreasonably compromise md syntax to introduce a specially-marked indented paragraph that means something other than a code block. And I think it wouldn't get any traction from users either.

I don't write any ReST, but I believe they have syntax where an indented paragraph is blockquote unless you end the previous paragraph with ::. This means whenever you see an indented paragraph in ReST, you need to look back to see whether it's a blockquote or a code block; it doesn't "look like what it is", which is an important quality of markdown syntax.

uvtc on 22 Aug 2017

@bpj I believe that allowing any character was suggested above by @uvtc (go back to Oct. 28 2016).

jgm on 22 Aug 2017

@bpj I believe that allowing any character was suggested above by @uvtc (go back to Oct. 28 2016).

@jgm I'm not suggesting that, I'm just suggesting that there are more options that would work because the "punctuation character followed by three or more hyphens" pattern would be distinctive enough almost no matter which the character before the hyphens is, so the choice of character need not be constrained by the characters considered for side marking earlier in this discussion when it is decided which that character is going to be. We/you have more options, but one specific character should be chosen.

bpj on 22 Aug 2017

Also regarding

~~~
{.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.

~~~

vs

~~~
; --- {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.
; ---
~~~

Note that the former is a form of side-marked syntax, while the latter is delimited.

@jgm suggesting ; --- {...} syntax was suggesting adding a delimited syntax for divs.

Recall that markdown sometimes offers both kinds of syntax (for example, code blocks may be side-marked (with 4 spaces), or else delimited by ~~~).

side-marked tends to be more work to write, but is generally agreed to be prettier and more readable, which is to say, it's more "markdownish". It also looks better than delimited when there's nesting.
delimited is easier to write (or generate), can be more convenient, but generally isn't as easy on the eyes.

So, if you're going to offer a side-marked syntax, it needs to look really good. :) Blockquotes and code blocks meet this requirement.

The suggested indentation-based div syntax is side-marked, but it has some issues. One of which is that it doesn't nest well:

~~~
{.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

{.other #foo}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

    {.more}
        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

~~~

Now, this doesn't look fabulous either:

~~~
; ------------------------------------- {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

; -------------------------------------- {.other #foo}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

; ------------------------------------------- {.more}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
; --------------------------------------------------

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
; ---------------------------------------------------

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
; ---------------------------------------------------
~~~

but the whole point of delimited syntax (as opposed to side-marked) is convenience for the writer (as opposed to readability).

If you want a more readable side-marked div syntax, I think I previously suggested (it's been a while!) side-marking with semicolons like so:

~
; ---------------------------------------- {.class #ident}
; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; sed do eiusmod tempor incididunt ut labore et dolore
;
; ; ---------------------------------------- {.other #foo}
; ; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; ; sed do eiusmod tempor incididunt ut labore et dolore
; ;
; ; ; ------------------------------------------- {.more}
; ; ; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; ; ; sed do eiusmod tempor incididunt ut labore et dolore
; ; ;
; ; ; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; ; ; sed do eiusmod tempor incididunt ut labore et dolore
; ;
; ; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; ; sed do eiusmod tempor incididunt ut labore et dolore
;
; Lorem ipsum dolor sit amet, consectetur adipiscing elit,
; sed do eiusmod tempor incididunt ut labore et dolore
~

but I understand that the delimited syntax is what's currently being considered.

uvtc on 22 Aug 2017

+++ John Gabriele [Aug 22 17 18:23 ]:

The suggested indentation-based div syntax is side-marked, but it has
some issues. One of which is that it doesn't nest well:

Why do you say that? You can see at a glance what belongs
to what level, unlike with the fenced syntax. And it looks
"cleaner" than the ; side-marked syntax.

{.class #ident}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

    {.other #foo}
        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

        {.more}
            Lorem ipsum dolor sit amet, consectetur adipiscing elit,
            sed do eiusmod tempor incididunt ut labore et dolore

            Lorem ipsum dolor sit amet, consectetur adipiscing elit,
            sed do eiusmod tempor incididunt ut labore et dolore

        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

jgm on 22 Aug 2017

You can see at a glance what belongs to what level, unlike with the fenced syntax.

True, but there might be an issue with very long divs. I sometimes get lost in my list item continuations/sublists and I think the risk of getting lost is greater here. The fenced syntax is probably safer in that regard.

bpj on 22 Aug 2017

The suggested indentation-based div syntax is side-marked, but it has
some issues. One of which is that it doesn't nest well:

Why do you say that? You can see at a glance {snip}

Because with the proposed indentation-based div, the content of the div is at a different indentation level than the "header". It looks like it zig-zags right and left as you go down the page. It reminds me of the GNU C coding standard:

~
if (x < foo (y, z))
haha = bar[4] + 5;
else
{
while (z)
{
haha += foo (z, z);
z--;
}
return ++x + bar ();
}
~

The only time in Markdown I expect to see the content indented from the "header" is with definition lists:

~~~
grey squirrel
: Gray and fuzzy, this creature
collects nuts in autumn.

Second paragraph of definition
of grey squirrel.

aardvark
: mumble mumble mumble
~~~

* * *

Compare

~~~
{.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

{.other #foo}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

    {.more}
        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

~~~

to

~~~
{.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

    {.other #foo}
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

        {.more}
        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

        Lorem ipsum dolor sit amet, consectetur adipiscing elit,
        sed do eiusmod tempor incididunt ut labore et dolore

    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

~~~

The former zigzags and I struggle to see to which heading a given paragraph refers. The latter is easy to read, but also coincides with code block syntax.

uvtc on 22 Aug 2017

Why do you say that? You can see at a glance what belongs to what level, unlike with the fenced syntax. And it looks "cleaner" than the ; side-marked syntax.

Yes:

In general, side-marked almost always indicates at a glance the writer's intent better than fenced/delimited anyway.
Side-marked with spaces (indented) looks very clean. Which is why it's one of the big three best ascii side-markers of all time: the >, the |, and the 4-space indent. :)
Side-marking with spaces looks better than side-marking with semicolons. Alas, yes (see previous point), but we're using side-marking spaces for code blocks. I think it would be a departure from Markdown philosophy to use them for anything else.

uvtc on 22 Aug 2017

+++ John Gabriele [Aug 22 17 13:53 ]:

The only time in Markdown I expect to see the content indented from the
"header" is with definition lists:

But really, with all lists (including standard bullet and
ordered lists), there are multiple possible levels of
nesting, and the nesting is marked by indentation, isn't it?
I don't see how this is different from regular list nesting.

jgm on 22 Aug 2017

But really, with all lists (including standard bullet and ordered lists), there are multiple possible levels of nesting, and the nesting is marked by indentation, isn't it?

Yes. That's one of the things I love about markdown lists. All list content (not the marker) is always indented by a multiple of 4 spaces. Looks beautiful on the screen.

I don't see how this is different from regular list nesting.

Hm. Not sure I understand what you mean, but this

~~~
{.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

~~~

definitely resembles a one-item definition list to me, which is different from a div.

Consider:

~~~
bread
: Baked fresh daily
in the oven.

Ovens can be hot.

{.bread}
Baked fresh daily
in the oven.

Ovens can be hot.

~~~

Those would both result in somewhat different output, even though they look almost the same in plain text.

Ok, I think I see what you mean though. Definition lists introduce a syntax element, which is a header line, a newline, then indented text (possibly with additional paragraphs, also indented). That's something new for markdown. The question then is, do you keep it special case only for definition lists, or do you generalize it to use for divs as well (and maybe other stuff too, in the future)?

For example:

~~~
||
lineblock
line two
line three

%%
This is a comment
paragraph.

And a second
comment paragraph.

{...}
I don't know what this
is for, but it's ... it's
for something.
~~~

uvtc on 23 Aug 2017

Oh, @jgm, sorry, I didn't answer your question, and I think I see what you mean now: you're saying that with nested lists you look at the content, not the marker, and so the content indentation beautifully shows the nesting level. Yes.

And here's a nested definition list:

~~~
red
: A reddish color.

green
: A greenish color, but with many varieties.

emerald
  : Looks like an emerald.

forest
  : the color of evergreens

    I could go on and on about
    forest green.

    Multiple paragraphs even!

linflast
  : possibly elvish?

blue
: see cyan
~~~

and here's something similar (3 divs in a row, with sub-divs) with the proposed indentation-based div syntax:

~~~
{red}
A reddish color.

{green}
A greenish color, but with many varieties.

{emerald}
    Looks like an emerald.

{forest}
    the color of evergreens

    I could go on and on about
    forest green.

    Multiple paragraphs even!

{linflast}
    possibly elvish?

{blue}
see cyan
~~~

uvtc on 23 Aug 2017

Side-marking with spaces looks better than side-marking with semicolons. Alas, yes (see previous point), but we're using side-marking spaces for code blocks. I think it would be a departure from Markdown philosophy to use them for anything else.

I don't see why. Yes, a block that starts indented and remains so is a code block. But we already have many constructs that have an unindented beginning and then use indentation to indicate the scope of their contents:

List items:

1.   This is a list item.

    And here is the second paragraph.

    > And a block quote contained under the same list item.

Footnotes:

[^mynote]:
    This is my footnote.  It can
    contain multiple paragraphs.

    But they must be indented.

Definitions in definition lists:

:    The definition goes here.

    And the second paragraph of the definition is indented.

The indented syntax for divs that is under discussion looks very similar to these:

{.class #id key=val}
    The contents go here.

    And if there are multiple paragraphs or other block-level content, it must be indented.

I did think of one objection to the proposed indented div syntax that concerns me more. If we ever did want to allow attributes to be added to arbitrary block-level constructions, the natural way to do it would be to put the attributes on a line before the block. With this syntax, though,

{.class}
    indented

would be an indented code block with the attributes.

jgm on 23 Aug 2017

My 2 cents about indentation:

Pros:

easy to edit on most text editors (a huge deal for me because even if there's a visually great side-marking syntax for div, I wouldn't use it if it is difficult to set up to work across different text editors. I guess this might be true to some other people too so the adoption rate depends on this.)
visually good, not distracting, and clear (less is more, comparing to any other side-marking)

Cons:

being a side-mark, it introduces a lot of diff. when a div is added (comparing to delimiter)
- counter-point to this is that it is possible to suppress white space diff. so this makes it the least troublesome side-marking
+1 on

If we ever did want to allow attributes to be added to arbitrary block-level constructions, the natural way to do it would be to put the attributes on a line before the block.

It seems to make this issue depending on the status of #684. Should #684 be resolved first then?

And I think this is suggested before: can we have both side-marking and delimiter (besides the existing HTML syntax)? e.g. @bpj's point on very long div (and lists) can be a problem. Being a div, it can be arbitrary long (unlike list which "usually" you can assume it wouldn't be terribly long). So providing both means both situations (short and visual hints are preferred, long and clarity on nested levels are preferred) are covered (and can be freely mixed).

ickc on 23 Aug 2017

@jgm wrote:

I did think of one objection to the proposed indented
div syntax that concerns me more. If we ever did want
to allow attributes to be added to arbitrary block-level
constructions, the natural way to do it would be to put
the attributes on a line before the block. With this
syntax, though,
{.class}
    indented
would be an indented code block with the attributes.

The indented div syntax is growing on me. One solution to the above may be to only allow attributes on delimited code blocks, but not indented ones.

Another issue with indented div block syntax though:

~~~
Hi.

{.warning}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.

Is this the next paragraph of the warning div block,
or is it a code block that comes after the div?

Bye.
~~~

Regarding the ;--- delimited syntax though, along with a possible future similar side-marked syntax: after ruminating on it more, it may be that trying to make a side-marked and delimited syntax "mesh" well may, overall, cause some confusion. For example, if the side-marked semicolon div syntax were accepted, you might very well have complaints and confusion over which of the following is correct:

~~~
; --------- note ----------
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.
; -------------------------

; --------- note ----------
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.

; --------- note ----------
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam, quis
; nostrud exercitation ullamco laboris nisi ut aliquip.

; --------- note ----------
; Lorem ipsum dolor sit amet, consectetur adipiscing
; elit, sed do eiusmod tempor incididunt ut labore et
; dolore magna aliqua. Ut enim ad minim veniam, quis
; nostrud exercitation ullamco laboris nisi ut aliquip.
; -------------------------
~~~

Code blocks have very different side-marked (4 space indent) vs delimited (~~~ or triple-backtick) syntax, and that works very well.

(Edit: Ooof. I'm sorry. Error. Edited to remove comment about pipes and lineblocks.)

So, these are all pretty consistent:

~~
{.foo #bar}
side-marked (indented) div block with class and id.
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nost rud exercitation ullamco laboris nisi ut aliquip.

~{.foo #bar}
delimited code block with class and id.
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.
~

{.foo #bar}

side-marked blockquote with class and id.
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.

{.foo #bar}
| side-marked line-block with class and id.
| Lorem ipsum dolor sit amet, consectetur adipiscing
| elit, sed do eiusmod tempor incididunt ut labore et
| dolore magna aliqua. Ut enim ad minim veniam, quis
| nostrud exercitation ullamco laboris nisi ut aliquip.
~~

Note: that is assuming we can't steal the | back to use for side-marking divs. That would probably be my first choice. But indented div syntax looks good too.

uvtc on 23 Aug 2017

@ickc wrote:

And I think this is suggested before: can we have both side-marking and delimiter (besides the existing HTML syntax)?

Given the following:

it's good to have both (side-marked for looks, delimited for convenience)
trying use the same character(s) to make both look similar/consistent may lead to confusion
I can't convince @jgm to steal | from line-blocks (;))
code blocks have ~~~ (well, and backticks), and it's only one character to hit three times
we can't use --- because it's already used for h2's and <hr>'s
::: is prettier than ; ---
__edit:__ as @jgm points out, the indentation for div blocks is reasonable, as indentation is used elsewhere to mean things that aren't code blocks. And indentation looks very good as a side-marker.

I think the answer is:

~~~
::: {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
:::

:::::::::::::::::::::::::::::: foo :::::::::::::::::::::::::::::: {#bar}
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

{.foo #bar}
indented div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est
laborum.
~~~

I don't recall where everyone stood regarding the :::. @jgm seemed in the middle. Or which way commonmark was leaning. Maybe we can put this one to bed. Please lmk what you think of the above.

uvtc on 23 Aug 2017

::: {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
:::

Looks clean, simple, easy to type, and being compatible with CommonMark makes it a good choice. (The indented form could be confused with indented code blocks?)

DaveJarvis on 23 Aug 2017

👍1

I'm just curious: what about the other symmetric choices below?

I think some has been discussed (e.g. +). And many of the below are not centered in the middle.

@jgm said,

I go back and forth on this, but I tend to think the ---- works better as a separator; it calls attention to itself less than the bulky ::::.

So if : kinds of draw 2 lines, then the other similar characters like .'"_ might be better. Note that although - and _ might be similar, but they are usually visually very distinct in most text editors (with the fix width fonts they/you use). (I guess it wouldn't collide with the emphasis/strong syntax.)

... {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
...

........................... {.foo #bar} ..............................
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
......................................................................

___ {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
___

___________________________ {.foo #bar} ______________________________
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
______________________________________________________________________

+++ {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
+++

+++++++++++++++++++++++++++ {.foo #bar} ++++++++++++++++++++++++++++++
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

''' {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
'''

''''''''''''''''''''''''''' {.foo #bar} ''''''''''''''''''''''''''''''
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

""" {.foo #bar}
delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
"""

""""""""""""""""""""""""""" {.foo #bar} """"""""""""""""""""""""""""""
also delimited div. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

(I just used @uvtc's last example for these characters but other variants like the side-marking ones can also be done.)

ickc on 23 Aug 2017

@ickc

I'm just curious: what about the other symmetric choices below?

Oooh, I'm feeling opinionated! Here goes!

- and _ are already used in <hr>'s, and - in h2's, and markdown and pandoc are loose enough that it's problematic to use them for something else. Also _ are very low to be using on bottom delimiter (they leave a lot of space above them and look off).
+ is used often in email reply headers ("+++ so and so wrote: ..."). Also looks prickly!
quote marks are, IMO, not suited for delimiters. It would be unusual to use them, and markdown is about using what's already usual (or at least close enough) in textual communications. IIRC, ReST uses them for underlining headings.
. and , (periods) are too small, and also too low on the line, IMO to work successfully as delimiter characters.

That leaves:

* already used for <hr>'s, list markers, and emphasis.
= already used for underlining (setext) headers
! bang! This was discussed before. It suggests urgency or warning, which isn't really great for a general-purpose div marker. Also, since it's for a delimiter, I think you generally want to choose a character that at least looks a little horizontal.
% which I bet will eventually become the delimiter marker for block comments
$ means money! Or a Perl scalar. And isn't horizontal enough. No.
@ and & are too bulky not not horizontal enough.
^. I'd suggested these myself, early on, but there wasn't any interest in using them.
# Already used at front of line for atx-style headers.
? only the Riddler would use these.
; could be ok, but colons are more symmetrical and prettier for this purpose

So, I think colons win.

uvtc on 23 Aug 2017

+++ John Gabriele [Aug 23 17 16:49 ]:

Another issue with indented div block syntax though:
Hi.

{.warning}
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip.

Is this the next paragraph of the warning div block,
or is it a code block that comes after the div?

This is no different from the issue we already have
with list items. The answer is that it's part of the block;
if you want a separate indented code block, you need to
end the indented block first, perhaps with an HTML comment.

jgm on 23 Aug 2017

@jgm wrote:

I did think of one objection to the proposed indented
div syntax that concerns me more. If we ever did want
to allow attributes to be added to arbitrary block-level
constructions, the natural way to do it would be to put
the attributes on a line before the block. With this
syntax, though,
{.class}
    indented
would be an indented code block with the attributes.

I thought of that too, but refrained from mentioning it because attributes on arbitrary content is one of my hangups. Now that you mention it I must say that that is an important consideration. Not so much WRT to code blocks, since there are fenced code blocks, but because it might be easily confused with a paragraph with attributes:

{.class}
    Cum quisquam temporibus aut et labore ut ducimus autem.

would be a div and

{.class}
Cum quisquam temporibus aut et labore ut ducimus autem.

would be a paragraph with attributes. These could too easily be visually confused, and are only an indentation mistake removed from each other. If your CSS selector is .class you might not even notice, but if you change it to p.class you get a bug which may be hard to find.

bpj on 24 Aug 2017

It does seem a little inconsistent that this syntax

~
{.foo #bar}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
~

(where you're combining the {...} with the indented block syntax) would specifically mean a div, yet if one could add attributes to other blocks, for example

~~
~{.foo #bar}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
~

:::{.foo #bar}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
magna aliqua. Ut enim ad minim veniam, quis nostrud.
:::
~~

the addition of the attribute is separate from the syntax of the block. Sorry, not sure if that's worded very clearly...

In other words: if a writer learns the general rule that you can mark a block with {...} to add attributes, then the indented div syntax really does look like you're adding attributes to a code block.

Maybe there should be different rules for adding attributes to side-marked blocks vs adding them to delimited blocks. If so, then the indented div syntax muddies the waters of that distinction.

uvtc on 24 Aug 2017

Some points regarding side-marked div syntax (I'm already sold on ::: delim div syntax):

It would be unusual to make a div (side-marked or delimited/fenced) without attributes. For this reason, the {} could be made mandatory for :-side-marked divs to avoid any conflict with definition list syntax.
since divs are often nested, it would be easier to read if there were two different side-markers that could be used.
divs are often used for warnings/notices/errors/admonitions

I've complained in the past about using ! as a side-marker for anything other than warnings/errors/etc, but

I understand that some people like it,
it _is_ one of the few visually useful tall thin side-marker characters,
it's great for warnings/notices/errors

Consider this syntax for side-marked divs:

~~~
{.info #bar}
: side-marked div block with attributes.
: Lorem ipsum dolor sit amet, consectetur
: adipiscing elit, sed do eiusmod tempor.
: incididunt ut labore et dolore magna.
:
: {.warning}
: ! For maximum flakiness, remove
: ! crust from toaster oven after
: ! it turns tacit brown but before
: ! it turns falsetto brown.
:
: Second paragraph. Aliqua ut enim ad
: minim veniam, quis nostrud exercitation
: sulaco dusty vanagon.

{}
: side-marked div block with no attribs.
: Lorem ipsum dolor sit amet, consectetur
: adipiscing elit, sed do eiusmod tempor.
: incididunt ut labore et dolore magna.

! side-marked div block with no attribs.
! No leading {} needed when using !'s.
! Lorem ipsum dolor sit amet, consectetur
! adipiscing elit, sed do eiusmod tempor.
! incididunt ut labore et dolore magna.
~~~

Regarding generic syntax for marking attributes on blocks, while you could leave the future option open for adding attributes to anything side-marked or delimited (line blocks, blockquotes, paragraphs (!)), for now just white-list:

sidemarked blocks that can have attribs: divs
delimited/fenced blocks that can have attribs: divs and code blocks

I think the syntax being discussed here (::: delimiters and :|! side-mark) both look good, and suspect they'd probably see fairly equal usage. This has been my experience with code block syntax btw (though, I don't typically ever use ```, as I think ~~~ looks much better).

uvtc on 25 Aug 2017

👍1

While side-marking (and maybe even an indentation-based syntax) have their advantages
for certain use cases as well, I think it's fair to say that surround-marking
(aka delimited) is the least controversial. So let's focus on its variants for now.

Of the some-character-followed-by-`---`-variants, the following
two seem the most popular:

; --------------- info -------------------- {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.
; ---------------------------------------------------------

(Btw, I'm posting this comment as one big code block, so we get an example of
how the different div syntax proposals look among some blocks of text.)

:--------------- info -------------------- {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.
:---------------------------------------------------------

Then, there is the simplicity of using only one character. AFAIK, the following
two markers seem to fit best and cleash least with existing markers.

:::::::::::::::::::: info ::::::::::::::::: {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.
:::::::::::::::::::::::::::::::::::::::::::::::::::::::

Yes, the dots in the following example are a bit low on the line, but why not?

..................... info ............... {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore

Another paragraph here.
.........................................................

It's true that both the colons and dots are a bit more bulkish than the slender
dashes. But I kind of like that aspect: the div stands out in a long document
and is clearly differentiated from headings and horizontal-rules, which already
use dashes.

Finally, while I like some more than others, I really think all of the examples
I just listed here are fine.

mb21 on 27 Aug 2017

👍1

This thread reminds me of what it is like in my brain when choosing food in a Cantonese restaurant... 😄

So many factors, I am quite persuaded by the recent worries against indentation, and then we are left with delimited vs. side marking, and I think the practicality during writing of delimiting wins. And I think the : has the upper hand overall, so i vote for:

:::::::::::::::::::: info ::::::::::::::::: {.class #ident}
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
:::::::::::::::::::::::::::::::::::::::::::::

iandol on 1 Sep 2017

So to sum the last posts up (before things start to drag along for years again -.-) i see the following trends in the discussion:

For delimited syntax we seem to have a winner (voted for: DaveJarvis, uvtc, iandol, me; proposed at least as option by: mb21, ickc; voted against: noone):

::: {.class #id}
text here
:::

with possible expansions (at least 3 :) and an interspersed class:

:::::::::::::::: oneClassName ::::::: {.allOther #attributes}
foo
:::::::::::::::::::::::::

Further discussion-point for delimited syntax:

should we allow other chars than : like ., -, etc.?

For the side-marking syntax there was suggested:

{.any #attributes .orEmpty}
: this is sidemarked
: Lorem ipsum..
: you know what i mean

! sidemarked without
! special {}-Attribute
! at the beginning of the line
! though it can also be added

I personally would prefer having : play the role of ! in the latter example - but i don't know if that would clash with Description-Lists.

Further discussion-point for side-marked syntax:

does : side-markings indeed clash with description-lists?
what chars would be allowed under which circumstances? (like above: ! always? : only with Attr in front?)
should we allow any other chars beside : or !? The same as with delimited-syntax?

Drezil on 5 Sep 2017

This thread reminds me of what it is like in my brain when choosing food in a Cantonese restaurant... 😄

Although there's a lot here, for me, this thread (reading, and contributing to it) has helped clarify a number of things about Pandoc Markdown. I've seen better and better suggestions, and changed my mind on at least a few things. Some bits I've learned:

side-marked blocks are more markdownish: generally easier to read, more work to write, tends to look better. Side-note: there are precious few really good ascii side-marker characters.
delimited blocks are less markdownish, but convenient (sometimes, much more convenient): easy to write, generally don't look quite as nice as side-marked blocks.
it's not necessarily required, or even advised, to try and use the same character for both a side-marked and a delimited syntax for a given type of block. Example 1: code blocks use spaces for side-marking, but ~~~ (or ```) for delimiting. Example 2: blockquotes use > for side-marking, but don't/can't use >>> for delimiting because that already means a twice-nested blockquote.
```
{.proposal}
! Given that last bullet point, if going ahead
! with a *side-marked* div syntax, it would
! probably make sense for now to only allow `!`
! and not `:`. I must admit that `!` is the
! better side-marker. Add to that that it may
! be visually confusing/inconsistent to use a
! list marker (`:` in definiton lists) also as
! a side-marker.
```
commonly-used/needed syntax must look good to be acceptable (ex. > for blockquotes). This also implies that side-markers should be at least vertical-ish, and delimiter characters should be at least passably flat-ish (::: is a pretty good compromise as a delimiter, in that it's symmetrical, centered, not too heavy on the page, and the character isn't already used for HRs, tables, or headings.)

One initial litmus test I have for a prospective new markdown syntax: given a reader seeing the new syntax once or twice, will they instantly understand what it means and then maybe even naturally start using it themselves without being told it's markdown syntax? If the answer is "yes", then it may be a good idea.
it's becoming common usage to add attributes to blocks and spans using ~~~{.foo #bar} and [can of span]{.foo #bar}. ...But probably not everything can or should support attribute syntax (for example, indented code blocks, list items, paragraphs).
any new syntax added should not look too much like markup (but should look good). Hence, Markdown/Pandoc prefers delimiters like ~~~ ... ~~~ rather than "opening/closing" ones like [[[ ... ]]]. I think an issue with ;--- is that it looks more like markup than :::.
There is strong hesitance to breaking backcompat (ex. stealing | to use for side-marked divs).
There is strong hesitance to making pandoc markdown more strict (for example, requiring blank lines below setext headers and around HRs, which might then allow --- and === delimited divs).
Pandoc Markdown supports "laziness" for list items. Trying to come up with a lazy variant for everything (ex. a lazy-style div block) may lead to unhealthy (er, unhealthier) amounts of bike-shedding.
Markdown sometimes offers multiple ways do the same thing (ex. italics, bold, list item markers). It's useful for very commonly-used syntax when you want to make nested parts look different from eachother (like nested list markers, or * a *cool* list item vs * a _cool_ list item), or when people have their own hardwired text/email habits (some people just like - or + instead of * for lists). But given how quickly that uses up markup characters (and adds parsing complexity), not sure I'd do that for new --- and assumedly less-often-used --- syntax.
Given that = and - are already so overloaded (used in setext headings, tables, and HRs), and that a blank line after an setext heading marker is optional, it's exceedingly difficult to use = or - for any additional syntax.

uvtc on 5 Sep 2017

👍3 ❤1 😄1

One qualm: if the side-marked syntax is supposed to be the handsomer more markdownish one, it should as a special case provide a less-marked-up-looking syntax for when supplying exactly one class to the div. Could this:

~
Note:
! Lorem ipsum dolor sit amet, consectetur adipiscing
! elit, sed do eiusmod tempor incididunt ut labore et
! dolore magna aliqua. Ut enim ad minim veniam, quis
! nostrud exercitation ullamco laboris nisi ut
! aliquip ex ea commodo consequat. Duis aute irure
! dolor in reprehenderit in voluptate velit esse cil.
~

work as a synonym for:

~
{.note}
! Lorem ipsum dolor sit amet, consectetur adipiscing
! elit, sed do eiusmod tempor incididunt ut labore et
! dolore magna aliqua. Ut enim ad minim veniam, quis
! nostrud exercitation ullamco laboris nisi ut
! aliquip ex ea commodo consequat. Duis aute irure
! dolor in reprehenderit in voluptate velit esse cil.
~

?

uvtc on 7 Sep 2017

👍1

I updated my PR to reflect the new syntax.

Two minor things that came up:

The ! leading on line clash with ![](...) so i had to add a special case in birdTrackLine
Having
! foo ! ! nested
would not parse as expected (as foo is parsed as inline and parses for blocks are then already done), whereas
! foo ! ! ! nested
works fine.
Same with
sominline ! suddenlyBlock
I think this comes up in some other places as well (where block & inline gets mixed) - so i don't know if that behaviour is intended.

Otherwise the testcases should be complete.

Drezil on 12 Sep 2017

🎉1

Additional test cases to consider (content and closing ::: removed for brevity):

:::info

::: info {.combine}

::: !info

::: {#id}

::: {#{id}

::: {#\{id}

::: {.class #id}

::: {.-1}

:::#id

::: #id

::: #id:class

::: #識別子

::: #{.class}

::: ###id

::: #id #id

::: #id #info

::: #id #info #bar

::: #id #info {.class}

::: #id ::: #info :: {.class}

DaveJarvis on 12 Sep 2017

Awesome 🎉 😄 🎆

tarleb on 24 Oct 2017

🎉8

WOW! ITS DONE! 🎈 🎈 🎈
Great job guys! :)

saivan on 24 Oct 2017

I think I hear an angel choir…

alerque on 24 Oct 2017

Same here! It took a while but this looks amazing!!!

sergiocorreia on 24 Oct 2017

This is great, really happy to see this arriving!

Two things:

Maybe add the following sentence to the MANUAL:

The attributes can also be replaced with a single word which will form the class name.
Add and fix the following test case (And another should be Para instead of Plain)

% pandoc -t native
::::: Warning
Here is a paragraph.

And another.
:::::
^D
[Div ("",["Warning"],[])
[Para [Str "Here",Space,Str "is",Space,Str "a",Space,Str "paragraph."]
,Para [Str "And",Space,Str "another."]]]

mb21 on 24 Oct 2017

👍1

Good suggestions, I've just done both.

+++ Mauro Bieg [Oct 24 17 14:58 ]:

This is great, really happy to see this arriving!

Two things:

Maybe add the following sentence to the MANUAL:
The attributes can also be replaced with a single word which will form the class
name.

Add and fix the following test case (And another should be Para
instead of Plain)
% pandoc -t native
::::: Warning
Here is a paragraph.

And another.
:::::
^D
[Div ("",["Warning"],[])
[Para [Str "Here",Space,Str "is",Space,Str "a",Space,Str "paragraph."]
,Para [Str "And",Space,Str "another."]]]

—
You are receiving this because you modified the open/close state.
Reply to this email directly, [1]view it on GitHub, or [2]mute the
thread.

References

https://github.com/jgm/pandoc/issues/168#issuecomment-339019751

https://github.com/notifications/unsubscribe-auth/AAAL5D1LZG7SgPA2N-t4Rzm_6heK-fJVks5svfsIgaJpZM4AOGXV

jgm on 24 Oct 2017

👍1

Many thanks for this implementation.

ousia on 24 Oct 2017

At last! :thumbsup: :fireworks:
Really good news, I'm really happy. Thanks to everyone who contributed!

bpj on 25 Oct 2017

Just curious, and I hope I don't open a can of worms, but was the idea of a side-marked syntax dropped ?

Thanks for all the care that was put into this.

simonmichael on 30 Oct 2017

+++ Simon Michael [Oct 30 17 07:25 ]:

Just curious, and I hope I don't open a can of worms, but was the idea
of a side-marked syntax dropped ?

I wanted to keep it simple, I guess. We could reconsider a
side-marked syntax later, but let's see how this works out.

jgm on 30 Oct 2017

👍2

It's been a year, are we interested in discussing side-marked syntax again? Indentation is great. How about the following one. It avoids fences, and use indentation.

::: block title
    block contents spanning
    multiple lines.
    yeah.

chaoxu on 6 Jan 2019

Pandoc: Syntax for divs

Most helpful comment

All 266 comments

Is this a setext header

followed by a fenced block?

Assumptions/summary

Some of my thoughts on the different kinds of syntax

Fenced syntax is already there

The problems with side-marked syntax

Compatibility With Other Markdown Editor

Difficult to Move the Divs Around

Conclusion: Fenced Syntax Is More Important, Against Side-Marked Syntax _Only_

Expanding the functionality of native pandoc divs (and spans?)

:+1: Block-Quote Side-Marking

Surround-Marking: Symmetric vs. Asymmetric

In summary...

TL;DR

Elaboration

Poll

side-marking

surround-marking

Related issues