💾 Archived View for tanelorn.city › ~sparrowhawk › bouncepaw-md-answer.gemini captured on 2020-11-07 at 01:29:16. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2020-10-31)
-=-=-=-=-=-=-
Posted on 2020-10-19, an answer to bouncepaw's 2020-07-14 post:
(I have just realized that I wrote the whole thing addressed directly to bouncepaw. If you read this and aren't them, think of it as a dialog)
Now let me start by stating that I agree with every fact you have quoted. I have smiled upon some of the examples, for if you use the same renderer often enough, you will end up by knowing what works and what doesn't, and forming habits around it. However, the truth remains: however much your invitation to write a rant-smashing article telling you how wrong you are is tempting - after all, who doesn't like to write rant-smashing articles in their free time - I will try here something different: show that markdown's suckiness is actually linked to the mindset with which you use it.
After chewing on your article for a bit, I decided that there were two paths I wished to explore as an answer. Firstly, this whole conversation makes me oh-so-strongly think of sh(1). Not knowing how familiar you and my other readers are with the shell and UNIX history, I'll explain in detail what I mean by this and how it is relevant; but by now a reader knowing their way around old systems must be smiling. Secondly, and this will build on the above parallel, I think that markdown only sucks if you use it for what it is not, or, more correctly, whatever the original intention behind it, it has a use case for which it excels.
In the beginnings was sh(1), the shell. Through it you could interactively talk to your computer! How fantastic. And of course, because in order to convey data between entities we need a common understanding, with it came a language, with a syntax and semantics. And then, someone, somewhere, had an idea of something they were missing... And suddenly, csh, tcsh, ksh, zsh, fish, bash, dash, and many, many more popped up all over the place. And each with their own dialect of shell built-ins, concepts for the environment, &c. In the end, after so many improvements, there is only one thing we can all agree on: POSIX compatible, well-defined, sh. All other variants are not portable, not compatible between each other, &c. By now, if it was not obvious at first glance, you should see the parallel with the argument made on markdown's disunion.
And yet, the shell is ubiquitous. If you program, you use git, you use a shell. If you are a power user, you use a shell. If you are a system administrator, you use a shell. When your filesystem fails you, when you have no idea why your computer won't connect to the network, when you are running large-scale computing experiments, or simply sorting through a textual representation of DNA, you use a shell. Most users without a specific taste end up using bash. Some advanced users will use zsh with hundreds of lines of configuration. Old timers will stick to ksh or csh. And then we end up with the same problem: if I write a shell script for fish, the shell I use everyday, and try to share it, we'll have compatibility issues. Heck, fish isn't even POSIX compatible! So what do we do ? You've already given the answer: we differentiate private and public code, and stick to the standardized subset when sharing.
Now of course, this does not make any argument against the suckiness of the situation, one could easily answer: « sure, so shell sucks as well ». But I argue that the above syndrome is actually something that is inevitable with any tool that is sufficiently widely used. We see it happen with language, where regional and cultural sub-grammars emerge, we see it happen with about every, really well established programming language (think of C for example). Heck, think of screwdrivers! In a sense, your extension of text/gemini for your wiki shows exactly what I am trying to abstract: you have this awesome tool that almost does what you love. So you fix it just a bit so it works like you want it (think text editors, keyboard bindings...). Except now your neighbor cannot use it, because they do not know what to expect from your version. This pattern is repeated constantly around us, and I believe it's a very good thing. For long, what was missing from markdown was the POSIX definitions, the one common standard that we can all interchange in; but CommonMark has solved this problem. Being fragmented is not an issue.
People sharing un-standard code is an issue, just as you get angry at someone handing out a bash script with a /bin/sh shebang, or expects you to compile GNU C extensions without warning.
Now, this bit is fairly tied to how I use markdown, but I believe that I can generalize an argument from this. To me, markdown is a programming language just like any other. I use it because I treat my writings as data: sometimes I need to be able to process them, sometimes I need to be able to present them. And so, depending on what I want to do, I will use the programming language I know that makes my life easiest. Sometimes, I want to quickly jot down a few notes, which I will do in a loose markdown-like format because the only compiler it's going through is my head. Sometimes, I want to write a markdown document that will be parsed by several people and engines: use the standard. Markdown is also a very handy way of quickly writing down something that you can transpile in a HTML document to share with non-technical friends. When I am writing for myself, I'll fully use all the Pandoc extensions I know, before transpiling that into a PDF: the end reader never needs know I have strayed out of the standard.
In a sense, there are two ways to use markdown: as a markup language that will be rendered with no transformation by an engine. Yes, everyone has their own version, but in the end, people with common sense will go the portability route (we even have cmark to verify our documents before publishing them, just like shellcheck for sh and other tools for other programming languages). The second way is as source code for a transformation that will lead to the presentation of data: in this case, various dialects matter only as to which enables you to achieve your goal with the least keystrokes. Gemini is as simple as it gets. Markdown is more complex, and can be much more if you use a dialect. HTML is even more complex, but you get yet more flexibility. Then you have LaTeX. And so on.
We have a standard, and it's nowadays pretty well respected. If you write non-standard code and expect it to be portable, you will have issues. If you stick to the standard, certain things will be more painful than if you use XX or YY dialect or extensions. I wrote this article using standard English, but assuming that technical references and acronyms will be understood (if they aren't, email me and I'll make a second pass to remove as much jargon as possible). As long as you choose the right problem for the tool you are using, then markdown works.
Finally, what I am not going to argument, but actually to open, is comparing markdown to other markup languages. I've already seen quite a number of arguments about the syntax of similar programming languages, or worse the formatting of a language. In the end, I am thoroughly convinced that syntax is a trade-off between how easy things are to remember and how many keystrokes it takes you to accomplish a task (if you know Haskell, you'll know what I mean). Markdown went down one road, and I can understand if you have more affinity with another, but like the editor wars, I really think in the end it's about what you learned first and is closer to your way of thinking. I guess the conclusion is a big yay for diversity, as long as we keep standards so we can communicate.
I'll happily receive and include any comments, though should this start looking like a serious discussion, keeping things mainlined in bouncepaw's original post is probably better.