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.
(2014 updated 2021) the original OpenBSD article is (2017) and there's still no good canonical DL instantiation -commonmark goes into "do it in HTML" which is .. FAIL in my book.
So, a "standard" which has been continuously revised since 2014 and doesn't have definition lists except as "use HTML"
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.
Markdown is an authoring language (it's easy to write) rather than a publishing language (like XML, which is mostly replaces, which sucks to write in).
> It’s also fast and efficient to type on the keyboard. Plus it feels very natural.
If you are solely an English writer then yes. Using md with some languages will quickly turn you into its hater. Certain formatting symbols aren’t easily accessible in some layouts, like backticks for code or ^ for superscript. Some symbols require extra keystrokes like ~ in german. Some layouts will require finger yoga exercises. Basically, any other text markups based on English (including LaTeX) are unfriendly to other languages. Thus an abnormal popularity of md across the apps makes them much less friendly for non-English users. Mobile typing pushes this pain to another level.
Yeah. My native language has some very awkward placements of certain symbols as well actually. But I chose to sacrifice the letters æ, ø, å years ago by switching to using US-based layouts on my computers. Sometimes I use Dvorak layouts (even have a custom one I made for my mechanical keyboard that I sometimes use). Most of the time I write on a computer in recent years has been using the keyboard on my MacBook Pro computers with just US QWERTY. I very rarely type anything in my native tongue on the computers. Mainly just on the phone. And I am 97% sure that the times I need æ ø å on my macOS laptops I can long-press or option click some of the related characters like a and o.
For a while, when I originally switched away from my native language QWERTY variant, I would sometimes need æ ø å on the computer and I would Google aelig oslash and aring respectively and find the symbols for those letters that way :p
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?’
I was about to say; even before I knew markdown, I was using a lot of its conventions informally. I was using # to denote headers, and surrounding things with asterisks to emphasize them, using > to denote quotes. When I found out about markdown, it took me about ten minutes to learn because it was stuff I was largely already doing.
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".
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.
I thought so as well, until I used it. And then I realised that I'd rather go back to OneNote than use markdown. It's just too limited without introducing HTML.
Eventually settled on using ms instead of OneNote, gets me that local goodness and beautiful PDFs but also allows me to define things and make it a bit more domain-specific whenever needed. Used it for several documents at work, got compliments on how good they looked. Wild for a relatively limited system from the 70's.
> Eventually settled on using ms instead of OneNote
This name is too short to Google, and Google thinks I am referring to Microsoft, or even OneNote, when I search for it. Do you have a link to this “ms” tool from the 1970s?
...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"!)
Instead of thinking in terms of "list items" think in terms of... days.
There is only so much that can be done in a day but it is very reassuring to see just at a glance what was actually done. Also, this makes never-ending lists pruning super easy and peaceful - "if this item has been carried over for a month and I haven't touched it then it means it's not needed".
And all I use for this is gedit (which is notepad.exe with syntax highlight if you so desire) and have the .txt files sync to my Nextcloud instance.
(Note: So far I use it only for personal projects mixed with day-to-day chores.)
I never saw the attraction to Markdown. I especially despised the end a line with two or more invisible characters to insert a line break.
If it wasn't for Github, I probably wouldn't be using it at all. There were so many Wiki markup dialects and a Wiki Creole that could serve as a base to make a more featured popular one.
It's not my favorite feature by any means but linebreaks are almost always an issue: practically all Markdown-ish or wikitext-ish formats don't give significance to single line breaks to allow hard-wrapping the source without affecting its rendering, which doesn't leave you with many "nice" options for actually doing explicit linebreaks when you do want them.
I've seen ones where you put something like a plus at the end of the line, the spaces from Markdown, or something like MediaWiki's format where you just can't do it without falling back to writing in some explicit HTML.
I primarily use Markdown in all my note-taking and blog-writing. It’s fine for it, for me. But lots of these criticisms of Markdown resonated with me. I know it’s a rough analogy, but I’m waiting for Markdown’s “TypeScript”, so to speak: A markup language that is a superset of Markdown, but adds a lot of value by addressing some (the more the better) of the usability and predictability deficiencies pointed out in this blog post.
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.)
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.
"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..."
I dunno if that what you meant, but it was pretty much designed so that the people that want to complicate everything go there complicating it, while the people that want to write something useful can just take complicators' work, use it, and raise their shoulders at every objection repeating "you are the one that designed it this way".
The original TeX doesn't work this way. That's why people don't collaborate directly in it.
I am with GP. When using LaTeX I was happy that it was difficult to easily change things. I had a thesis to write and took the solution that would create something good (even if I would not agree) and prevent me from easily choosing fonts for headers etc.
The keyword here is "easily". Of course I could learn the language and go wild. But, hey, I had a thesis to write so I had to make choices: PhD or fancy headers.
Nawh, it was invented to reinvent PostScript and create a barrier-to-entry to academic publishing.
Seriously, I still can't find a decent WSYSIWYG latex editor with the UX of the legacy Word equation editor or a graphing calculator. The closest I found was [0].
I agree. I had the terrible idea to build a Markdown library in Prolog and I discovered how it's full of quirks. There's CommonMark which tries to be more precise but they have already published at least 25 versions of the spec (and still is not 1.0) and some things are just defined by an algorithm.
While I was doing that, I found Djot, a language very similar to Markdown (a bit more verbose sometimes) but much better specified (and with some additional features). So I did a Djot library in Prolog too.
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.
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??
My only complaint with markdown is generally whoever is rendering it chooses terrible values for line heights. I'm not sure if this is part of the spec, but it looks terrible.
Here [1] is an example. The dividers underneath headers should have less top padding, so that it's visually associated with the header and not ambiguously associated with either the body or header (or neither).
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.
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.
> There are six word breaks in your pdf, zero in the latex version. (well, good-nature is a compound word in the original text).
I use ConTeXt. ConTeXt uses the same Knuth-Plass algorithm for line breaks as LaTeX. I've allowed ConTeXt to hyphenate liberally. There is a setting to control hyphenation. See lesshyphenation, morehyphenation:
> Notice the "river" [3] of spaces that runs downs from "Enfield"
ConTeXt probably has tweaks for this as well. Keep in mind, I typeset Jekyll and Hyde in 2020 and am not a ConTeXt expert; ConTeXt has had countless improvements since then.
> adopt the superior text-layout algorithms of latex
Pretty sure ConTeXt is capable of producing the same quality of document as 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.
I've kept compatibility with pandoc (CommonMark) and knitr a priority; I wrote KeenWrite to replace a shell script that was calling out to those software packages. My Typesetting Markdown blog posts dive into that script and programs:
Further, KeenWrite only supports plain TeX, which means that the typesetting system can be any software that is TeX-compatible: LaTeX, ConTeXt, LuaTeX, ExTeX, KaTeX, etc.
Seriously though I do like the workflow you've put together with KeenWrite. I have a potential application where it might be a great fit to replace some markdown->pdf workflows I have built. In my case, I use a Front Matter header to pass structured data along with the markdown to generate templated HTML which can then be "typeset" with the extensions provided by HTMLDOC or wkhtmltopdf.
Thanks again for posting and replying. Pleased to make your acquaintance.
> Thanks again for posting and replying. Pleased to make your acquaintance.
Likewise!
> I use a Front Matter header to pass structured data
The impetus for developing that shell script (ergo KeenWrite) was using variables in documents. KeenWrite injects structured, interpolated YAML strings back into documents by replacing Moustache syntax (or `r# ...` syntax for R docs). This means that the same structured data can be reused for multiple documents, allowing for single sources of truth and a clean separation of content from presentation. Also, variables can be used in diagrams.
As for Front Matter, data can be passed in from the command line[1]:
Under the hood, KeenWrite places the metadata inside the intermediate XHTML document as <meta> tags inside the <head>. These are parsed by ConTeXt using an XSLT-like syntax that converts them into TeX instructions[2].
Do post any questions you may have on the discussions forum[3].
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 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.
> 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!
Agreed! 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.
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.
Markdown 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)
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.
... 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.
The author's website is designed to look like the OpenBSD manual's web page. This is a blogpost about mandoc/markdown in the form of a man page...for mandoc...very clever.
113 comments
[ 0.27 ms ] story [ 185 ms ] threadA single canonical reference and a little restraint and a dl definition would do it for me, regarding man page creation.
https://commonmark.org/
So, a "standard" which has been continuously revised since 2014 and doesn't have definition lists except as "use HTML"
Its mostly successful, but not entirely. Wish Gruber would just link to that instead of his old, bugger, out of date spec.
If you are solely an English writer then yes. Using md with some languages will quickly turn you into its hater. Certain formatting symbols aren’t easily accessible in some layouts, like backticks for code or ^ for superscript. Some symbols require extra keystrokes like ~ in german. Some layouts will require finger yoga exercises. Basically, any other text markups based on English (including LaTeX) are unfriendly to other languages. Thus an abnormal popularity of md across the apps makes them much less friendly for non-English users. Mobile typing pushes this pain to another level.
For a while, when I originally switched away from my native language QWERTY variant, I would sometimes need æ ø å on the computer and I would Google aelig oslash and aring respectively and find the symbols for those letters that way :p
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.
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?’
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".
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.
Eventually settled on using ms instead of OneNote, gets me that local goodness and beautiful PDFs but also allows me to define things and make it a bit more domain-specific whenever needed. Used it for several documents at work, got compliments on how good they looked. Wild for a relatively limited system from the 70's.
This name is too short to Google, and Google thinks I am referring to Microsoft, or even OneNote, when I search for it. Do you have a link to this “ms” tool from the 1970s?
...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"!)
The clue being right there in the name.
There is only so much that can be done in a day but it is very reassuring to see just at a glance what was actually done. Also, this makes never-ending lists pruning super easy and peaceful - "if this item has been carried over for a month and I haven't touched it then it means it's not needed".
And all I use for this is gedit (which is notepad.exe with syntax highlight if you so desire) and have the .txt files sync to my Nextcloud instance.
(Note: So far I use it only for personal projects mixed with day-to-day chores.)
If it wasn't for Github, I probably wouldn't be using it at all. There were so many Wiki markup dialects and a Wiki Creole that could serve as a base to make a more featured popular one.
I love Markdown, but I also hate this. The only benefit is that is discourages people from messing with line breaks.
I've seen ones where you put something like a plus at the end of the line, the spaces from Markdown, or something like MediaWiki's format where you just can't do it without falling back to writing in some explicit HTML.
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.)
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.
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..."
The original TeX doesn't work this way. That's why people don't collaborate directly in it.
The keyword here is "easily". Of course I could learn the language and go wild. But, hey, I had a thesis to write so I had to make choices: PhD or fancy headers.
Seriously, I still can't find a decent WSYSIWYG latex editor with the UX of the legacy Word equation editor or a graphing calculator. The closest I found was [0].
0. https://latexeditor.lagrida.com
This "boring" type of use is what makes me so damn excited for AI: reduction of low skill monotony.
While I was doing that, I found Djot, a language very similar to Markdown (a bit more verbose sometimes) but much better specified (and with some additional features). So I did a Djot library in Prolog too.
This post feels like a rant by someone who’s just having a bad day. Not sure why it’s even on HN.
You’re really gonna keep that folder of text files in “very good” LaTeX??
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.
Here [1] is an example. The dividers underneath headers should have less top padding, so that it's visually associated with the header and not ambiguously associated with either the body or header (or neither).
[1] https://docs.github.com/assets/cb-55935/mw-1440/images/help/...
While I agree with you about GitHub's dividers being too low, I think it's GitHub's problem. Not related to Markdown.
https://daringfireball.net/projects/markdown/
* 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...
https://github.com/DaveJarvis/keenwrite#other
If that doesn't work for you, please open an issue and describe what you'd like for MacOS.
* 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)
I use ConTeXt. ConTeXt uses the same Knuth-Plass algorithm for line breaks as LaTeX. I've allowed ConTeXt to hyphenate liberally. There is a setting to control hyphenation. See lesshyphenation, morehyphenation:
https://wiki.contextgarden.net/Command/setupalign
> Notice the "river" [3] of spaces that runs downs from "Enfield"
ConTeXt probably has tweaks for this as well. Keep in mind, I typeset Jekyll and Hyde in 2020 and am not a ConTeXt expert; ConTeXt has had countless improvements since then.
> adopt the superior text-layout algorithms of latex
Pretty sure ConTeXt is capable of producing the same quality of document as LaTeX.
* https://wiki.contextgarden.net/Documentation
* https://tex.stackexchange.com/questions/36/differences-betwe...
* https://tug.org/levels.html
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.
Documents written in KeenWrite can be typeset using tools that already exist:
* https://pandoc.org/
* https://yihui.org/knitr/
* https://github.com/jfisteus/html2xhtml
I've kept compatibility with pandoc (CommonMark) and knitr a priority; I wrote KeenWrite to replace a shell script that was calling out to those software packages. My Typesetting Markdown blog posts dive into that script and programs:
https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow...
Further, KeenWrite only supports plain TeX, which means that the typesetting system can be any software that is TeX-compatible: LaTeX, ConTeXt, LuaTeX, ExTeX, KaTeX, etc.
Seriously though I do like the workflow you've put together with KeenWrite. I have a potential application where it might be a great fit to replace some markdown->pdf workflows I have built. In my case, I use a Front Matter header to pass structured data along with the markdown to generate templated HTML which can then be "typeset" with the extensions provided by HTMLDOC or wkhtmltopdf.
Thanks again for posting and replying. Pleased to make your acquaintance.
Likewise!
> I use a Front Matter header to pass structured data
The impetus for developing that shell script (ergo KeenWrite) was using variables in documents. KeenWrite injects structured, interpolated YAML strings back into documents by replacing Moustache syntax (or `r# ...` syntax for R docs). This means that the same structured data can be reused for multiple documents, allowing for single sources of truth and a clean separation of content from presentation. Also, variables can be used in diagrams.
As for Front Matter, data can be passed in from the command line[1]:
Under the hood, KeenWrite places the metadata inside the intermediate XHTML document as <meta> tags inside the <head>. These are parsed by ConTeXt using an XSLT-like syntax that converts them into TeX instructions[2].Do post any questions you may have on the discussions forum[3].
[1]: https://github.com/DaveJarvis/keenwrite/blob/main/docs/cmd.m...
[2]: https://github.com/DaveJarvis/keenwrite-themes/blob/main/xht...
[3]: https://github.com/DaveJarvis/keenwrite/discussions/
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?
How's this?
https://whitemagicsoftware.com/softcover/technical.pdf
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.
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!> 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.
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.
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)
I always need a cheatsheet when using roff or latex because they're too much to remember if you're not using it everyday.
> 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.
The submitted URL appears to be the man page for a "mandoc" command.
http://schwarze.bsd.lv/mandoc.7
Also apparently the submission title needs (2017).