9 ms·

Markdown can do quite a lot, but it doesn't have any way to write mathematical formulae. Since that's 90% of why I use LaTeX in most cases it seems silly to rec

Markdown can do quite a lot, but it doesn't have any way to write mathematical formulae. Since that's 90% of why I use LaTeX in most cases it seems silly to recommend Markdown. LaTeX has a superset of features, and is well suited to what it does properly (typesetting). Markdown is quick and easy to use, so it's good for blog posts.

eevilspock 9y ago
Many flavors of Markdown support math extensions. Many do so in a way that degrades gracefully when the extended Markdown is opened in a standard Markdown tool. Typora is a great WYSIWYG Markdown editor that uses MathJax to render LaTeX mathematical expressions.
- behindmyscreen 9y ago
  The problem is, if you do a lot of formula writing in a narrative, most WYSIWYG editors that support LaTeX formula rendering are just not efficient. I want to type my thoughts, start a formula block, write my expression, end the block, and continue going. You can't do that in most WYSIWYG editors.
  - k_bx 9y ago
    You can definitely do that in Typora (unless I miss something what exactly you meant).
    - behindmyscreen 9y ago
      When I think of WYSIWYG editors, I see presentation and content being mixed. Unless Typora has figured out how to get remove the need to locate the insertion point of a formula, open an editor, then submit the data to render an image that is placed inline or made into a block. If it has figured that part out then props to them for making it easier to write mathematics in an accessible editor.
      - k_bx 9y ago
        For formulas it just re-renders formula as you type it, no WYSIWYG magic where it's over-complicated. For regular Markdown it's WYSIWYG.
- MajorSauce 9y ago
  I just wanted to thank you for this discovery. I am in the middle of writing a document and gave Typora a try, seems to fit the middle ground between "basic" formatting and Latex.
da_chicken 9y ago
My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing documentation. They get to use the same plain text editor they're familiar with. They get to use the same version control that they use with their code. I've seen programmers try to use many justifications for why LaTeX is important for their doc because LaTeX has some feature that everybody knows they don't actually need to use. The truth is that unless you have a literal need for actual true typesetting, you should absolutely not use LaTeX for documentation. The reason for this is two fold: 1. "First, you need a properly configured LaTeX build environment," are never, ever the first words that anybody wants to hear when they need to read, update, modify, and manage documentation. Documents that are not going to be published outside the company should never require a build environment. 2. No matter what your job is, you're not going to have it forever and someone will probably be in it after you. If all your documentation is written in LaTeX, then suddenly, "Ability to write, modify, and maintain LaTeX documents," is a mandatory requirement. That's a significantly higher bar than "Ability to write, modify, and maintain Microsoft Word documents." Congratulations, you just added significant complexity to your job for essentially no benefit to the company. The only time you should favor LaTeX is when you're writing a document that will be published and is essentially entirely text. You're a mathematician or some other discipline and actually need to write extremely complex symbology. You have extremely complex and numerous references to manage. You're writing a high level research paper. Congratulations! You're the intended audience for LaTeX. If you're a software engineer writing standard documentation, put the text editor down and use Microsoft Word. Documentation is meant to be read by everyone, not make you feel good about being forced to write it.
- seanmcdirmid 9y ago
  Not many go into LaTeX "loving it". Many of us try Word first, and are just unhappy with its output. If you need something that is well typeset and don't want to spend a few $10k on professional typesetting software, LaTeX fits the bill well. Everything else about LaTeX is a pain, not a joy. Is a lot of documentation written in LaTeX? I would never use it for that. Paper that is going to be submitted to a conference? Sure! Blogpost? No, documentation that is read only online...also probably not. But I don't think I would use Word for that either, Word is a pain if you need something other than very standard formatting.
