4 ms·
> 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 t
by jakelazaroff 3y ago
> 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!
- jaylittle 3y agoIt will never cease to amaze me how out of touch some technical people are... including the author of this markdown rant.
- devinprater 3y agoAnd the person that wanted to use PDF as web pages instead of HTML.
- apple4ever 3y agoAgreed! I think this is the main problem with Markdown: > The most official reference manual for markdown is the original one written by John Gruber in 2004. It is unmaintained since that time and leaves various ambiguities, such that different parsers tend to parse input somewhat differently in detail. Its ridiculous that it hasn't been updated, though there have been some attempts.
- draw_down 3y ago[dead]
- MattPalmer1086 3y agoYeah, 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.
- kaba0 3y agoMarkdown obviously has a place and I quite like it, but if someone wants more expressiveness, I think Typst’s language does a very good job of being similar to markdown, yet giving you everything LaTeX can. Unfortunately it doesn’t yet have an HTML export version (I would be okay with a simplified one as well for now, like only do paragraphs, emphasis, etc)
- MattPalmer1086 3y agoDidn't know about typst. Looks quite nice, I like that you can embed LaTeX style maths in it, but it is still quite readable.
- pepa65 3y agoThank you for bringing up Typst, it is completely awesome, SO useful.
- vanjajaja1 3y agoYou learn markdown by looking at a half page example for 5 minutes, you learn this abomination by studying a spec document. bad
- 1letterunixname 3y agopandoc 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.
- jochem9 3y agoThis is exactly what markdown achieves: comprehensible even when it is not rendered. Yet the author completely ignores that feature.