Syntax for divs

[jgm]

I've been missing a way to specify a div markdown
without using HTML tags.  The (relatively) new 
delimited code block syntax gave me an idea however.
Consider using a line of four or more periods to
start a div:

    Para before div

    ....
    First para inside div

    Second para inside div

    Third para inside div
    ....

Since one will often want and need to apply an ID
and/or class to a div one should be able specify
those.  I suggest a CSS-like syntax inside braces
after the opening line of periods

    .... {#id .class}
    div content
    ....

One problem would be nested divs.  I suggest marking
those by indenting.  A code/pre block containing div
syntax would need to be doubly indented, similar to 
such blocks inside lists:

    .... {#outer_div}

    Para of outer div

        .... {#nested_div}

        Para of nested div.

        A code block illustrating div syntax
        (a most unusual thing!):

                ....{#example_div}
                This is how you specify a div
                ....

        Another para in nested div

        ....

    Another para in outer div

    ....
markdown
Of course one could mark nested divs by more periods in the
line (and then at least two more!):

    .... {#outer_div}

    Para of outer div

    ...... {#nested_div}

    Para of nested div.

    A code block illustrating div syntax
    (a most unusual thing!):

        ....{#example_div}
        This is how you specify a div
        ....

    Another para in nested div

    ......

    Another para in outer div

    ....

But I think indenting makes things cleaner, making it
easier to remember closing the divs you have opened, and not 
to close more divs than you have opened.  If you have very 
many nested divs you should probably pause and consider why 
anyway!

Google Code Info:
Issue #: 195
Author: bpjonsson
Created On: 2010-01-07T13:54:47.000Z
Closed On: 

[jgm]

+++ 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]

+++ 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:

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

[van-de-bugger]

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.

[uvtc]

@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]

@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 ::: <!-- /outer -->, as long as Pandoc doesn't complain or insist the comment go on a separate line.

[mb21]

2. [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.

[bpj]

@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]

@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]

@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:

1. [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.

[ousia]

@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.

[jgm]

+++ 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.

[hadley]

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.

[ousia]

@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]

@jgm, are there any news on this issue?

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

[jgm]

+++ 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.

[ousia]

@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?

[thejohnfreeman]

@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.

[uvtc]

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.

[jgm]

+++ 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.

[uvtc]

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.)

[ousia]

@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.

[uvtc]

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.

[thejohnfreeman]

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.

[bpj]

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!)

[uvtc]

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

[jgm]

+++ 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."

[bpj]

@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]

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.

[jgm]

+++ 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.

[bpj]

@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).

[uvtc]

! 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.
;;;

[bpj]

@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.

[uvtc]

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 <!-- comment --> markers.)

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

[ghost]

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

[bpj]

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.

[jgm]

+++ 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.

[uvtc]

@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.

[ghost]

@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

[uvtc]

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

[jgm]

+++ 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}

[ghost]

@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.

[bpj]

@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.

[ghost]

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

[bpj]

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.

[felixsanz]

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:

[bpj]

@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!

[ghost]

@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...

[bpj]

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]

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

[ousia]

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.