xiaq 9y ago
Pandoc's tex_math_dollars, tex_math_single_backslash and raw TeX mode makes it possible to fallback to TeX whenever you need: https://pandoc.org/MANUAL.html#math-input https://pandoc.org/MANUAL.html#math-input A Markdown -> LaTeX -> pdf pipeline was how I wrote all of my algorithm assignments in college. I wrote things like: * **Basis**. Prove for $n = 0$... * **Induction**. If \mathcal{G} is a graph ... \begin{equation} ... \end{equation}
- tincholio 9y ago
  You seem to be well over half-way to LaTeX there, so what's the point in using markdown? If the verbosity of writing \begin{description} ... \item[basis]... \end{description} is the issue, you can get around that with a couple of shorthand macros.
  - black_knight 9y ago
    I wrote my math phd thesis in Markdown/LaTeX in this way. I also replaced all maths symbols with their Unicode equivalent. The result was very readable markdown source text, easily compiled to Latex and PDF, using a mk file. My thesis also included formalised proofs in a proof assistant, and they were just written straight into the markdown files as code blocks, and were using the same Unicode symbols as the rest. Later, when publishing the different parts of my thesis, this separation from Latex made it easier to convert to whatever cls the publisher wanted, since I would just change the template.
    - tincholio 9y ago
      I wrote mine in plain LaTeX, never had an issue with it. Regarding code, you can use the listings package (\lstincludelisting) to include source code files directly. I fail to see the interest in having a bastardized, not quite TeX, not quite MD file (unless you're using something like Org, of course, and using its other functionalities). Regarding having unicode for the maths, how did you deal with symbols that needed scaling (brackets, integrals, etc.?) They may look simpler when seen as text, but they certainly won't render nicely as math...
titanix2 9y ago
From my (limited) experience of writing a documentation page for a library I made, Markdown is pretty limited (speaking of CommonMark here). Even basic things like table or image need HTML to be done. The gain in syntax is lost on the coherence side as the document mixes two languages, and an additional step of processing the document is required to transform it in full HTML. It have it use cases but writing long and complex documents is not one of them.
- busterarm 9y ago
  Kramdown is far and away the best Markdown implementation at the moment. It doesn't have the problems you describe (but does others).
- Ajedi32 9y ago
  CommonMark _does_ support images: http://spec.commonmark.org/0.27/#images http://spec.commonmark.org/0.27/#images Some other, non-standard variants of Markdown also handle tables via a syntax which resembles ASCII art. And while that format does do an excellent job of adhering to Markdown's ethos of remaining readable in plain text; I usually prefer to use HTML fallback anyway as it's easier to maintain.
  - petepete 9y ago
    The most commonly used Markdown variants (Github, So, Reddit, probably Slack) support tables, they've been in use for years and work well. I can't believe Commonmark can't just standardise what's already being used by the majority of users. Some of the suggestions in the discussion thread[0] don't pay any attention to this, and if they agree on something that nobody uses it'll just be ignored. [0] https://talk.commonmark.org/t/tables-in-pure-markdown/81/29 https://talk.commonmark.org/t/tables-in-pure-markdown/81/29
rz2k 9y ago
I use RStudio with `knitr` when it is the wrong tool, because it is just too easy to make something that is easy to read and people think I put a lot of effort into formatting. I do have a few templates that I use so that the text isn't always Computer Modern, but it is mostly a mix of Markdown, Latex math, and features from R like `kable` for making tables. I even tend to plot graphics into the text using R, rather than looking up how to place them using markdown.
- kqr 9y ago
  This is what I do, too, except I use Org instead of knitr, because it lets me embed many more languages than just R. I should finish the blog post about this at some point...

eevilspock 9y ago

Many flavors of Markdown support math extensions. Many do so in a way that degrades gracefully when the extended Markdown is opened in a standard Markdown tool. Typora is a great WYSIWYG Markdown editor that uses MathJax to render LaTeX mathematical expressions.

behindmyscreen 9y ago
The problem is, if you do a lot of formula writing in a narrative, most WYSIWYG editors that support LaTeX formula rendering are just not efficient. I want to type my thoughts, start a formula block, write my expression, end the block, and continue going. You can't do that in most WYSIWYG editors.
- k_bx 9y ago
  You can definitely do that in Typora (unless I miss something what exactly you meant).
  - behindmyscreen 9y ago
    When I think of WYSIWYG editors, I see presentation and content being mixed. Unless Typora has figured out how to get remove the need to locate the insertion point of a formula, open an editor, then submit the data to render an image that is placed inline or made into a block. If it has figured that part out then props to them for making it easier to write mathematics in an accessible editor.
    - k_bx 9y ago
      For formulas it just re-renders formula as you type it, no WYSIWYG magic where it's over-complicated. For regular Markdown it's WYSIWYG.
MajorSauce 9y ago
I just wanted to thank you for this discovery. I am in the middle of writing a document and gave Typora a try, seems to fit the middle ground between "basic" formatting and Latex.

da_chicken 9y ago

My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation. Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing documentation. They get to use the same plain text editor they're familiar with. They get to use the same version control that they use with their code. I've seen programmers try to use many justifications for why LaTeX is important for their doc because LaTeX has some feature that everybody knows they don't actually need to use. The truth is that unless you have a literal need for actual true typesetting, you should absolutely not use LaTeX for documentation. The reason for this is two fold: 1. "First, you need a properly configured LaTeX build environment," are never, ever the first words that anybody wants to hear when they need to read, update, modify, and manage documentation. Documents that are not going to be published outside the company should never require a build environment. 2. No matter what your job is, you're not going to have it forever and someone will probably be in it after you. If all your documentation is written in LaTeX, then suddenly, "Ability to write, modify, and maintain LaTeX documents," is a mandatory requirement. That's a significantly higher bar than "Ability to write, modify, and maintain Microsoft Word documents." Congratulations, you just added significant complexity to your job for essentially no benefit to the company. The only time you should favor LaTeX is when you're writing a document that will be published and is essentially entirely text. You're a mathematician or some other discipline and actually need to write extremely complex symbology. You have extremely complex and numerous references to manage. You're writing a high level research paper. Congratulations! You're the intended audience for LaTeX. If you're a software engineer writing standard documentation, put the text editor down and use Microsoft Word. Documentation is meant to be read by everyone, not make you feel good about being forced to write it.

seanmcdirmid 9y ago
Not many go into LaTeX "loving it". Many of us try Word first, and are just unhappy with its output. If you need something that is well typeset and don't want to spend a few $10k on professional typesetting software, LaTeX fits the bill well. Everything else about LaTeX is a pain, not a joy. Is a lot of documentation written in LaTeX? I would never use it for that. Paper that is going to be submitted to a conference? Sure! Blogpost? No, documentation that is read only online...also probably not. But I don't think I would use Word for that either, Word is a pain if you need something other than very standard formatting.

xiaq 9y ago

Pandoc's tex_math_dollars, tex_math_single_backslash and raw TeX mode makes it possible to fallback to TeX whenever you need: https://pandoc.org/MANUAL.html#math-input https://pandoc.org/MANUAL.html#math-input A Markdown -> LaTeX -> pdf pipeline was how I wrote all of my algorithm assignments in college. I wrote things like: * **Basis**. Prove for $n = 0$... * **Induction**. If \mathcal{G} is a graph ... \begin{equation} ... \end{equation}

tincholio 9y ago
You seem to be well over half-way to LaTeX there, so what's the point in using markdown? If the verbosity of writing \begin{description} ... \item[basis]... \end{description} is the issue, you can get around that with a couple of shorthand macros.
- black_knight 9y ago
  I wrote my math phd thesis in Markdown/LaTeX in this way. I also replaced all maths symbols with their Unicode equivalent. The result was very readable markdown source text, easily compiled to Latex and PDF, using a mk file. My thesis also included formalised proofs in a proof assistant, and they were just written straight into the markdown files as code blocks, and were using the same Unicode symbols as the rest. Later, when publishing the different parts of my thesis, this separation from Latex made it easier to convert to whatever cls the publisher wanted, since I would just change the template.
  - tincholio 9y ago
    I wrote mine in plain LaTeX, never had an issue with it. Regarding code, you can use the listings package (\lstincludelisting) to include source code files directly. I fail to see the interest in having a bastardized, not quite TeX, not quite MD file (unless you're using something like Org, of course, and using its other functionalities). Regarding having unicode for the maths, how did you deal with symbols that needed scaling (brackets, integrals, etc.?) They may look simpler when seen as text, but they certainly won't render nicely as math...

titanix2 9y ago

From my (limited) experience of writing a documentation page for a library I made, Markdown is pretty limited (speaking of CommonMark here). Even basic things like table or image need HTML to be done. The gain in syntax is lost on the coherence side as the document mixes two languages, and an additional step of processing the document is required to transform it in full HTML. It have it use cases but writing long and complex documents is not one of them.

busterarm 9y ago
Kramdown is far and away the best Markdown implementation at the moment. It doesn't have the problems you describe (but does others).
Ajedi32 9y ago
CommonMark _does_ support images: http://spec.commonmark.org/0.27/#images http://spec.commonmark.org/0.27/#images Some other, non-standard variants of Markdown also handle tables via a syntax which resembles ASCII art. And while that format does do an excellent job of adhering to Markdown's ethos of remaining readable in plain text; I usually prefer to use HTML fallback anyway as it's easier to maintain.
- petepete 9y ago
  The most commonly used Markdown variants (Github, So, Reddit, probably Slack) support tables, they've been in use for years and work well. I can't believe Commonmark can't just standardise what's already being used by the majority of users. Some of the suggestions in the discussion thread[0] don't pay any attention to this, and if they agree on something that nobody uses it'll just be ignored. [0] https://talk.commonmark.org/t/tables-in-pure-markdown/81/29 https://talk.commonmark.org/t/tables-in-pure-markdown/81/29

rz2k 9y ago

I use RStudio with `knitr` when it is the wrong tool, because it is just too easy to make something that is easy to read and people think I put a lot of effort into formatting. I do have a few templates that I use so that the text isn't always Computer Modern, but it is mostly a mix of Markdown, Latex math, and features from R like `kable` for making tables. I even tend to plot graphics into the text using R, rather than looking up how to place them using markdown.

kqr 9y ago
This is what I do, too, except I use Org instead of knitr, because it lets me embed many more languages than just R. I should finish the blog post about this at some point...