121–130 of 328 posts
Earlier quoted context omitted.
Markdown is pretty far from the worst. It's decent and unobtrusive. Worst would be something like Troff or jira formatting. Midtier would be RST.
Ugh, troff. It's mind-boggling that the closest way to have an actual (hyper)link in a manpage is to use your pager's "search for text" function. No, "JuSt usE gNu iNfO it'S beTtER" is not an answer either.
i like html fine, but org-mode, now you're talkin'. it's like the nasa voyager equivalent of text markup. just needs to be rescued from being held hostage in emacs.
Markdown in the same directory as the code it documents is very readable by humans and LLMs.
Given LLMs proficiency in markdown and that reading it in view and edit mode is comparable I bet many engineering teams ditch confluence/Google docs for documentation in favor of just markdown plaintext docs adjacent to code (my team has moved design/RFCs to this as well, get feedback via PR commits, turn an LLM loose to implement design)
Also if you really don’t like it I bet you could just ask the LLM to translate it. No point wasting the human input characters or tokens on a ton of etc
if you tell somebody they can use HTML, they get frustrated when you tell them that tags other than anchor, bold, italic, list, heading, and paragraph aren't supported. but if you tell somebody they can use markdown, then they implicitly understand that the content they're submitting won't be rendered as green text on a purple background, and don't try to accomplish that.
Because, 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…
The solution is sufficiently perfected with markdown. Just like new revolutionary technologies doesn't replace wheel technology.
Everyone seems to forget Markdown was invented for humans and incidentally for machines. Almost everyone who complains has some parser or rendering related agenda. No one cares if you can't nest asterisks inside underscores. Most of these edge cases don't read well as Markdown, which defeats the purpose.
>Everyone seems to forget Markdown was invented for humans and incidentally for machines. We already had plain text for that. Markdown was invented to be converted to HTML. It has no utility over plain text otherwise. The link and image syntax is doing what HTML tags do, but are less readable for people than just pasting the URL. The relationship to the machine isn't incidental, it's intrinsic.
My cat is an idiot.
My cat is an idiot.
My cat is an idiot.
Earlier quoted context omitted.
Markdown is pretty far from the worst. It's decent and unobtrusive. Worst would be something like Troff or jira formatting. Midtier would be RST.
Ugh, troff. It's mind-boggling that the closest way to have an actual (hyper)link in a manpage is to use your pager's "search for text" function. No, "JuSt usE gNu iNfO it'S beTtER" is not an answer either.
I've written over a dozen books. Have used asciidoc, HTML, word, latex, and rst. Markdown is the least painful of all. It's not perfect but the others are worse. (My custom stack uses markdown (or Jupyter notebooks converted to markdown). Pandoc plus some custom filters creates typst (for PDF) or epub.)
I did a book in rst and liked that it had cool admonition, import, glossary, and index features that made it better than markdown for me. Still hate the heading conventions.
Also, as I use it, Markdown is effectively plain text. I very rarely look at "rendered" markdown. I guess in practice I actually use "plain text" that just happens to look a lot like markdown by this article's definitions.
Earlier quoted context omitted.
markdown tried very hard to encode conventions that were already used in Usenet, email, and other text media For those of you who weren't there: *bold* _underline_ ~strikethrough~ /italics/ > Quotation - list - list - list I've been using these for almost half a century. They're much easier and more intuitive than Markdown. I see no compelling reason to change.
But Usenet style didn't have a trendy name, an 'inventor' or Github stars. So it didn't exist.