Because to me it's good enough, the syntax is simple and it's totally readable in plaintext, which makes it the ultimate format against vendor lock-in.
Why are we still using Markdown?
261–270 of 328 posts
Re: Why are we still using Markdown?
#262Earlier quoted context omitted.
Your quotation and list syntax should work out of the box in most Markdown flavors (HN has a very non-standard and crippled version - basically nothing other than italics, paragraphs, and code/preformatting works.) Strikethrough and bold are doubled to avoid common ambiguities. Your underline should technically work, but it comes out as an (emphasis) tag, which is rendered as italics in most browsers.
What ambiguities are there with bold ?
Asterisk * has other uses too. Even more common than footnotes would be
x*y=42
X=42/y
edit: HN automatically finds this example and puts in escapes to make it work. From elsewhere in the discussion I just want AsciiDoc.
https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
Re: Why are we still using Markdown?
#263Earlier quoted context omitted.
groff can produce output with links in it, and does by default in HTML mode! The GNU version of the Unix man page macro set has .UR and .UE for “URI start” and “URI end”. (I don't know whether these were present earlier in the lineage or whether they were introduced by GNU.) Also, the lowdown Markdown converter when in man output mode will output those for links. For fun, try: echo 'Hi there! Have a [hyperlink](https…
I mostly care about links inside the man page (look at man bash — there are tons of internal references like "described below under CONDITIONAL EXPRESSIONS" or "section SHELL BUILTIN COMMANDS below", or operators being underlined and looking like hyperlinks, which you can't easily interact with to just go to where they refer to. You have to employ full-text search, but it also turns up the references themselves, and…
Ah! Yeah, that makes more sense—I misinterpreted you at first since I don't normally think of “internal link” as the default exemplar of “hyperlink”. And yeah, I don't see good target markup for that. Stuff like starting your search regexp with “^ +” helps but is still janky. I'd tend to categorize this mostly as “man pages aren't meant to be long treatments of more complex software”, of course? Some large packages do something which I kind-of like but which I'm not sure would work well if everyone did it (mainly due to ergonomy around disambiguation) where they split up a bunch of their documentation into shorter pages with the origin as part of the section when making it accessible through man: pcap_init(3pcap) from libpcap, Bigarray(3o) from OCaml. Shells, as you notice, get hit by this really hard; Zsh tries to do some splitting in the man version of its docs, but it's really not enough, like I'd want to see fc(1zsh) (and then fc(1bash), etc.) but instead it's all in zshbuiltins. (Eventually I facepalmed when I realized an Info version was available and switched to that. The way I found this out was actually by eyeing the Zsh source tree and noticing that the documentation files were written in Yodl, which I'd never heard of, and then noticing that the schema they were using looked a lot like Info…)
… 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?
Re: Why are we still using Markdown?
#264for me as a user, I like it it's simple to use, I know for the developers it's probably very hard to parse and what not, but for most people the experience matters most.
Also markdown you can use it without any parser just a text editor.
Re: Why are we still using Markdown?
#265Re: Why are we still using Markdown?
#266I've actually tried some other markup languages like asciidoc, but went back to markdown since I found it's hard to cooperate with others with another markup language like asciidoc and it's harder to find something else than asciidoctor to render it. I could write blog posts in asciidoc but in order to make it parse-able for my SSG I'd still have to compile it to markdown.
Re: Why are we still using Markdown?
#267Because, like UNIX/Linux itself, worse is better: https://en.wikipedia.org/wiki/Worse_is_better - and perfect is the enemy of "good enough." 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…
> barriers to producing documentation--should be minimized. Writing well is difficult enough!
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:
It may be a simplistic set of tags, but it is an improvement over easy-to-type text blobs.
Re: Why are we still using Markdown?
#268Earlier quoted context omitted.
It makes quite a few right calls, but still tries to not be a strict subset of Markdown, requiring e.g. a different editing mode.
Being a strict subset of Markdown would make it itpossible to achieve simplicity. From the rationale: > Rules for emphasis should be simpler. The fact that doubled characters are used for strong emphasis in commonmark leads to many potential ambiguities, which are resolved by a daunting list of 17 rules. It is hard to form a good mental model of these rules. Most of the time they interpret things the way a human woul…
Indeed. I'd go with dead simple rules. The below assumes whitespace or punctuation on either side:
*bold*
_italic_
*_bold italic_*
_*also bold italic*_
Re: Why are we still using Markdown?
#269Because we need to get information down quickly, but still have the option of parsing to a presentable format. Markdown is not perfect, but it's far better for the efficient capture of information or document authoring. I recently built AS Notes for VS Code (https://www.asnotes.io). It's markdown based, with wikilinks, mermaid diagrams, with the ability to publish to github pages etc. There is no way I'm writing my day to day notes with HTML and anchor tags without it being a huge distraction. And HTML is so much harder to read in longform if you need to come back end edit your writing. Markdown is for humans where HTML was designed to be simple, but is ultimately for parsers.
Re: Why are we still using Markdown?
#270Earlier quoted context omitted.
Being a strict subset of Markdown would make it itpossible to achieve simplicity. From the rationale: > Rules for emphasis should be simpler. The fact that doubled characters are used for strong emphasis in commonmark leads to many potential ambiguities, which are resolved by a daunting list of 17 rules. It is hard to form a good mental model of these rules. Most of the time they interpret things the way a human woul…
Indeed. I'd go with dead simple rules. The below assumes whitespace or punctuation on either side: *bold* _italic_ *_bold italic_* _*also bold italic*_ Any other combination does not parse as formatting, and is considered literal text. Yes, this prevents marginally useful cases like putting an it al ic fragment in the middle of the word. I'd be fine with that.
If I’m understanding correctly, your rules are based on word boundaries? How do you define a word boundary?