> The whole value proposition of markdown was supposed to be that a writer/reader need not create a detailed mental model to mentally parse the text.

The main value proposition was that the raw markdown looks like normal text. If you just want a simple mental parsing model, you use html or bbcode.

Addenda: looks like normal text --> looks and behaves like normal text.

If it looks like normal text but get rendered to a different text it is a negative value proposition.

Then just write plaintext. Markdown is not supposed to render exactly as written.

That is not the point; if markdown looks like text A and render like text B looking like text A is not a strength in and of itself.

I would say this would still fall under the realm of readability and of being lightweight (as in a markdown text looks like someone that did not knew markdown could have written)

But it is supposed to render exactly what was written. You write a heading, it gets rendered as a heading. You write the number 2, it ought to be rendered as the number 2.

Most markdown parsers don’t work properly you begin with. The issue isn’t the text written. It’s poor parsers.

> Most markdown parsers don’t work properly you begin with. The issue isn’t the text written. It’s poor parsers.

I think this isn't exactly fair, in that it seems to mislocate the problem——Markdown itself is so underspecified (I think Gruber never really expected it to take off the way it did) that the meaning of 'Markdown' can vary wildly from place to place, as a result of which there's no simple, universal test suite, and it's hard to tell on what sort of edge (or not-so-edge) cases your homerolled parser will trip until you actually deploy it (at which point people have come to rely so much on its quirks that it's difficult to fix it).

