11 ms·
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offe
by Arainach 2y ago
>To which I say, are you really going to avoid using a good tool just because it makes you puke? Because looking at it makes your stomach churn? Because it offends every fiber of your being?"
Yes. A thousand times yes. Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. How easy it is to parse doesn't matter. How easy it is to extend is largely irrelevant.
Markdown may or may not be the best tool for writing a book, but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax.
I don't want to write a book. If I did I'd use LaTeX before RST. I want something to take notes, make quick documentation and thread comments.
- michaelcampbell 2y agoIf you'd read past that, the author says "yes, those are good reasons, I would too".
- pclmulqdq 2y agoI am probably in the 90th percentile of TeX users, but I have to say that it's hard for me to think that there's much space between markdown and TeX for another typesetting language. Markdown is easy to write and read but very constrained, while TeX is a bit harder and essentially infinitely flexible. The biggest issue I have seen with TeX is a people problem: people frequently write spaghetti TeX with horrible style. This is terrible, but it is not actually a language issue. Writing it with a "docs are code" mindset can produce some very clean results. The second biggest issue is that there isn't a good TeX -> HTML compiler.
- slaymaker1907 2y agoYou should check out Scribble which uses Racket. It has a bunch of different renderers including HTML and Markdown. However, unlike Markdown, you can easily write extensions for it in Lisp, even within the document itself. https://docs.racket-lang.org/scribble/running.html#%28part._.Extra_and_.Format-.Specific_.Files%29 https://docs.racket-lang.org/scribble/running.html#%28part._... I suppose that makes it inappropriate for something like rendering comments, but it's a great way to write documents. I used it a lot for writing papers since there's a lot less boilerplate and was much easier to use than TeX.
- conaclos 2y agoMaybe Typst (https://typst.app/ https://typst.app/) is a good in-between?
- josephg 2y agoI used typst for a recent project and I love it. It’s essentially all the power of latex but with modern sensibilities. And it’s a cute little programming language - with support for variables, functions, json data loading, 3rd party libraries, and all sorts of other nice to haves. I just wish the typst compiler had a way to output html. It would be perfect for making online documentation and blog posts.
- enema_bag_jones 2y agoI see typst mentions HTML output, is this only possible with something besides the the CLI? It looks very cool, going to try it out at the first opportunity.
- flokl 2y agoHTML output with Typst isn't possible yet, but it has a high priority.
- reknih 2y agoFor the upcoming release, we decided to prioritize print layout and the shortcomings we have there. The release after (think late fall) will focus on HTML and accessible output. The plan is to create a turn-key solution for technical writing, docs, and document automation.
- josephg 2y agoThankyou for your work! It’s a delight.
- deleted 2y ago[deleted]
- 2y ago
- nrr 2y ago"The second biggest issue is that there isn't a good TeX -> HTML compiler." This is the crux of the problem in using just TeX for writing books: it focuses on producing camera-ready output at the expense of literally everything else. reStructuredText isn't itself a typesetting language. It's meant to be something of an interposer between the semantic meaning of what you're writing and the thing that does the typesetting. The hope is that it, unlike something heavily constrained like Markdown, gives you the tools to capture that semantic meaning and transform it into something that can be typeset. Like, the goal isn't to throw out TeX. The goal is to be able to target TeX as a typesetter along with Web browsers and e-book readers and even things like GNU info and troff without having to rewrite the content wholesale to fit each one.
- pclmulqdq 2y agoPersonally, I would rather just have TeX itself target the web rather than wedging another layer into the typesetting stack. As far as I know, other than the sheer size of the language, there is nothing fundamental stopping someone (I guess me, eventually) from writing "htmlatex." Modern web pages are already designed with "camera ready" in mind, essentially with browser width being the only thing that changes layout.
- nrr 2y agoMy point is more that TeX is a typesetter just as a Web browser is. They're incompatible typesetting systems with wildly different command languages.
- justincormack 2y agoI think the poster above wants to run TeX in js to format the text. I have seen a bunch of hyphenation and suchlike stretching back years not sure about running a full engine.
- bitwize 2y agoTeX is old and busted; Typst is the new hotness. Written in Rust, too!
- pclmulqdq 2y ago"Written in Rust" matters to very few customers of your office webapp. And you should add that it is $8/month for an online platform, not free or self-hosted.
- __mharrison__ 2y agoWhat advice do you have for writing "docs are code" LaTeX? I find LaTeX to be the lesser of evils when creating PDFs. However, I rarely deal with LaTeX issues these days because all of the pain points have been patched away in my tooling that converts md to tex. However, I keep thinking something more modern or faster (like Typst) might make my life as an author easier. Compiling LaTeX with tools like rubber is still painful and slow.
- pclmulqdq 2y agoA few things: 1. Separate each part of a document into different TeX files and include them in the main document. Each file should be a separate unit of the work. Only compile the main document when you need to. 2. Generally write with readability in mind and use newlines and other whitespace in the source a lot more than you think you should. 3. If you have common boilerplate that you frequently use at the top of docs, make your own package(s) for those commands and maintain that separately. 4. Refs and labels everywhere you possibly can. Also, prefixing your label names helps a lot, so \label{clouds} on a picture of clouds becomes \label{fig:clouds}. If you are writing a book, and this is the chapter on the sky, consider \label{fig:sky:clouds}.
- __mharrison__ 2y agoAwesome. Can you point to a repository with an example? Also, is there a book that you would recommend for learning LaTeX?
- pclmulqdq 2y agoOverleaf has several examples that are not bad. I am currently working on a book and the Krantz template is a pretty decent example of how you might structure things (although the package itself is total spaghetti). The ACM and IEEE paper examples are also both OK, but are short so they cut some corners. I'm not sure if there is a good book on LaTeX, ironically.
- 2y ago
- red_admiral 2y agoMy problem with the TeX ecosystem is it's so non-modular. Bring in this package to add a new font with some extra dingbats, and suddenly you lose proper linebreaking inside boxed environments. And so on.
- bilater 2y agoyup - my knee jerk reaction at seeing the first couple of samples was to recoil. Great if it works for ppl but I'm gonna stick with markdown.
- bityard 2y agoI thought Markdown was clearly very silly back when it started gaining traction amongst developer types. There were already so many other better options--even at the time--for plaintext-to-formatted document markup languages.) But still, developers were designing whole apps (CMSes, productivity apps, document management, etc) and plugins around Markdown, sometimes as businesses. But then I realized, after using it in some apps, that wasn't really what Markdown was about. Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. The amount of formatting it supports is small _on purpose_, so that it fits in your brain and doesn't require a toolbar to use. It is _meant_ for things like comment fields, chat programs, commit messages, and so on. Maybe even blog articles. But it certainly is not something you'd want for writing the documentation for an enterprise-grade product. These days, I write Markdown even in place where it will never be rendered into HTML. Because it's quite readable as-is. (And I wish HN supported it.)
- packetlost 2y ago> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product. I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables. Most enterprise web applications would probably be completely fine with just markdown-based docs.
- paholg 2y agoI think a good example is all of the wonderful documentation that's been created with mdBook. Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that. https://github.com/rust-lang/mdBook https://github.com/rust-lang/mdBook
- steveklabnik 2y agoCarol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print. That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.
- sureglymop 2y agoAnd it actually can be easily extended with custom blocks ( ::: ). https://github.com/vokimon/markdown-customblocks https://github.com/vokimon/markdown-customblocks
- edgarvaldes 2y agoThe very next paragraph in TFA agrees with you: >...Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.
- thomascgalvin 2y agoI have used markdown to write books, and it worked just fine. Now, these were novels, not technical documents, but I never encountered something that couldn't be solved with markdown plus some occasional HTML. I've also generated quite a bit of technical documentation using markdown, and Pandoc's extensions[1] allow you to include pretty much any formatting you might require, complicated math and syntax highlighted code blocks included. That markdown can then be transformed into HTML, a Word doc, a ePub, a PDF ... There needs to be a very compelling reason for me to reach for something other than markdown. [1] https://pandoc.org/MANUAL.html https://pandoc.org/MANUAL.html
- bluGill 2y agoMost novels don't need anything more complex than a link to the next chapter at the end of the page. Maybe bold text, but a lot get by without. As such markdown will work for most. I've seen some novels with some really complex formatting, but those are rare (I read a lot of litRPG and still call them rare). However I mostly write technical documentation and I often hit limits of things markdown cannot do even though my documents are much shorter than a novel.
- zelphirkalt 2y agoPandoc is a great thing! However, lets not mix up Pandoc Markdown with standard Markdown. Pandoc Markdown intentionally adds features, that make it more suitable for academic writing, I believe.
- thangalin 2y agoHere are some Markdown books I've crafted: * https://whitemagicsoftware.com/softcover/technical.pdf https://whitemagicsoftware.com/softcover/technical.pdf * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf * https://whitemagicsoftware.com/softcover/jekyll-hyde.pdf https://whitemagicsoftware.com/softcover/jekyll-hyde.pdf My blog describes shell scripts to use pandoc and knitr for converting Markdown to PDF: https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/ https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdow... I wrote a FOSS GUI/CLI cross-platform desktop application to replace those shell scripts: * https://keenwrite.com https://keenwrite.com * https://keenwrite.com/screenshots.html https://keenwrite.com/screenshots.html * https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9KWzPIoWZMKu_ https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9... I'm using KeenWrite to write a sci-fi novel and can produce a standard manuscript format in seconds (because the content is kept separate from the presentation). Regarding technical documentation, I extended Markdown in KeenWrite with a consistent cross-reference syntax for tables, figures, equations, etc. * https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/references.md https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/ref...
- ajross 2y ago> Because the biggest advantage of Markdown is that it's easy to read, and its second-biggest advantage is that it's easy to write. I'd go so far as to flip those two. By far, it's more important to ensure that documentation can be easily written (the raisin d'etre of MD) than it is to optimize for the job of the people trying to collate/edit/format/improve/maintain the documentation (something that RST speaks to, primarily). Because the primarily failure mode in this space is not that we have imperfectly edited documentation. It's that we lack docs at all, because the hackers didn't understand the doc tools. In Zephyr, we use RST. And... it's fine. I've made my peace with it. But "please write some docs" is a routine comment in review, and in my experience many-probably-most contributors just don't know how and don't want to take the time to learn. The barrier to markdown would be much, much lower.
- philistine 2y ago> I don't want to write a book. If I did I'd use LaTeX before RST. 100 times yes. Markdown for light styling. LaTeX for anything else. The next revolution in standardized text parsers will not come from replacing Markdown, but from replacing LaTeX.
- lapinot 2y agoEvery heard about https://typst.app/ https://typst.app/?
- philistine 2y agoI don’t think the global standard of scientific paper writing will be replaced by something that has a pricing tab at the top of the page.
- yencabulator 2y agohttps://github.com/typst/typst https://github.com/typst/typst
- qwerty456127 2y ago> Because the biggest advantage of Markdown is that it's easy to read Do you really read Markdown in plain text editors? I only do occasionally (nevertheless I'm glad I can). Most of the times I use tools like Obsidian, Typora, Markdown Monster etc. HTML is just too bad for plain source reading relatively to Markdown and too complex for reliable mapping between what it is looks, what it means and what it is. This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have. There certainly are cases where Makrdown seems the best choice - wherever simple plaintext editors are going to be used often. Nevertheless I doubt Markdown is the best choice for tools like Obsidian - perhaps people working on new projects of this kind should also take a look at rST or AsciiDoc.
- riidom 2y agoI'm with you on that, I can think of one counter example though, and that is when you have to write your MD in something like VS Code. Which uses the old-fashioned approach of source code pane and render pane. I strongly dislike that and usually try to get away with source-code view only. To be fair, they use a tiny bit of coloring, so it's not 100% plain text. And the better solution is to write your MD in any other MD editor except VSC, of course.
- red_admiral 2y agoWhen you're putting documentation in the same commit as the relevant code - which is good practice, at least around here - then it's often useful to be able to read not just markdown but a diff of markdown as plain text in ${editor}.
- BeFlatXIII 2y ago> This said, something slightly more complex than Markdown while slightly more elegant, less chaotic and more readable than HTML sounds a great thing to have. Revive Textile? It was one of the inspirations for MD, IIRC.
- qwerty456127 2y ago> I don't want to write a book. If I did I'd use LaTeX before RST. To me this seems a horrible decision at the stage of writing/structuring. I'd rather write in Markdown (this way I could just write, without bothering about typesetting) and only convert to LaTeX for publishing. I'm not proficient in LaTeX though - I once tried to learn it and it felt like learning a language of an insectoid extraterrestrial civilization - completely unintuitive, almost impossible to do anything new - what hasn't been already done by someone else enabling you just copy-paste your own text. IIRC it doesn't even have first-class Unicode support.
- anserin 2y agoIn LaTeX you also clearly separate structure and typesetting: you don't write \noindent\textbf{Introduction}\nobreak\medskip or whatever, but simply \section{Introduction} Macros are also pretty easy to define \newcommand\important[1]{\textcolor{red}{#1}} And of course it has first-class Unicode support
- josephg 2y agoEasy is relative. Latex is sooo much uglier than typst: #let important(body) = { text(red, body) } But whatever you do, #important[Dont *panic*!] Docs: https://typst.app/docs/reference/foundations/function/ https://typst.app/docs/reference/foundations/function/
- nrr 2y ago"In LaTeX you also clearly separate structure and typesetting ..." Not quite. The rub comes in when you want to pull that content out to render it in a format that isn't meant to be camera-ready, like a Web page or an e-book. TeX, even with Leslie Lamport's LaTeX macros, doesn't give you an ergonomic mechanism for marshalling out the semantic structure of your document to reuse elsewhere. You're left parsing the TeX yourself, and that sucks.
- ori_b 2y agoYes, that is a good rephrasing of the rest of the paragraph you quoted.
- eviks 2y ago> but Markdown is the best tool for what it does - quickly writing formatted text in a way that is easy to read even for those who are not well versed in its syntax. That's not true, even at the basics it's not great, let alone the best: asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/ And then outside the basics it's not that easy to write/read either, you'll get lost in bad formatting of tables or metadata (tags) obscuring text or what not without proper tooling > How easy it is to extend is largely irrelevant It is relevant as then you could fix those basics if you could easily and conveniently extend it
- michaelcampbell 2y ago> asterisks/underlines for italics already require familiarity unlike the much more intuitive /italic slashes/ This has always baffled me. _underline_, /italics/, bold.
- yencabulator 2y agoAnd then you have programmers talking about _private_method and /some/path/
- eviks 2y agonot a good argument given the fact that underscore _is_ already a bold markdown syntax
- yencabulator 2y agoYeah but CommonMark was carefully specced to make sure _foo_bar doesn't trigger that, and _foo_ is not a common style of identifiers -- where as /etc/ is a common convention, when you specifically want to refer to contents of a directory.
- eviks 2y agoIf it's so carefully specced (though how do you italicize a part of a word than? Seems to me more commonly important vs some niche identifiers), why did you bring _ up as an issue? But also asterisk is a common form for multiplication just like / is for division/separation (which is more common than paths) So you already have this design issue, but on the other hand at least you could have the benefit of visually intuitive markup, which isn't the case with markdown
- necovek 2y agoUhm, reST is also easy to read and write, at least where Markdown is easy to read and write. To me, they are largely the same thing, with slight syntax differences, with reST being more readable as it's clearer what any special syntax is about, whereas MD is more concise to type out — you need to learn the special syntax whatever way you slice it. FWIW, reST was the default for Python "doctests": a wonderful feature that has fallen out of favour for some reason, but has the potential to be your real runnable documentation. I wouldn't write a book in either, but that's because I am really high on great typesetting — I even had my own set of (Plain) TeX macros to do ToC generation, syntax highlighting, alternative math fonts, support for UTF-8 before eTeX and such when I did write papers and handed in coursework regularly.
- lmm 2y ago> reST is also easy to read and write, at least where Markdown is easy to read and write. It isn't though. It's just a whole lot more annoying. On paper the syntax differences are small, but they make the writing experience so much worse. I wanted to like rST but it just isn't good enough in use.
- jgruber 2y agoIf rST were actually easy to write and read I would have just used rST instead of creating Markdown.
- __mharrison__ 2y agoExcept for native Python tools like Jupyter, which have all moved on to md. (I still like doctests and use them extensively in my books.)
- bosie 2y agoWhat do you use for the actual, non-quick documentation? Markdown is pretty bad for note taking, it has a niche functionality suited for basic text based note taking. Unfortunately that isn’t the only note taking that is possible
- andrepd 2y agoThis is pretty much the paragraph that follows the paragraph you cited...
- makeitshine 2y agoThat was a rhetorical question in the article. It's immediately followed by: > ..Okay yeah that's actually a pretty good reason not to use it. I can't get into lisps for the same reason. I'm not going to begrudge anybody who avoids a tool because it's ugly.
- __mharrison__ 2y agorST and md are both not ideal for writing books. And LaTeX is even more painful. IMO using md is the lesser of two evils. I'm done kicking against the pricks with rST.
- kevin_thibedeau 2y agoMarkdown has 30 different flavors because it grew organically and has no formal extension mechanism. "What am I allowed to use in this markdown processor?" never becomes an issue with reST.
- red_admiral 2y agoMarkdown has 30 flavors because it has over 30 different ecosystems using it. We have github flavored markdown, gitlab flavored markdown, MDN markdown etc. because github, gitlab and MDN are all using it. If you forced everyone to move to rst, then you'd see flavors cropping up soon too. Even if rst has a generic extension mechanism, on github you'll spend a lot of time referencing commits, tags, users, pull requests and that kind of thing. So you end up having to know a domain-specific language anyway, whether it's formally presented as an extension mechanism to the language or as a dialect.
- ska 2y agoIf it was only about this, personally I find org-mode is better than markdown. There is a big gap between a book and informal notes, docs, comments though. At least big enough to drive several tools into, or they wouldn’t exist.
- BeFlatXIII 2y agoWhat are some non-emacs tools (more advanced than notepad.exe or TextEdit.app) for editing org-mode?
- humanfromearth9 2y ago> I don't want to write a book. If I did I'd use LaTeX before RST. You'd want to use Typst, not LaTeX. I'm rewriting my CV with it, it's fantastic. I can now finally put the CV contents in a JSON, and generate the PDF programmatically, with lots of computed values by my own algorithms, the layout is simple, nothing stands in the way, nothing feels out of its place. And compilation is so fast... Really, forget LaTeX, embrace the 2020s.
- jgruber 2y agoI couldn’t say it better myself. Thanks.