Yes. Blockquote container works nice, if you have 1-2 paragraphs. All examples with blockquotes are of this type. But since we are discussing standard, we have to cover all cases, or declare that other cases are out of interest. I’d like to avoid sitiuation, when blockquote is promoted as universal solution. Because it isn’t. With big blocks it’s horible both for typing and for reading.
Thanks! As far as i see, requests for alternate block container are floating for a long time. It would be nice, if those will not became suppressed by blockquote extentions.
Spans are required too, but in worst case those can be hacked via AST with some luck. Blocks can’t be hacked in safe manner, and require good support at parse phase. I think, we have everything to declare those without pain. Fenced blocks are investigated and covered very well. We need only to invent alternate marker and declare “parseable fenced blocks”
+++ Vitaly Puzrin [Oct 30 14 02:11 ]:
Blocks can’t be hacked in safe manner, and require good support at parse phase. I think, we have everything to declare those without pain. Fenced blocks are investigated and covered very well. We need only to invent alternate marker and declare “parseable fenced blocks”
I’m not yet sold on the idea that these should be fenced blocks, as opposed to side-marked (whether by overloading blockquotes, or by introducing another side marker).
You raise the issue of long blocks. But there is also a problem with fences for long blocks, which is that it’s easy to lose track of the fact that you’re in a special kind of section. With side-marking, there is a constant reminder of the scope of the section.
In addition, with fences, as Fletcher Penny pointed out on the markdown-discuss group, deleting one line can radically change the meaning of huge parts of the document. Side-marking is more “local.”
I think the biggest argument for fenced code blocks (when we originally introduced them on the markdown-discuss list) was that indented code blocks are inconvenient for cutting and pasting code (either from a program to the markdown document, or in the reverse direction). That consideration doesn’t apply as much to generic block containers. Generic block containers do seem to me to be a generalization of blockquotes. So, using side-marking for them seems more in the spirit of Markdown than introducing fences. It would be more consistent with the rest of the syntax.
It is interesting to compare the main competitors, AsciiDoc and reSructuredText. AsciiDoc uses fences:
[NOTE]
.A NOTE admonition block
=====================================================================
Qui in magna commodo, est labitur dolorum an. Est ne magna primis
adolescens.
. Fusce euismod commodo velit.
. Vivamus fringilla mi eu lacus.
.. Fusce euismod commodo velit.
.. Vivamus fringilla mi eu lacus.
. Donec eget arcu bibendum
nunc consequat lobortis.
=====================================================================
reStructuredText uses indentation to determine the scope of the block container:
.. note:: This is a note admonition.
This is the second line of the first paragraph.
- The note contains all indented body elements
following.
- It includes this bullet list.
Interestingly, in both cases the method used aligns with the approach to blockquotes. In AsciiDoc blockquotes are fenced; in reStructuredText they are indented blocks. (It may be that you prefer the AsciiDoc approach…but then, why not just use AsciiDoc?)
The main complaints that have been raised against blockquote-style syntax are (a) that it is a pain to write and (b) that it is hard to read. I see why one might worry about these things, but (a) is completely solved if you use a decent text editor, and I’m just not sure that the difference in readability (b) is all that great. As I pointed out above, the presence of the side markers reminds you that you’re in a special section, which you might otherwise lose track of in a longer section, so there’s a way in which it increases readability. (In a published book special sections are often put in a box with a different background color or font.)
I’m not at all decided on this issue; I’m just explaining why I don’t find it an easy one.
1 Like
It’s also worth considering using indentation to mark the scope of the container. That also has good Markdown pedigree, since that is how we deal with list items. Indeed, we could re-use the list item rules.
.NOTE
This is a note admonition.
This is the second line.
- A list.
- Another item.
Next paragraph, not in the note.
1 Like
I’m not so sure. For example, I often wrap notes and half-finished snippets in my markdown documents in a <div class="note"></div> and then move that text (including lists and blockquotes) out of the div as I finalize it.
That’s indeed the major downside of fenced blocks. However, would you have lazy continuation for those blocks as well? Then the visual cue is radically reduced. I think we have to face the reality that a lot of people aren’t using a decent text editor—that’s why lazy continuation is so popular. And honestly, I write a lot of markdown in iA Writer as well, just because I find that its beautiful typography and environment puts me in a different mind-set than when I’m coding. And then yes, when I need to format a blockquote I quickly switch to vim and copy’n’paste it back. And let’s not talk about some environments that use non-monospaced fonts (ahem, Discourse, ahem). Working with block-based indentation when using soft-line-wraps (as most people do when not working with code) becomes quickly a mess as well.
When working in normal/non-code/non-decent editors, I find fiddling with side-markers/indentation a lot more challenging than using fences. That being said, I think both fenced and side-marked blocks are workable solutions.
:::::::::::: SPOILER :::::::::::::
Spoiler Text Here etc....
::::::::::::::::::::::::::::::::::
converts to
<div class="spoiler" >
<div class="key header" > spoiler </div>
... content here...
</div>
http://talk.commonmark.org/t/content-block-inline-syntax/815
@mofosyne I’ve come to like that as well (added your example). Maybe we’re soon converging on something here? Let’s hear some more people on the block style…
1 Like
I considered both fenced and indented styles for containers. I think, both are good, and selection depends on content, editor, and personal preferences. Probably, it worth to have both in the end. Whe only reason, why i mentioned fences - because it’s less “conflicting” with other markup and possible to finish in short time. Personally, i’d prefer fenced, but will agree with indented too. Any choice will be better than pushing blockquotes “as is” everywhere.
As far as i know, current fences spec allows to indent the whole block. This identation will be substracted later. Fencing do not force you to make identation, but allow to use it, if you wish to make result more trackable. Nested blocks are resolved by fences length.
May be fences concept needs some polish, but i don’t see fatal clashes in it.
My target community is “ordinary forum users”. They will be more comfortable with markdown (though they don’t know yet about it 
). I don’t pretend on right understanding of markdown spirit, but hope that my suggestions are not destructive for it. Selecting alternative text markup is not acceptable for me.
I don’t see problems with readability for indented style. But note, that editor depends on enviroment. On web that can be just a textbox. Also, i’m not sure that regular users have descent editors. I think that’s a question “what markdown spirit is?” in general - does it allow some visibility tradeoff for more simple and comfortable typing.
No prob, i understand. Nobody wish to be responsible for scary standard. IMHO, we could decide first, if we needed 2 styles (fenced + indented), or only one should stay in the end. If we select both, then we can set less conflicting to top priority. I’m realistic with timeline estimates for standards. 1 year is very optimistic for full final spec. That’s too long. So, it worth to range priorities, setting the most painful parts to top. IMHO block container is this one. Because it locks too much.
Tables, math & spans are also “painful”, but not locking other things as much as block container does.
+++ Vitaly Puzrin [Oct 30 14 18:12 ]:
I don’t see problems with readability for indented style. But note, that editor depends on enviroment. On web that can be just a textbox. Also, i’m not sure that regular users have descent editors. I think that’s a question “what markdown spirit is?” in general - does it allow some visibility tradeoff for more simple and comfortable typing.
One of the essential guiding ideas in Markdown, as articulated in Gruber’s original documentation, is that it should be easy and natural to read. This sets it apart from, for example, Textile, which is just as easy as Markdown to write but less esay to read. So I think that the spirit of Markdown recommends favoring ease of reading when there is a tradeoff between ease of reading and ease of writing. This comes out clearly if you compare the way Markdown handles lists with the way most other lightweight markup systems (excluding reStructuredText) do. In Markdown, inclusion of continuation paragraphs and sublists is indicated by indentation, whereas in AsciiDoc and most wiki formats, you use duplicated list markers (**, ***, e.g.) for sublists, and a special connecting symbol (+) to join paragraphs to an existing list item. Compare this example from the AsciiDoc documentation
1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.
2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.
b. List item b.
This paragraph belongs to item two of the outer list.
--
with the Markdown equivalent:
1. List item one.
List item one continued with a second paragraph followed by an Indented
block.
$ ls *.sh
$ mv *.sh ~/tmp
List item continued with a third paragraph.
2. List item two continued with an open block.
This paragraph is part of the preceding list item.
a. This list is nested and does not require explicit item
continuation.
This paragraph is part of the preceding list item.
The Markdown version (technically, pandoc Markdown, because of the a. list item) looks a lot like the rendered version; you can see the nesting clearly. Not so with the AsciiDoc version – but the AsciiDoc version is easier to write, since you don’t have to worry about indenting things. So you can see these two different syntaxes as making different tradeoffs between ease of reading (by a human) and ease of writing.
2 Likes
A solution here might be to improve Markdown editors instead of adding additional syntax options. For example, on this forum I’ve never manually typed the full quote syntax (e.g. [quote="jgm, post:43, topic:767"]) because it is easier to highlight a passage of text and click “quote reply”. The same might be applicable to lists, blockquotes, and other repetitive aspects of Markdown.
Could you summarize pending problems of fenced markup? It allows identation (based on marker offset), and should provide user choice for both cases:
- indented style for readability (or if you like it and have descent editor)
- not indented style for easy typing in any enviroment.
Also it allows resolving nested blocks and possible cases are already investigated & covered in spec (as fenced blocks for code).
Someone can dislike need of tailing marker, but it’s not a big price for universality and ability to accept this markup in reasonable time. Also, it will not pervent to add pure indented style later if required.
1 Like
Quotes should not be edited, that’s an edge case. Improving editors can solve problem, but it’s unsafe to assume that all users always have editor with good indented style support.
Just some thoughts.
-
Note that attribute blocks for side-marked blocks should not be inside the sidemarks, this precedent was set by Kramdown to avoid clashing with attributes on paragraphs within the side-marked content. But this could work:
{ .TIP } : # Don't use closed-source tools! : : You can't change them and you can't count on them : being around in the future.However, here it’s clearer to what the attribute belong to:
:::::::::::::::: { .TIP } ::::::::::::::::::::::: # Don't use closed-source tools! You can't change them and you can't count on them being around in the future. :::::::::::::::::::::::::::::::::::::::::::::::::And you’d probably rarely use a div without attributes.
-
For very long or nested content, the side-lined syntax seem to have the edge again.
::::::::::::: {#outer} blah blah blah ::: {#inner} ok :::::::::::: blah blah blah ::::::::::::::::::::::vs.
: blah : blah : blah : : : ok : {#inner} : : blah : blah : blah {#outer}
Yea I can see some convergence in regards to ::: . The difference tho is that I see it more as a block/div version of the inline/span []{}. Thus my logic is that since !extName[](){} is grammatically Verb/act + content/arg for inline, the same logic should apply for block directives as !extName: + content/arg. This allows for easily converting an existing block of content into a directive block. e.g.
This is spoiler text
Can be acted upon as
!spoiler:
This is spoiler text
Which is good for single paragraph content.
While for multi paragraph blocks, the ::: fence kicks in as:
!spoiler:
:::
This is a spoiler
With a second paragraph.
:::
I do not intend this to be a directive as it doesn’t have a block directive signifier !spoiler:. It’s just a div with classname .spoiler. E.g. you might want a warning, or notice box, and that would be rather overkill with directives
:::::::: Spoiler ::::::::::::::
Just a normal div container
:::::::::::::::::::::::::::::::I’ve handwritten and edited quotes numerous times. For example, when writing down a quote that is in printed material, embedded in an image or heard in spoken audio.
Agreed that we cannot make the assumption that the writer is using a specific editor. If the writer is quoting large blocks of text, perhaps they are an advanced user and likely to be using a more sophisticated editor? It would be good to see some use cases for long quotes. From my experience in academia it was generally frowned upon to quote more than a few paragraphs at a time; long quotes are at the expense of original content (perhaps @jgm would like to weigh in here).
With line blocks for song lyrics I can see a potential issue for marking up lengthy multi-paragraph songs.
If it is decided that a block syntax is necessary, perhaps we could use the same marker for familiarity, similar to how fenced code blocks use the same backtick as inline code:
>>>
This is a blockquote
Covering three paragraphs
Final paragraph
>>>
This could be an alternative to:
> This is a blockquote
>
> Covering three paragraphs
>
> Final paragraph
And for line blocks:
|||
This is a line block
Covering three paragraphs
Final paragraph
|||
This could be an alternative to:
| This is a blockquote
|
| Covering three paragraphs
|
| Final paragraph
I’m not entirely convinced of the need for this but it’s worth looking at options.
2 Likes
At this point, I see a block directive as basically a div that in addition to containing block elements, has:
- inline content
- a name (could be rendered as a HTML5 custom tag)
In absence of a filter or something handling a directive, a div is a natural fallback.
1 Like
To quickly recap the arguments in favour of each div-syntax proposal (nobody seems to like indented syntax):
Side-marking
- more readable for long sections (because it’s always obvious that you’re in a div-environment, even if the section is longer than the height of your screen)
- more local (removing one line doesn’t change large parts of your document)
Surround-marking
- more readable for short sections (because of the almost-line-long surrounding markers)
- doesn’t require a decent editor to write easily
- better for copy’n’pasting / wrapping existing stuff in a div
3 Likes
I’d say, both should be supported at the end. Because side-marking is nice for small peaces of text. But, side-marking needs much work. Surround-marking is fenced-blocks like, and can be accepted very easy.
For me, it’s more management question, how to reorder spec priorities. Having one well working DIV markup is much better than having zero. I don’t count blockquotes, because i think those are unusable in current state.
2 Likes
I agree. And the longer I think about it, the more I’m convinced that we should go for surround-marking for now. An alternative side-marking syntax could still be implemented later if needed.
1 Like
+++ Vitaly Puzrin [Nov 03 14 13:25 ]:
For me, it’s more management question, how to reorder spec priorities. Having one well working DIV markup is much better than having zero. I don’t count blockquotes, because i think those are unusable in current state.
Blockquotes are just a form of side-marking, and you don’t seem to be against side-marking in principle. Blockquotes can already contain arbitrary block elements. Why are they “unusuable” (supposing a mechanism was provided to add attributes)?
1 Like