Indeed, Gruber has resisted efforts to more thoroughly specify parts of the syntax (resolving ambiguities in parsing), saying that the original form works for his needs. This "power vacuum" has led to things like CommonMark (https://commonmark.org).

The point of the numbering changes is if you want to insert a new item half way through the list you don't have to change every single line. Unfortunately it probably confuses people more often than it helps them.

I've come to the conclusion that the worst thing about how developers design their products is the existence of "features" that override the user without the user ever telling it to. It assumes you wanted to do something other than was was inputted without getting further input from the user indicating they wanted to carry out that action. Pretty much every massive technology fuck-up in my life has been the result of the computer doing something other than what I told it to do and me not realizing or not being able to fix it after it did so. Things like "open restored document" helpfully deleting the older, unrestored document for me, attaching signatures to emails when I didn't configure a signature, etc. I want to start a movement that forces us to ask every new feature "did the user tell the computer to do X and if so, where is it indicated that X will happen?" There are a million examples when you look out for it and they're all infuriating.

Oh thank god I'm not alone in thinking that this is a horrible way to design a "feature"!

I've had very similar experiences as you. Every automatic "correction" of user input needs to at least be clearly indicated and easily reversible. In my opinion it shouldn't even happen until the user actively signed off on the proposed modification.

Hitting far above its weight in this category is autocorrect (my wife took to calling it autocarrot in a small act of rebellion), which "helpfully" corrects millions of painstakingly correctly-spelled obscure words into completely wrong but more common words, every day, making human communication less understandable.

Ehhhh I agree with your general point, but I'd argue Markdown's list behavior shouldn't be tarred with this brush. It's a reasonable feature that makes perfect sense if you understand it, but in practice it didn't survive contact with the real world. Nothing is perfect, after all.

> It's a reasonable feature that makes perfect sense if you understand it, but in practice it didn't survive contact with the real world.

I think the same argument can be made for almost every "the machine knows better than the user" decision, so it seems to me that this is pointing out that the Markdown list behaviour should be tarred with exactly the same brush.

> It's a reasonable feature that makes perfect sense if you understand it,

This is true of all these features in general. They're all well-intentioned. No one wants to design a system that annoys users. But my criteria is meant to illustrate why it might not have been a smart idea to begin with: the user didn't indicate they wanted the system to renumber their bullet points. In fact, very often the user indicates that they want a specific numbering by placing specific numbers. The feature would work if there was some way to indicate this is just a bulleted list with numbers. Instead, the system assumes 100% of the time that the user made an error, then fixes that error in a way that is difficult to detect without ever providing feedback about the changes. That's a bad system that happens to usually be trivial or at most embarrassing. But the design itself is flawed from first principles.

A better way to implement auto-numbered lists would be indicate you want to use auto-numbered lists, just like you indicate you want to use headings, links, or any other element. First, don't rewrite all numbers, making the fact that a correction is taking place under the hood invisible to even experienced users. Auto-numbered lists should be indicated by having multiple lines starting with, say, "<space>0.", or even better "<space>#." to be more congruent with the use of "#" for headings and subheadings in other markdown systems (languages?). Second, when a user submits a post, the system should indicate what has been changed, perhaps with a non-intrusive highlight.

The problem would never have arisen had the developers asked my two questions "did the user indicate X?" and "where/how did the user indicate X?"

I suppose you should add onto that "is the change transparent to the user?" which is also known to cause some potentially life-threatening errors: http://www.dkriesel.com/en/blog/2013/0802_xerox-workcentres_... - you probably think "it's markdown, what's the big deal?", but who knows. Maybe someone gets some medical or chemistry advice and, sure, they shouldn't trust reddit, but then maybe someone dies anyway. So I think it's always best practice to indicate that a change has been made.

Besides confusing people, I'd say it's a useless feature for a couple of reasons:

1. If you insert a misnumbered item in the middle of the list then when you come back later to edit the text you will be confused by how the numbers in the source are different from the numbers in the formatted output.

2. There's no point in using a numbered list unless you're going to refer to the number(s) somehow. (In this case I'm using the word "couple" to introduce the list!) Markdown doesn't sort out those references for you so in practice you have to manually renumber things anyway.

This is like dealing with that clueless newbie who desperately tries to help you, in the process creates a huge mess. You'd tell them to stop, and ask for permission before doing anything.

I propose a new term: paternalistic software. It's software that overdoes being helpful, and becomes annoying or dangerous. It's the software that does things you don't want automatically, because it thinks it knows better than you. Automatic renumbering and autocorrect both fall under this.

> It's software that overdoes being helpful, and becomes annoying or dangerous.

It looks like you're trying to write a rant against Clippy. Would you like help?

Clippy was annoying, but at least it was personified enough to serve as a single point of blame. But more than that, it didn't actually do anything automatically for you. It was kind enough to ask.

I used to call it "overly-clever syndrome", but "paternalistic software" is way better. Thanks for this word.

Sounds like my web browser.

I am working in ATC (air traffic control). Controllers prefer a dumb tool with easy to predict deffects (like STCA) instead of a smart tool with infrequent random failures. Simplicity is underrated.

I take your point, though I’m less bothered about errors on Reddit formatting than I am errors in air traffic control.

I use this "feature". But generally I use the same number for all items because it is a pain to have to renumber everything.

maybe the solution is to renumber if a list uses all 1's, but leave it untouched if it has different out of order numbers.

So this gets renumbered:

1. item 1

1. item 2

1. item 3

But this does not:

1.

3.

7.

Shouldn't things like numbering be part of the UA, then the user can decide (directly or give the job to a plugin).

Reddit could then offer "use our text-editor assistant in your browser" to those who aren't using one.

The text box would have to define what it allowed as input: alnum, plaintext, markdown, etc., and the appropriate plugin would activate?

I'd also add that while I agree with the confusion expressed, using code snippets to escape from markdown parsing is important when sharing stuff that literally contains markdown. Of course that depends somewhat on the provider and what custom flavour of MD they use, which is often contraversial.

Like #463 GitHub auto linking, which I usually like, but occasionally been caught by it.

Or there's no point and it's just a consequence of turning numbered lists into <ol>.

that's what plain html is for! I don't really see the point of markdown. With modern html5 you do not even need to close most tags.

I don't know. Even though I know HTML, I'd much rather create a bullet list by putting an asterisk in front of each item than writing a bunch of <ul><li> tags.

> I don't know. Even though I know HTML, I'd much rather create a bullet list by putting an asterisk in front of each item than writing a bunch of <ul><li> tags.

But I wouldn't—and it's a lot easier for you to process your Markdown and paste it into an HTML-enabled text field than it is for me to process my HTML and paste it into a text field that understands only one of the flavours of Markdown that doesn't have sufficient escape hatches built in (or that, like most flavours, has lots of features built in that you're apparently supposed to discover only by experimentation, preferably without any sandbox or preview available).

IMO, plain HTML is much more confusing and quite a bit less legible.

I have no idea how this became the widely held belief about markdown. Markdown is based on Gruber's buggy Perl implementation of a rich text format that's intended to be fairly readable while editing the raw source files. Gruber had zero concerns for how other people would use it, he didn't even support standardisation efforts that tried to resolve the contradictory informal spec he had published.

To be fair, his use case was/is for writing very simple things (blurbs on his blog), that simply don't get into painful corner cases. It's a simple tool that works great - for simple things. It can fail hard on more strenuous cases. As you say, he resists attempts to resolve the ambiguities, yet, he also guards the name "Markdown" - which has all the mindshare - causing headaches for others who try to resolve those ambiguities. So, we get things like CommonMark.

I've got it. We'll create a _new_ spec and design it right this time. It'll support split ordered lists, and table colspan, image size attributes, and definitely templating - cause what we really wanna do is programmatically generate this stuff, amiright!?

I both hate and agree with what you wrote.