> So, the bottom line is: Do not use markdown. Do not use DocBook. Do not use Texinfo. Use mdoc(7) to maintain your source documents, and mandoc(1) to convert them when needed
Cool, let’s see what mdoc looks like:
> The following is a well-formed skeleton mdoc file for a utility "progname":
.Dd $Mdocdate$
.Dt PROGNAME section
.Os
.Sh NAME
.Nm progname
.Nd one line about what it does
…
So, utterly incomprehensible. I’ll stick to Markdown, thanks!
Yeah, I also looked at mdoc and came to almost the same conclusion.
He's only saying if you want to write man docs use the syntax designed for it... Ok. It's horrible to read and write but it's probably the best thing to use.
OTOH if you want to write simple plain text that humans can read and write with no difficulty at all, but can also make nice richer text if you want, markdown is great.
pandoc and ronn can also output roff man pages. Markdown is great for accessible, generic use without a need for special features. For special features or formatting, abstraction can be a hindrance. statamic, jekyll and such use YAML frontmatter for embedding metadata but it's not a full replacement for HTML or lossless HTML formats like slim, haml, pug, ace, macdom.
I always need a cheatsheet when using roff or latex because they're too much to remember if you're not using it everyday.
"Markdown is pitifully weak and powerless" because it lacks (obscure feature author wants).
If you want features, use a word processor, or LaTex, or something. Markdown is for documents that need only very basic formatting.
The future of this is probably some AI-based system where you put in raw text and tell the system "make it look good ... no, make it look more like a Medium article...optimize for SEO..."
This advice does appear to be coming from someone who writes webpages using roff... The core argument simply seems to be that markdown lacks sufficient structure to build "documents," which I agree is absolutely true and essentially part of the design.
IMO Markdown isn't intended to structure documents; it's intended to enhance plain text. If you find yourself constantly tweking at whitespace or special characters to provoke your markdown to behave, or if you are using so many features of md that you have to keep a reference handy, maybe you ought to use something different.
As an aside, I have used Front Matter (essentially a YAML header on markdown) for cases when a bit of structure or metadata is needed alongside a blob of text, and I think it strikes a great balance between writability and structure.
Markdown tables need to die in a fire though; what a wreck.
It’s even more than that - it’s a codification of plain text formatting conventions.
If you write a plain text document and you format it following markdown principles, you get a simple rich text version of your document for free. Your headings will be headings, your bullet points will be bullet points, and your code blocks will be code blocks.
Now, you can also ‘game’ markdown, writing the minimum possible plaintext to ‘trick’ it into making a pretty document while leaving the plain text ugly.
But in general, the idea of markdown is to start from ‘imagine I have a bunch of plain text files I’ve been formatting consistently for years. How can I make them look nice as rich text?’
For sure. I'd call it an excellent bad markup language. I use LogSeq daily and as a practical matter I much prefer Markdown to, say, Evernote's WYSIWYG approach, which was more of a pain to use and left me with notes so broken that they are impossible to fix. Or to this author's theoretically better system HTML, because it's more of a pain to write. Basically Markdown cares about formatting about as much as I do, which is barely.
And I think it has a lot to do with a very particular notion of good, which is something like "conceptually pleasing to someone who has mastered the space".
It’s also fast and efficient to type on the keyboard. Plus it feels very natural. Much more natural than for example html or even bbcode, when you are typing out text.
So much this. I think I must be missing something here about the context here, but even then I think it's extremely hyperbolic for the author to make the leap from "I don't like Markdown for [x]" to "Markdown is objectively bad and should never be used in any context."
Just look at some of these other examples the author lauds. I've been writing code for most of my life and I find roff's manpage to be absolutely inscrutable. I don't understand the context in which you'd need to pick between roff and Markdown, they seem like they're solving completely different problems for totally different audiences.
This is kind of absurd. Markdown has very specific use cases. For example, using any number of free apps, you can maintain a folder of notes that are human-readable, machine-parsable, that will effectively be useful forever.
You’re really gonna keep that folder of text files in “very good” LaTeX??
Comparing Markdown and LaTex is silly. One is intended for intuitive plain text input, the other is, as the author points out, almost a full postscript style programming language. I don’t know what mdoc is optimizing for, but it’s sure not intuitive.
This post feels like a rant by someone who’s just having a bad day. Not sure why it’s even on HN.
...It's a great convention on how to do common stuff in plain text. Plain text. Let me repeat: plain text.
(I'm accidentally doing "a different todo list approach" now due to it, and it is so surprisingly awesome; sorry, busy doing stuff off of my "weird todo list"!)
Markdown is phenomenal. It gives end users simple and easy to remember ways to perform the most common formatting operations but leaves the text in a state that it was be parsed by humans without an actual markdown renderer.
My text editor, KeenWrite[1] (see tutorials[3] for details), converts from Markdown to XHTML. The XHTML is then typeset using the ConTeXt typesetting software to create a PDF. The PDF is stylized using a theme[2].
What Markdown is missing, in particular flexmark-java, is a standard CommonMark extension for cross-references and citations[4].
This is a great opportunity to extol the superior text layout capabilities of Latex. In your third pdf [1], look at page 2, para starting from "No doubt...". Compare to the same rendered in plain latex [2]. Two problems that jump immediately.
* There are six word breaks in your pdf, zero in the latex version. (well, good-nature is a compound word in the original text).
* Notice the "river" [3] of spaces that runs downs from "Enfield"
I have no idea why other fixed layout engines don't adopt the superior text-layout algorithms of latex.
KeenWrite looks cool and useful; thanks for the reference.
It does appear that the real heavy lifting in this workflow is still all done by TeX, and that Markdown (with lots of extensions) is more or less a database of blobs to feed the template engine.
I would suggest the question: Is what you have at the end really a Markdown document if it has no context without KeenWrite's extensions or templates? I think the article under discussion is a bit pedantic, but I'm pretty sure the author would say that what you end up with is a KeenWrite document.
... this is close to a disqualifyingly wrong statement.
(I literally work with Markdown on a daily basis as my actual day job. Markdown really does suck.)
The only way in which (La)TeX is not context sensitive is that it's sensitive to the entire global TeX state at all times. There's no notion of grammar in TeX, _at all_. It's hard to trust the rest of the content in there after this.
Strong agree on the lack of a decent definition list notation. Strong agree on roff. Moderately strong on most of his critique Pretty strong disagree that markdown is an abominably bad choice: it's problems are fixable.
A single canonical reference and a little restraint and a dl definition would do it for me, regarding man page creation.
> [Markdown] allows embedding arbitrary HTML code, both at the block and at the flow level. That makes writing any parser for it very hard because you basically have to include a full HTML parser and then add context sensitive complications...You also have to worry about all the security caveats of HTML. For example, HTML allows embedding Javascript, so you get to implement a Javascript interpreter as well, and to secure it.
Is it just me, or is a JavaScript interpreter irrelevant to a Markdown parser?
Markdown "supports" embedded HTML but that does not mean that your chosen implementation must support it. Personally, I think it's a misfeature and wouldn't want to touch any markdown lib that tried to put too much emphasis on something like validating or sanitizing HTML and Javascript. That's a project with too much scope creep.
It is. I know of zero Markdown implementations off the top of my head that bother to parse JavaScript - if there's JS embedded in HTML embedded in Markdown, it gets passed through as a block element on the HTML side (which may or may not be parsed, either).
TFA is drawing at straws to dunk on a format they don't like.
I haven't seen anything new in this space and I just finished a project using a markdown format I invented called Tagged{Text}. I'm happy to present it here for your consideration.
In creating my blog and static site I started using Markdown but couldn't get around the limitations. So I invented a simple file format for tagging text into a tree like structure. It has a formatting style modeled after LaTeX. It has served me well (two websites and two blogs).
I call it an "agnostic markdown format" because no tags are defined ahead of time. The user defines everything and writes python filters to generate the output from the tags. I have lots of python code to parse and generate HTML. It has a macro processor, calculator, git date, and other useful tags.
The main python file is: taggedtext.py (the parser).
All the other python code are filters to generate or transform the tagged text tree into something else. For example, tt_macros.tt implements the DEFINE{} tag.
When you have a certain kind of mind, you tend to see "simplicity" in a way that might not be recognizable to others. I think Mr. Schwarze might be one of those minds, seeing his history with Free/OpenBSD.
Markdown's fantastic for generating pure HTML. However, if I had a print deliverable, or any complicated function like transclusion or conditionals, I'd maybe nudge the user to try out an alternative, Asciidoc or something else.
Why do I say that when you can do so many cool things with Markdown? Well, "so many cool things" is sort of the problem. You build up a unique Mkdwn/Extension/<Insert_Framework_Of_Choice/> stack every time you do a "cool thing", until eventually you're writing docs for what is, in effect, a bespoke parser. Knock out one block of that - say, like, your company's InfoSec department decides that technical writers having NPM is a Very Bad Idea - and your cool thing gets scaled back or broken outright. It's much better for your docs' lifecycle to use just the core of the spec, and not be dependent on a flurry of extensions and dependencies for the business of making docs.
I don't include edge uses, where extensions excel. To take one example, Mr. Rojas' excellent WireViz program (https://github.com/wireviz/WireViz). If that gets knocked out, my document still builds into PDFs.
The price you pay, of course, is a more niche ecosystem; Asciidoc tooling is maybe a tenth or a fiftieth of what's dedicated to the M*kd*n Multiverse. And of course, if you're writing simple docs that go straight to HTML without so much as thinking about a print layout, then Markdown is the easy choice.
I think the people commenting that this isn't what markdown is for should take up their argument with the people who were saying that openbsd should rewrite all the man pages in markdown.
The author refers to Markdown as "Abominable" at the end of the page.
I am always skeptical when someone has this level of disdain for any technology. The overall argument that "Markdown is bad" would be stronger if they noted the pros of Markdown, and why the pros are less valuable in aggregate than pros of other languages.
I came to the same conclusion while trying to work out a good documentation single-sourcing setup that could successfully target multiple formats like markdown, mdoc, be injected into code, etc.
I still use markdown for what it does well, but I feel like virtually every other (lightweight) markup language misses the mark as well.
Last year I started writing some posts that are about this in a very vague way (6 so far at https://t-ravis.com/room/doc/) to help order my own thinking and lay some groundwork for eventually demonstrating where a lot of them fall short.
(Caveat: I'm not suggesting anyone stop using them for any given project that doesn't need to target multiple output formats. They aren't unusable. They just all have problems that make virtually all of them difficult to use as a single source.)
For technical documentation? Sure, I see how the alternatives make more sense. But for more general use, like formatting shorter posts on forums and social media? Markdown seems quite adequate there, and dealing with any of the listed recommendations would be unbearable for many users. I’m not sure if the article was written for a very specific audience or expected to be read in a given context, or if the author overgeneralises their conclusion to all applications that a markup may have. (In the former case, it just doesn’t work as a standalone piece, in my opinion, so I don’t see much that could be said about it here.)
On a side note, the text only glosses over TeXinfo, calling it officially dead based on an e-mail from 9 years ago, while it’s had many new releases since; I’m not sure what to make of that. Would anyone have more insight into that?
This article, and many of the comments here, seem to be written from the perspective of someone who would never think to read the "source code" for a document in the original text format and thinks that the transformed document is the only one they should be looking at.
And for those folks, sure, markdown sucks.
But some of us still view source code as primary and want to "use" the docs in the same context we use when "editing" the docs.
Frankly I'm enough of a curmudgeon that I view the whole conceit of markdown (that it was a concession to the "pretty formatted docs" people that was acceptable to us README dinosaurs) as a step too far. Nothing short of writing docs in proprietary WYSIWYG editors will ever be enough for those folks, and we shouldn't have tried.
[+] [-] jakelazaroff|2 years ago|reply
Cool, let’s see what mdoc looks like:
> The following is a well-formed skeleton mdoc file for a utility "progname":
So, utterly incomprehensible. I’ll stick to Markdown, thanks![+] [-] jaylittle|2 years ago|reply
[+] [-] vanjajaja1|2 years ago|reply
[+] [-] MattPalmer1086|2 years ago|reply
He's only saying if you want to write man docs use the syntax designed for it... Ok. It's horrible to read and write but it's probably the best thing to use.
OTOH if you want to write simple plain text that humans can read and write with no difficulty at all, but can also make nice richer text if you want, markdown is great.
[+] [-] jochem9|2 years ago|reply
[+] [-] 1letterunixname|2 years ago|reply
I always need a cheatsheet when using roff or latex because they're too much to remember if you're not using it everyday.
[+] [-] draw_down|2 years ago|reply
[deleted]
[+] [-] Animats|2 years ago|reply
If you want features, use a word processor, or LaTex, or something. Markdown is for documents that need only very basic formatting.
The future of this is probably some AI-based system where you put in raw text and tell the system "make it look good ... no, make it look more like a Medium article...optimize for SEO..."
[+] [-] geitir|2 years ago|reply
[+] [-] nomel|2 years ago|reply
This "boring" type of use is what makes me so damn excited for AI: reduction of low skill monotony.
[+] [-] peteradio|2 years ago|reply
[+] [-] camdenreslink|2 years ago|reply
[+] [-] gorkish|2 years ago|reply
IMO Markdown isn't intended to structure documents; it's intended to enhance plain text. If you find yourself constantly tweking at whitespace or special characters to provoke your markdown to behave, or if you are using so many features of md that you have to keep a reference handy, maybe you ought to use something different.
As an aside, I have used Front Matter (essentially a YAML header on markdown) for cases when a bit of structure or metadata is needed alongside a blob of text, and I think it strikes a great balance between writability and structure.
Markdown tables need to die in a fire though; what a wreck.
[+] [-] agildehaus|2 years ago|reply
[+] [-] jameshart|2 years ago|reply
If you write a plain text document and you format it following markdown principles, you get a simple rich text version of your document for free. Your headings will be headings, your bullet points will be bullet points, and your code blocks will be code blocks.
Now, you can also ‘game’ markdown, writing the minimum possible plaintext to ‘trick’ it into making a pretty document while leaving the plain text ugly.
But in general, the idea of markdown is to start from ‘imagine I have a bunch of plain text files I’ve been formatting consistently for years. How can I make them look nice as rich text?’
[+] [-] wpietri|2 years ago|reply
I'll note this tension has a long history in CS: https://en.wikipedia.org/wiki/Worse_is_better
And I think it has a lot to do with a very particular notion of good, which is something like "conceptually pleasing to someone who has mastered the space".
[+] [-] codetrotter|2 years ago|reply
[+] [-] mmcclure|2 years ago|reply
Just look at some of these other examples the author lauds. I've been writing code for most of my life and I find roff's manpage to be absolutely inscrutable. I don't understand the context in which you'd need to pick between roff and Markdown, they seem like they're solving completely different problems for totally different audiences.
[+] [-] kazinator|2 years ago|reply
Yet, I had to crank out diagrams recently, and found every single program I knew had become enshittified to the point of not being usable.
I got the job done with asciiflow box-and-arrow diagrams, pasted into a word processing document as monospaced-font paragraphs.
[+] [-] unknown|2 years ago|reply
[deleted]
[+] [-] brigleb|2 years ago|reply
You’re really gonna keep that folder of text files in “very good” LaTeX??
[+] [-] 1letterunixname|2 years ago|reply
Nits:
Markdown is general purpose but limited. It's a big improvement on plain text files. Thank you Aaron Swartz (RIP) and John Gruber.
I sure don't hand-code doc directly in PDF or PostScript formats, although people used to do the latter before TeX was ubiquitous.
[+] [-] t8sr|2 years ago|reply
This post feels like a rant by someone who’s just having a bad day. Not sure why it’s even on HN.
[+] [-] drbig|2 years ago|reply
...It's a great convention on how to do common stuff in plain text. Plain text. Let me repeat: plain text.
(I'm accidentally doing "a different todo list approach" now due to it, and it is so surprisingly awesome; sorry, busy doing stuff off of my "weird todo list"!)
[+] [-] jen729w|2 years ago|reply
The clue being right there in the name.
[+] [-] gavinhoward|2 years ago|reply
[+] [-] listenallyall|2 years ago|reply
[+] [-] jaylittle|2 years ago|reply
Markdown is phenomenal. It gives end users simple and easy to remember ways to perform the most common formatting operations but leaves the text in a state that it was be parsed by humans without an actual markdown renderer.
[+] [-] frizlab|2 years ago|reply
[+] [-] scarface_74|2 years ago|reply
https://daringfireball.net/projects/markdown/
[+] [-] trav4225|2 years ago|reply
[+] [-] thangalin|2 years ago|reply
* https://impacts.to/downloads/lowres/impacts.pdf
* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...
* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
My text editor, KeenWrite[1] (see tutorials[3] for details), converts from Markdown to XHTML. The XHTML is then typeset using the ConTeXt typesetting software to create a PDF. The PDF is stylized using a theme[2].
What Markdown is missing, in particular flexmark-java, is a standard CommonMark extension for cross-references and citations[4].
[1]: https://github.com/DaveJarvis/keenwrite
[2]: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...
[3]: https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9...
[4]: https://talk.commonmark.org/t/cross-references-and-citations...
[+] [-] abdullahkhalids|2 years ago|reply
* There are six word breaks in your pdf, zero in the latex version. (well, good-nature is a compound word in the original text).
* Notice the "river" [3] of spaces that runs downs from "Enfield"
I have no idea why other fixed layout engines don't adopt the superior text-layout algorithms of latex.
[1] https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
[2] https://i.imgur.com/Rs7ai0G.png
[3] https://en.wikipedia.org/wiki/River_(typography)
[+] [-] gorkish|2 years ago|reply
It does appear that the real heavy lifting in this workflow is still all done by TeX, and that Markdown (with lots of extensions) is more or less a database of blobs to feed the template engine.
I would suggest the question: Is what you have at the end really a Markdown document if it has no context without KeenWrite's extensions or templates? I think the article under discussion is a bit pedantic, but I'm pretty sure the author would say that what you end up with is a KeenWrite document.
[+] [-] the-printer|2 years ago|reply
[+] [-] cscheid|2 years ago|reply
> Little context sensitivity
... this is close to a disqualifyingly wrong statement.
(I literally work with Markdown on a daily basis as my actual day job. Markdown really does suck.)
The only way in which (La)TeX is not context sensitive is that it's sensitive to the entire global TeX state at all times. There's no notion of grammar in TeX, _at all_. It's hard to trust the rest of the content in there after this.
[+] [-] ggm|2 years ago|reply
A single canonical reference and a little restraint and a dl definition would do it for me, regarding man page creation.
[+] [-] deanebarker|2 years ago|reply
https://commonmark.org/
[+] [-] paulddraper|2 years ago|reply
Is it just me, or is a JavaScript interpreter irrelevant to a Markdown parser?
[+] [-] gorkish|2 years ago|reply
[+] [-] klardotsh|2 years ago|reply
TFA is drawing at straws to dunk on a format they don't like.
[+] [-] dwh452|2 years ago|reply
In creating my blog and static site I started using Markdown but couldn't get around the limitations. So I invented a simple file format for tagging text into a tree like structure. It has a formatting style modeled after LaTeX. It has served me well (two websites and two blogs).
I call it an "agnostic markdown format" because no tags are defined ahead of time. The user defines everything and writes python filters to generate the output from the tags. I have lots of python code to parse and generate HTML. It has a macro processor, calculator, git date, and other useful tags.
Here is an article about Tagged{Text}: https://etcutmp.com/taggedtext.html Another website built using this format: https://etcutmp.com/evolve5 Source Code: https://github.com/kjs452/tagged_text Source Code for the second website: https://github.com/kjs452/Evolve5Help
The main python file is: taggedtext.py (the parser). All the other python code are filters to generate or transform the tagged text tree into something else. For example, tt_macros.tt implements the DEFINE{} tag.
[+] [-] MilStdJunkie|2 years ago|reply
Markdown's fantastic for generating pure HTML. However, if I had a print deliverable, or any complicated function like transclusion or conditionals, I'd maybe nudge the user to try out an alternative, Asciidoc or something else.
Why do I say that when you can do so many cool things with Markdown? Well, "so many cool things" is sort of the problem. You build up a unique Mkdwn/Extension/<Insert_Framework_Of_Choice/> stack every time you do a "cool thing", until eventually you're writing docs for what is, in effect, a bespoke parser. Knock out one block of that - say, like, your company's InfoSec department decides that technical writers having NPM is a Very Bad Idea - and your cool thing gets scaled back or broken outright. It's much better for your docs' lifecycle to use just the core of the spec, and not be dependent on a flurry of extensions and dependencies for the business of making docs.
I don't include edge uses, where extensions excel. To take one example, Mr. Rojas' excellent WireViz program (https://github.com/wireviz/WireViz). If that gets knocked out, my document still builds into PDFs.
The price you pay, of course, is a more niche ecosystem; Asciidoc tooling is maybe a tenth or a fiftieth of what's dedicated to the M*kd*n Multiverse. And of course, if you're writing simple docs that go straight to HTML without so much as thinking about a print layout, then Markdown is the easy choice.
[+] [-] tedunangst|2 years ago|reply
[+] [-] ssgodderidge|2 years ago|reply
The author refers to Markdown as "Abominable" at the end of the page.
I am always skeptical when someone has this level of disdain for any technology. The overall argument that "Markdown is bad" would be stronger if they noted the pros of Markdown, and why the pros are less valuable in aggregate than pros of other languages.
[+] [-] abathur|2 years ago|reply
I still use markdown for what it does well, but I feel like virtually every other (lightweight) markup language misses the mark as well.
Last year I started writing some posts that are about this in a very vague way (6 so far at https://t-ravis.com/room/doc/) to help order my own thinking and lay some groundwork for eventually demonstrating where a lot of them fall short.
(Caveat: I'm not suggesting anyone stop using them for any given project that doesn't need to target multiple output formats. They aren't unusable. They just all have problems that make virtually all of them difficult to use as a single source.)
[+] [-] F3nd0|2 years ago|reply
On a side note, the text only glosses over TeXinfo, calling it officially dead based on an e-mail from 9 years ago, while it’s had many new releases since; I’m not sure what to make of that. Would anyone have more insight into that?
[+] [-] thangalin|2 years ago|reply
How's this?
https://whitemagicsoftware.com/softcover/technical.pdf
[+] [-] ajross|2 years ago|reply
And for those folks, sure, markdown sucks.
But some of us still view source code as primary and want to "use" the docs in the same context we use when "editing" the docs.
Frankly I'm enough of a curmudgeon that I view the whole conceit of markdown (that it was a concession to the "pretty formatted docs" people that was acceptable to us README dinosaurs) as a step too far. Nothing short of writing docs in proprietary WYSIWYG editors will ever be enough for those folks, and we shouldn't have tried.