Uncategorized
tabatkins — 2014-09-03T21:34:30-04:00 — #1
I was thinking about starting this anyway, but then I saw this was listed as an appropriate topic in the pinned feedback thread. ^_^
It's a big change, but Standard Markdown would be immeasurably helped by abandoning indented code blocks. They're a terrible, inconsistent part of the original Markdown, which causes problems throughout the rest of the language, and fenced code blocks are better in every way.
For one, indented code blocks mean that you're never allowed to indent markdown for any reason, which is pretty limiting. I'm a CSS spec author, and write my specs with a processing tool called Bikeshed, which partially supports Markdown. It's common convention in Bikeshedded specs to only write headings against the margin, and indent everything else, as it makes it easier to quickly skim through a big source file and see where the sections are. Here's an example source file.
For two, indented blocks make handling Markdown nested in HTML much more difficult. Bikeshed supports intermixed HTML by detecting lines that start with a block tag, and outputting just that line literally; the very next line can be (indented) markdown text again. I suspect the reason SMD has the slightly odd rules about HTML blocks is to avoid accidentally triggering code blocks from the indentation. Bikeshedded specs regularly put Markdown text on the very next line after an HTML tag, and it looks completely natural, so this is a place where I'm currently going to have to willfully violate the spec.
For three, the handling of indented code blocks within lists is crazy town - having to indent 8 spaces makes it look terrible.
For four, blank lines in code blocks are hard to see/express. Plus, some editors have options to auto-remove trailling whitespace from a line (I use this, to reduce spurious diff churn). (On that note, I'm glad to see a way to force hard breaks without trailing whitespace make its way into SMD.)
Overall, if indented code blocks go away, Markdown can become completely indentation-agnostic, where the only real requirement is that following lines in a block have to be indented at least as much as the first line. That's basically what I've implemented in Bikeshed so far, and I plan to continue supporting precisely that, even if I match SMD everywhere else.
codinghorror — 2014-09-03T21:40:54-04:00 — #2
I understand the reasons, but I feel this is too big a change to the core.
Note that most non trivial code in the wild tends to be "naturally" indented by 4 spaces or more, which is why the average Java coder on Stack Overflow got good results just pasting in a random block of code into a question. I think this is the rationale that was used to select this convention in the first place but I am only guessing.
I agree that fenced code blocks are better in a lot of ways, but they aren't a replacement, for one thing, sometimes you just want a non syntax highlighted preformatted block versus fenced code blocks which I see as explicit references to "source code".
tabatkins — 2014-09-03T21:44:37-04:00 — #3
Yeah, I suspected this would be the answer. It doesn't kill me, it just means I'll have to willfully violate SMD to continue to support idiomatic use of my own tool. Ah well.
dontdieych — 2014-09-04T01:04:37-04:00 — #4
How about non java coder? So many language out there. And they have all different convention for indent. How about terminal command output? Log?
Even if it is java, you should indent all line by only one unindented line.
Moreover, it is too hard to indent properly for average joe.
"You should use code block for this."
"How?"
"Copy and paste into your editor. Select all then indent. Copy and paste here"
"I cannot find indent
in my editor. I'm using notepad
."
"Forget about it. Just wrap around the block with ```'
hayd — 2014-09-04T01:47:25-04:00 — #5
On Stack Overflow (and here) code can be indented by highlighting and using the keyboard shortcut ctrl+k, or the clicking the "code" button ( {}
on Stack Overflow, </>
here). This is not the case on github (although it does respect indentation for code blocks).
The benefit of ``` IMO is that you can specify the language more concisely.
yaakov — 2014-09-04T01:58:21-04:00 — #6
Addressing some of @tabatkins original points (standardizing code indenting means that it is very hard or impossible to indent for other reasons) and borrowing a bit from his point #2 - what if there was a an negative indicator that could be used in the first line of an indent block to indicate that it should not be treated as code? For example, starting off the top line with at least four dashes (or equal signs, or pluses, or something) would mean that that line should not be processed as Markdown.
diimdeep — 2014-09-04T02:09:57-04:00 — #7
I like this idea, but I would say it will break too many existing documents, maybe better implement this as extension or it's too much change for extension ?
balpha — 2014-09-04T02:37:21-04:00 — #8
The nice thing about indented codeblocks is that they're very easily read in the Markdown source, easier then fenced blocks. Fenced blocks have their own advantages, but indented blocks win in the original "readable as plain text" category.
For your point two, SMD makes mixing Markdown and verbatim HTML much nicer than the original "spec".
For your point three, I don't understand why indenting the code block 4 spaces from wherever the current margin of the text is would look terrible. This seems like the most natural thing to do:
27. We propose frobbling the quux as shown in the
following pseudocode section:
while (ad nauseam) {
x := foo(bar)
}
result = baz(x)
The performance characteristics of this code
are, to use the industry standard term, awesome.
For your point four, again I don't understand. How are blank lines in code blocks "hard to see/express"? They're just… blank lines. And the part about trailing whitespace doesn't even apply to code blocks, because in codeblocks a linebreak in the source is a linebreak in the rendered version.