It's a good example of "pave the path" design philosophy, where you do what users are already doing rather than trying to impose some platonic ideal of what the world should be like. And it works quite well at that.
For those of you who weren't there:
*bold*
_underline_
~strikethrough~
/italics/
> Quotation
- list
- list
- list
Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an <em> (emphasis) tag, which is rendered as italics in most browsers.
* I had to escape all of these asterisks.
** I see this happen fairly often to people's comments here.
The bullet point problem is fixed by only bolding when the asterisks are on either end of word characters.
This is just terrible UI, why do you need garbage marks when you already have bold? And you can edit "as normal" if you like, but that only requires displaying asterisks during that tiny % of time you edit the word, not all the time when you read it or edit something else.
But you're not editing that text! You're editing some other text and see a bunch of asterisks all over the place. And this is especially bad in nested styles - try some colored bold word in a table cell - without hiding the markup you'll basically lose most of visibility into the text/table layout
> to reduce ambiguity
it does the opposite, you can't easily distinguish between an asterisk and an asterisk, which is... ambiguity
> can't distinguish between adding more bold text to currently bold text or adding non-bold text immediately
Sure you can. In a well-designed editor you'll see the style indicator right near your caret is so it's always obvious whether and how your typed text is styled or not.
In a not-so-well-designed editor you'll get that indicator far away from your caret or just get asterisks appearing when you need them.
In a not-designed editor you'll see them all the time even when they don't serve any purpose.
This might be why I also liked LaTeX. The markup itself is semantic and meant to help me understand what I am editing. It isn't just some keyboard-shortcut to inject a styling command. It is part of the document structure.
Only for the 3 primitive styles that were supported? 3 table cells of RedBold GreenLowerCaps BlueUnderlineItalic isn't easy anymore
But also - there wasn't a single app in the 80s with a different easy approach, right? So removing noise had a downside.
> styling command. It is part of the document structure.
Not for the most used markdown markers, where styling = semantic.
But yeah, this tension you are describing is also where other concepts like "paragraph styles" bothered me in later editors. I think I want/expect "span styles" so it is always a container of characters with a semantic label, which I could then adjust later in the definitions.
Decades later, it still repulses me how the paragraph styles devolve into a bunch of undisciplined characters with custom styling when I have to work on shared documents. At some point, the only sane recourse is to strip all custom styling and then go back and selectively apply things like emphasis again, hoping you didn't miss any.
And... I preferred WordPerfect's separate "reveal codes" pane, which reduced the opportunity for ambiguity. WP 5.1 has never been equalled as a general-purpose word processor.
HN automatically finds this example and puts in escapes to make it work.
Or italics can be //double slash// to avoid ambiguities with file paths. That still leaves the windows style //some/file/path as ambiguous But I’ll never accept single * as natural for italics.
*bold* and _italic_ would have been better.
As for /slashes/, which would visually be perfect for italics, the only reason they conflict between italics and filepaths is the fact that in both cases they are expected to be used at the beginning and end of a word. Maybe using an unnatural placement of )parentheses( could have worked as a non-conflicting indicator of italics.
Markdown was created in an era before the web had easily used components for structural syntax highlighting (tree-sitter) and where reliance on regex-based approaches was more common.
Using different delimiter for opening and closing is a good idea on its own, too. I think it makes parsing simpler and unambiguous wrt nesting.
I've imagined something like this:
`(monospace)
_(underline)
/(italics)
~(overstrike)
O, c'mon! That is clearly a giant heading in a display font, squeezed in the middle and wider at the top and bottom. (-;
- Superscript with hat symbol (^)
- Hidden content (also known as spoiler tags, content warnings, click-to-reveal, etc...) with two pipe symbols (||) at start and end of hidden content. Interact with the content to show the content inside.
- Table syntax to show tabular data and align content with pipe, hyphen, colon symbols
---
After that, I'd look at the extensions that are only useful for the use-case you're targeting:
- Subscripting with tilde symbol (~)
- IDs, Classes and Attributes
- Task lists
- Sections / Containers
- Language labels for code blocks
- Math Support (mathml, latex, katex, etc...)
- Table of Contents / Footnotes
- Definition lists
- etc...
• I have to decide whether to use asterisks or underscores for bold and italic.
• I have to decide whether to use asterisks, hyphen-minuses, or plus signs for unordered lists.
• I have to remember all the various rules and edge cases about parsing.
I think it would be easier for me to appreciate your comment if you named some of these other languages. Markdown is the only standardized one I regularly come across that I type by hand, these days.
What are you contrasting to?
As for Markdown specifically- the only thing I regularly mix up is the syntax for links. I frequently reverse the [] and (). But that's just because I don't use it enough to have the muscle memory.
HTML? Also my markup language I created for myself, which is currently not published.
In email, I naturally write things like "...on the example website (www.example.com)..."
Markdown keeps those () in the same place, and just adds the [] so you can delimit the visible text: "...on the [example website](www.example.com)..."
I remember it as passing parameters to a function that requires an URL as an argument. Maybe it's not the most straightforward way, but it works for me
In the worst case, the barrier to entry and exit are pretty low.
First you can switch from WYSIWYG to text editor instantly.
Then you have an outline where you can manipulate your “markdown blocks” [i.e title and its content] by drag n drop. Or extract a “markdown block” as a new note, and leave a reference where it originally was extracted from.
And then [the killing feature], it displays the content of a link, web link or internal link, as a [kind of] iframe, if you prepend a ! to the link.
A lot of the load comes from the editor and parser, and if Markdown died tomorow, plenty of teams would crawl back to worse HTML habits.
echo 'Hi there! Have a [hyperlink](https://www.gnu.org/software/groff/manual/groff.html).' | lowdown -st man | groff -man -Thtml
So if I set MANROFFOPT=-rU1 in the environment, I can get clickable links in man… if the man page author included them that way in the first place. I'm not sure how common that is in the wild, but grepping the ones on my system, I find firejail(1) contains a link to a GitHub issue embedded in that way, and it does indeed work when I hit ^O^N to seek to it and then C-mouse1—though the mouse gesture I have Alacritty using for links doesn't seem to work through tmux (there might be a way involving twiddling the tmux terminal-features setting, but I ran out of steam before trying this), and I didn't see a great way to get either grotty or Alacritty to style them on display instead of having them blend into the surrounding text, so it's still kind of scuffed in practice. (Though I bet the cool kids have moved on from Alacritty by now?) less displays the link target in the status line when you use the navigation commands, so it's not inaccessible, but for opening selected links directly from less with the ^O^O gesture rather than leaning on terminal support, it looks like you need to explicitly set the LESS_OSC8_ANY and/or LESS_OSC8_‹scheme› environment variable to a shell command that outputs a shell command pattern to substitute the link into; if I set LESS_OSC8_ANY='echo xdg-open %o' then it passes it to my Firefox. I wonder if they'd take a patch (or if any existing distributions patch it) to use that as the default?
That was a fun little rabbit hole to go down, thank you.
… wow, hang on, I just checked for Bash, and it has an Info file but it says it's just an intro and the manual page is the definitive version‽ That's… hah. There must be some timeline jank around that; ambiguous NIH vibes around Info aside, I wouldn't have expected it from an actual GNU program! Did Bash show up before Info existed?
A man page source isn't a binary format, so your statement that they're "plain text" is technically correct. (The same is also true of TeX and LaTeX files, and even PostScript if you want to stretch the definition of "plain text" until it snaps.) But the renderer is groff or (legacy) troff with the `an` macro set. less(1) (or, originally, more(1)) is just the pager that consumed the former's output (if the output format is ASCII, which is one of many) and handled paging on the terminal for the convenience of the user.
In my old Sun workstation (and even early Linux desktop) days, I rarely used man(1) in the terminal because 1/terminals were usually too small and weren't usefully resizable like they are today, and 2/unadorned monospaced fonts don't look nearly as nice as properly typeset pages do. (Color terminals were just coming on the horizon, and text could only be emboldened, not italicized.) Instead, I typically used xman whenever I could. The best way I can describe xman is as if you were rendering man pages into PDFs and viewing them in Preview on the Mac. Man pages were much more comfortable to read that way.
.Lk https://dotat.at/ "Tony Finch’s web site"
It's a very old idea
In the paper, Copernicus postulated the principle that "bad money drives out good", which later came to be referred to as Gresham's law after a later describer, Sir Thomas Gresham. This phenomenon had been noted earlier by Nicole Oresme, but Copernicus rediscovered it independently. Gresham's law is still known in Poland and Central and Eastern Europe as the Copernicus-Gresham Law.
The wikipedia page about "worse is better" re: software linked above states:
It refers to the argument that software quality does not necessarily increase with functionality: that there is a point where less functionality ("worse") is a preferable option ("better") in terms of practicality and usability.
(1) I can never remember, whether I need to use [] or () first, when embedding an image. In Org mode syntax one simply uses [] for both parts.
(2) Or whether ** is bold or italic or * is bold or italic. Other formats use the well known / to mean italic, which optically already makes more sense and also doesn't interfere with something being bold or not, because it is a separate symbol. This makes Markdown also harder to parse btw..What about something like AsciiDoc (or reStructuredText)?
* https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
* "Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code": https://news.ycombinator.com/item?id=33468213
Simply things are still simple, but there seem to be more advanced options for those that want/need them.
Writing is a demanding kind of encoding. At the same time, we all expect but rarely get good, accessible, searchable documentation. Why? The one barrier that cannot be removed is the need to retain semantic structure.
In TFA, the author writes:
The Bad -- We don’t know what we want.
We consistently fail to manage meaning. It's strikingly paradoxical because the art of programming is all about meaning. We organise code semantically because it is essential to do so (not just for compiling, but also) for extending/refactoring/review/retrieval/understanding.
We need to write with the same considerations. This need not be complicated. Yet we persist in using the wrong utensils for the recipe.
> Markdown is the best compromise we know of
It reduces keystrokes and makes the handraulic act of writing easier. But... it addresses only part of the problem.
As an example of a small improvement, HTML5 offers a minimal set of semantic tags: <summary> <article> <main> <section> <details> <aside> <figure> <figcaption> <time>
It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
There's the stuff that wows people and the stuff that people actually USE.
What's wrong with .txt ?
We want to encourage people to produce written output with minimal friction. Barriers to writing--and especially barriers to producing documentation--should be minimized. Writing well is difficult enough!
Markup is overhead. Complex markup is even more overhead. Markdown is the best compromise we know of today that provides just enough structure and typographic capability, while imposing very little cognitive load on the author.
Besides, if you need something more complicated these days, you can have your favorite AI agent do it.