
Reach for Markdown, not LaTeX - sridca
https://blog.jez.io/reach-for-markdown/
======
z1mm32m4n
Author here! I'd like to take a second to point out that the audience I had in
mind when writing this article was mostly my fellow classmates in college. In
school we were hastily introduced to LaTeX freshman year and were required to
typeset our homeworks before submission.

The point of the article isn't "you should never use LaTeX" but rather "hey,
there's this other, simpler tool that you might like better!" plus some
starter templates to make the transition easier.

Importantly, I encourage everyone to use the tools that they feel most
comfortable using!

~~~
kerkeslager
I'd also add that while Markdown and LaTeX can do _some_ of the same things,
they're designed toward very different tasks. I've used both numerous times in
my career, and I can't remember a case where it's been ambiguous which tool
was more appropriate for the task.

If it's going to be printed, you probably want LaTeX. If it's going to be
rendered to a screen, you probably want Markdown. If it's going to be rendered
to a screen and have math in it, you probably want Markdown with some LaTeX
for the math. If it's going to be rendered to a screen and printed, better
start looking for a job, because that project is going down in flames.

~~~
mwcampbell
Why is LaTeX unambiguously better for print? Is it just the support for math
notation, or is there more to it?

And since "print" very often means a PDF that's also available online, has
there been any progress on tagged PDF support in pdflatex or a similar tool?
This is important for accessibility.

~~~
eslaught
Have you ever tried to typeset a complex document with side bars, figures,
multi-part figures, figures that contain math (not just images), and layouts
that take a lot of tweaking to get just right?

I can imagine doing that in Pandoc Markdown, but only with extensive use of
raw LaTeX code. Most of the above doesn't have a direct equivalent even in
richer Markdown dialects like Pandoc.

~~~
mwcampbell
Ah, thanks for educating me. I pity anyone who has to work within the
constraints of print in 2018. To me, hypertext that adapts to the user's
device and needs (e.g. rendering at a different font size and reflowing
appropriately, or rendering through non-visual means like speech and braille)
is the only way to go these days.

~~~
Gracana
To be fair to latex, the majority of hypertext examples don't do any of those
things either.

------
SAI_Peregrinus
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.

~~~
da_chicken
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.

~~~
hyperbovine
Wow, this is just so far off the mark I don't even know where to begin. LaTeX
excels in three areas that are crucial for writing complex documents -- cross
references, citations, and indexing. You clearly have not had to endure the
house of horrors that is the MS Word ToC, or trying to get autonumbering
working as you wish for sections, figures, and tables, or managing a large
(100s of pages) multipart document, or any one of a bazillion other little
asspains that crop up when forced to use Word for a nontrivial task like
maintaining documentation for a large complex project. And point #1 is a
complete straw man, setting up a TeX env takes 20 minutes and the basic doc
format has not changed since the 1990s at least.

~~~
theparanoid
I thought Latex was superior to Word in every way than I had a colleague that
knew Word. Word if you _learn_ it is just fine generating a ToC or
autonumbering sections, figures, and tables.

In practice, Markdown is better than either for documentation that isn't
printed. It's easier to edit, can be viewed with a plain text editor, and has
a minimal learning curve.

~~~
catamorphismic
> I thought Latex was superior to Word in every way than I had a colleague
> that knew Word. Word if you learn it is just fine generating a ToC or
> autonumbering sections, figures, and tables.

No, it doesn't work well even if you know what you're doing. It's much better
than when blindly trying to hack your way through, but there are still so many
weird quirks it does which you always have to spend a lot of time on.

~~~
Too
I would say it works well if you know what you are doing, but in a shared
document there is always some dumb ass in the team that does some manual
formatting like using the bold-button instead of changing header type, or
remove a link from an image. Then the all the references and indexes are
beyond repair with the only way to salvage the document is to slowly,
meticulously and painfully go through it in this outline-view and try to
identify what should be a header and what should not.

If only there was a way to create a Word document that forbids manual
formatting it could actually be usable.

------
mbid
I don't get it. Say I already know that I'll need some formulae in my
document. Then the use case here seems to be, essentially, that I can write

    
    
        # Section Name
    

instead of

    
    
        \section{Section Name}
    

and that I can write

    
    
        *important stuff*
    

instead of

    
    
        \emph{important stuff}.
    

I can see that the markdown version is a little nicer on the eyes and
keyboard, but only by a small margin.

Now, if I write a document in latex I need to understand exactly

* latex.

Latex is a beast, but there are no serious alternatives to typeset formulae.

If I want to write markdown with some latex in it, I need to understand

* markdown

* latex

* how pandoc interleaves the two.

What if, as will inevitably be the case, something breaks? There will not even
be close to as much documentation for the markdown+latex+pandoc stack as for
the latex-only stack out there. Is there even a standard for markdown+latex,
the pandoc way?

Then there's the issue of packages needed to compile. Tex suites are already
huge pieces of software. Now I also need to have pandoc. Pandoc is written in
haskell, and the haskell stack on arch is a complete clusterfuck. I will not
have saved time if I need to understand how to fix pandoc if it breaks after
an update. Granted, this is mostly an arch issue, but the point is that the
more software you use, the more likely it is that something breaks.

The bottom line is that you replace an already complicated piece of software
with the exact same piece of software _and then something_. I find it hard to
justify it in this case where there is so little benefit.

~~~
skrebbel
> Latex is a beast, but there are no serious alternatives to typeset formulae.

People keep repeating this like it's true, but MS Word has had an _excellent_
formula editor for a decade now (the one they shipped before Word 2007 was
terribly shitty though).

It's wysiwyg (which is fantastic if you're editing a _big_ formula), it
supports all math notation I've ever needed, and it has surprisingly decent
UX. It even supports LaTeX-like input, eg if you type e^2 it gets
autocorrected to e².

This makes _entering_ formulas as fast, if not faster, than LaTeX and
_editing_ formulas an order of magnitude easier because you don't need to re-
parse that backslash-curly-mess that you entered a week ago. Just point and
click and edit.

~~~
wfo
Agreed, there's a great formula editor which is very nice if you want to
create math presentations in powerpoint instead of in beamer (and I wouldn't
blame you, especially if you're in a hurry).

But could you really imagine writing a serious mathematical document (paper,
book, thesis) in Word? No Git, no vim/emacs, no plain text? Abandoning the
digital lingua franca of mathematical communication? Abandoning the packages
written by the sum total of anyone who has worked on anything close to
mathematics in recent years? For what?

~~~
skrebbel
> But could you really imagine writing a serious mathematical document (paper,
> book, thesis) in Word?

Yes I could, and I did. My Master's thesis is written in Word and it was
pretty heavy on the theory and the formulas. If you're interested it's online
on [http://e.teeselink.nl/thesis_et.pdf](http://e.teeselink.nl/thesis_et.pdf).
It's not a particularly stunning thesis in terms of content, but in my humble
opinion it's a pretty document, definitely no worse than the average LaTeX-
produced thesis.

See eg page 58 (the 70th page of the PDF) for some large formulas. It's not
arithmetic but Structured Operational Semantics, but I doubt that matters for
this argument. (in hindsight I hate that page and the ones like it - the sheer
overload of single-character variables makes it totally impossible to
understand)

By the way you said "no git" but Word files can be version controlled just
fine - particularly when you're working solo which I was. I used Subversion
(hey, 2007) but ok.

I used Word because I noticed in earlier years that LaTeX made my mind drop
down into "programmer mode" every time I wanted to accomplish something that
was non-trivial. This nerd sniped me and it distracted me from writing the
actual content. I ended up with super nice LaTeX themes and definitions and
homecooked macros (excuse me for having forgotten the real names these things
have in LaTeX, I last used it over 10 years ago), my content sources were
super clean, but I spent at least as much time on setting up LaTeX as
_actually writing_. Plus, I found editing large formulas frustrating because I
had to find the right place in a fullscreen wall of backslashes and curlies.

Word forced me to focus on the content because everything layout-wise I wanted
to accomplish was boring and, mostly, easy.

The only thing that was cumbersome was getting IEEE-style references (i.e. the
ones that Bibtex generates by default) to work. It worked out in the end but
wasn't as easy as it should be (I noticed that they fixed that since). Also I
had _zero_ problems with that thing where Word just doesn't want to do what
you tell it to (indents jump, list items suddenly disappear etc, you know the
drill) because I _only_ used Word Styles (a bit like CSS classes) and never
custom formatting. As long as you stick to that, Word sucks less.

~~~
anon20180219
Frankly, this PDF shows that it has been produced with Word. For example: (a)
Full justification without hyphenation; (b) Chapter 6 ends at page 69, and the
next 32 pages have wrong left header; and (c) Section headers with fake small
caps. Using LaTeX would have resulted in a more beautifully typeset paper.

Your point that you might have spent more time preparing it is subjectively
true, obviously, and it seems that in your case Word proved good enough.

------
lou1306
I _do_ reach for Markdown/Pandoc whenever possible, but on longer documents
one will end up using lots of LaTeX tricks to get the job done (newcommands,
subfigures, or that strange package that respects the typesetting conventions
of your field).

Plus, I think Pandoc-based collaboration is still out of reach, as there are
simply too many moving parts: the underlying LaTeX distribution, templates,
filters, most of them only available through cloning git repositories.

So a typical workflow of mine is: draft in Markdown/Pandoc, start adding
stuff, but migrate to LaTeX very soon if you notice something is going wrong
(also, the Pandoc LaTeX output sometimes needs some tweaking, so it's better
to leave Markdown while the document is relatively small).

~~~
nextos
For simple stuff, I prefer org-mode. I have great memories of using
OmniOutliner on OS X Tiger. The hierarchical nature of outliners is great for
structuring thoughts quickly. Org is even better, as it's plain text and has
tons of modules for all sorts of crazy things, including kanban or spaced-
repetition. And plenty of export options, including many facilitated by
pandoc, literate programming, etc.

I do use LaTeX, but I have a love-hate relationship with it. Lots of LaTeX
packages don't compose well, and there are tons of pitfalls. But there are
beautiful parts too, like TikZ or Memoir. I'd be happier with TeX, but few
people use that.

------
mbostock
We recently added support for embedding LaTeX expressions (and really, any
dynamically-generated DOM) within Markdown template literals to Observable
notebooks. So you can say md`I like ${tex`\\\KaTeX`}`, and KaTeX renders its
logo, which is then embedded within the generated Markdown.

I’m admittedly biased, but I love the ease of writing Markdown combined with
being able to inline arbitrary DOM for math, sparklines etc. More examples
here:

[https://beta.observablehq.com/@mbostock/measuring-color-
diff...](https://beta.observablehq.com/@mbostock/measuring-color-difference)

[https://beta.observablehq.com/@mbostock/introduction-to-
html](https://beta.observablehq.com/@mbostock/introduction-to-html)

~~~
dunham
I worked around the inline math issue by doing:

    
    
        md2 = x => md([x[0].replace(/\$(.*?)\$/g, m => tex([m.slice(1,-1)]).outerHTML)])
    

I do appreciate you adding support for ${tex`...`}, but it's still a bit more
verbose than I'd like to type.

~~~
mbostock
Well, it’s nice that you can always define your own tagged template literal.
;) The double backslashes certainly are annoying. We may be able to eliminate
them by using String.raw. [https://github.com/observablehq/notebook-
stdlib/issues/10](https://github.com/observablehq/notebook-stdlib/issues/10)

~~~
dunham
I just saw that pop up on the front page of observablehq. That resolves
another pain point for me. (My first experiment with the platform happened to
have a lot of math exposition in it.)

------
gervase
I don't think most people are reaching for LaTeX to write to-do lists or other
ephemeral notes (which can be pretty effectively written just in .txt), but
because they'll need some feature that is simple in LaTeX but difficult or
impossible elsewhere.

However, I doubt anyone who argue with a modified premise of "Reach for
Markdown, not LaTeX, when writing blog posts." But that wouldn't produce as
many clicks, either.

~~~
OberstKrueger
Is that not what it says? The last sentence of the first paragraph is "By
reaching first for Markdown, then for LaTeX when necessary, writing is easier
and more enjoyable", which would be that premise but applied to any situation
where LaTeX is overdoing things.

------
behindmyscreen
I used LaTeX all the time at university. It made citation/bib easy, it made
writing reports for mathematics way more efficient, and the presentation of
the documents were beautiful. I had a prof rave about how nice the my paper
looked once when I turned it in.

I wish I had stuck with it afterward. I write enough that it would make my
work less painful, but I let the skill laps. This article is making me think I
should pick it back up.

~~~
megaman22
I really wish I had bitten the bullet and learned LaTeX in college. At the
time, trying to actually write a research paper start-to-finish in Word was
too painful, too prone to crash and lose data, and badly incompatible with
using version control (CVS and SVN, at the time), and so I settled on a
process where I'd write the whole thing in plain-text, and insert my citations
in inline parentheses, then when I was all done, have to go back and try to
format the thing in Word with proper footnotes and formatting. More than a few
times, it took nearly as long to get that post-processing right for printing
than it did to actually write the paper.

------
bo1024
I find many of these points unconvincing. All of the pros listed at the
beginning also apply to TeX, some arguably better than to Markdown. As far as
I can tell, Markdown has several advantages over LaTeX, but these aren't
highlighted in the article:

* Markdown is easier to learn (at least the basics)

* Markdown is more readable when in plain text format

* Markdown doesn't require boilerplate/metacode such as package imports

* Markdown more easily and naturally renders to HTML (biggest one in my opinion)

(I don't particularly find any of these that convincing for my uses except
maybe the last one.)

------
fmntf
Given how easy the markdown specs are, it is unbelievable how different the
text is rendered using different engines.

~~~
GhostVII
The text is rendered with CSS, so you should be able to specify whatever
rendering style you want using something like Pandoc.

------
vfulco
Really appreciate this piece. I have been doing more rmarkdown into pdf
through pandoc/latex/etc. (yea its complicated but made much easy by the R
community) for my English resume editing business. Still wading into Latex to
customize docs feels like hieroglyphics. Seems made for grad students with too
much time on their hands. The learning curve is steeper than I want or need to
to be as an intermediate tool.

Addendum: I would really recommend crowd here look at rmarkdown flavored work.
There are now a ton of community offerings for resumes/CV/theses even academic
journal article templates. Most can be found on github.com and CRAN (the
central repository for non-base packages).

------
wolph
RestructuredText has generally worked nicer for me that Markdown. Especially
when combined with Sphinx you can easily embed LaTeX math structures as well.

Having that said, depending on the scale of the paper I usually tend to go
back and forth between RestructuredText and LaTeX. When it's large and might
need some fine tuning it's better to use LaTeX, when you simply need to jot
something down... no need for the complex LaTeX setup.

~~~
imron
> RestructuredText has generally worked nicer for me that Markdown

Agree. As soon as you want to start having references to other parts of your
document(s) RestructuredText wins out over Markdown.

------
ollin
Using Typora for WYSIWYG markdown editing using inline LaTeX and a LaTeX-like
theme
([http://theme.typora.io/theme/Academic/](http://theme.typora.io/theme/Academic/))
has been a nice middle-ground for my most common use-cases of homework and
notes. Full LaTeX is wonderful but feels like overkill in many situations.

------
NewEntryHN
LaTeX for scientific documents, Markdown for lightweight text documents, and
ODT from a text editor for everything else.

------
arca_vorago
Reach for emacs org mode, then export to whatever and if you really have to
use pandoc.

------
taeric
If you are just reaching for something to jot notes and whatnot, you could do
worse than looking at org mode. Pandoc is nice, but I have yet to find that a
simple export from org doesn't get me most of where I want to go.

------
azernik
For an intermediate choice, I would recommend AsciiDoc
[[http://asciidoc.org/](http://asciidoc.org/)]. I currently use it for some of
the more complicated pages on my company's GitHub wiki, and am very satisfied
with it.

For an example of its usage and look, here
[[http://asciidoc.org/INSTALL.txt](http://asciidoc.org/INSTALL.txt)] is the
source from which this
[[http://asciidoc.org/INSTALL.html](http://asciidoc.org/INSTALL.html)] page
was rendered.

------
anh79
When I prepared my master thesis some years ago, I needed to extract parts of
the main materials to build another small book that contained only the main
ideas, theorems and proof highlights. \LaTeX and it's programming interface
really helped as I could define a new environment for example

\begin{shipboth} contents for both thesis and the small book \end{shipboth}

This is an example of making things DRY. How can I do the same with Markdown
(and their tools)?

(Well I rarely use \LaTex today; my R\'esum\'e was typeset in \LaTeX and it
helped me to get a good job but when it has so many things I just write them
in a .odt file)

------
imron
I found Markdown quite lacking for things like documentation. Restructured
Text with Sphinx was similar to Markdown in usage but significantly more
flexible (especially references other parts of the documentation).

------
black_knight
Pandoc is really awesome. Even mathematics papers can be written in (mostly)
markdown, and then converted to latex before compiling to PDF.

For mathematics I would also recommend using Unicode symbols in place of LaTeX
commands, which makes the source even more readable. For instance

$∏_{x∈X} ∑_{y∈Y} Ψ(x,y) → ∑_{f : X → Y} ∏_{x∈Y} Ψ(x,y)$

instead of

$\prod_{x \in X} \sum_{y \in Y} \Psi(x,y) \to \sum_{f : X \to Y} \prod_{x \in
Y} \Psi(x,y)$

To get this compiling, your template will have to include declarations for
these such as:

\DeclareUnicodeCharacter{220F}{\ensuremath{\prod}}

~~~
royal_ts
But you can type the second one way easier

~~~
k_bx
There's a very simple emacs extension called "pretty lambda", which displays a
word "lambda" as a lambda character (but presents as ascii still). I wonder if
something like this is possible to do here (of course, the syntax with
arguments makes it harder).

~~~
black_knight
Using XCompose (see sibling post) has the advantage of working in all programs
on X, and producing real unicode.

------
j7ake
I would like to see somebody write their PhD thesis in markdown.

~~~
black_knight
I did! My maths phd thesis was written in markdown.

------
swfsql
I agree. Had started a project aiming to translate various literature books
(no fancy math) into various languages, and markdown makes it a lot easier,
for everyone. [http://github.com/ancap-ch/from-en](http://github.com/ancap-
ch/from-en)

But it's required some regex "replace_all" to be applied when rendering the
PDF.

------
setzer22
This reminds me very much of the emacs org-mode experience. But the good
(bad?) thing about this is that it doesn't require emacs. I was looking for an
alternative to recommend to my friends, since having to learn both the new
notation and emacs really creates some friction.

------
Tenobrus
This is why I reach for Org mode.

------
threatofrain
I imagine many people are already using Latex _inside_ Markdown, a rather nice
solution for the quick production of mathematical texts.

------
gaius
Use both. RMarkdown + Beamer or something.

------
kvm000
This is great.

I write 100-200 page functional spec documents at a vendor for large scale
file based broadcast systems (10-300 linux servers) for a number of customer
projects, and have been trying to get away from word since it's slow at that
scale and I don't want to spend any time on formatting, and want to get to a
templated approach for the others on my team with a consistent output.

Currently I'm using markdown with some CSS and just use Marked2 (Mac) to
export but don't have it all worked out yet. Markdown + LaTeX + Pandoc is
probably better and more powerful or precise than using CSS. I don't use
equations but I do use tables a lot and I'm using multimarkdown ascii ones for
now (with a nice atom.io auto-format plugin to make it easy to author) and
some code blocks with syntax highlighting.

The idea is to have a folder per customer/project spec, with a consistent
structure of one .md file for the body and a local sub-folder for images (svg
workflow(bpmn)/system diagrams mostly, some jpgs for logos, screenshots). The
folder would be in a local git repo so we can commit changes and export diffs
to see what changed between versions and have multiple people work on the same
doc with tracking.

I'm using "invisible links" for in-line comments at the bottom of each section
that are added while going though it with the customer since it usually takes
5-30 versions before it's finalized and signed off. Those keep a record of
discussion with the customer and don't get rendered out in the final output.
Also using standard set of status tags (@outstanding, @done, @info) within the
comment text.

Ex; `[Note: <initials> YYY-MM-DD]: # (comment text @status-tag)`.

Going through the in-progress spec with customers and typing notes inline has
been much better than word's commenting system and using markdown makes it
easy for the customer to read without extraneous formatting code in-line.

Currently using a multimarkdown header for variables; customer name, project
name, author, author email, spec version, etc., but I might move that to a
separate YAML file.

Ideally, to make each version of the spec it would be markdown through
LaTeX/Pandoc to render a PDF with;

\- Title page generated automatically using variables (multi markdown header
or separate YAML) \- Automatic Table of Contents \- Automatic header numbering
(h1-h6) \- Automatic header/footer using variables & auto page numbering \-
Ability for basic control of image size; 80% width (svg), original pixel
resolution (pngs), etc., positioning. \- Ability to have global paragraph
numbering in sidebar that the customer can reference while discussions are
ongoing, and turn that off for final output to PDF.

I'm going to spend time with the examples from the original link to try to
work that all out but any suggestions or tips would be greatly appreciated.
I'd be happy to post an example of the final template and write-up of the
approach on GitHub.

------
ggm
Writing can have two goals. Sorry three. Firstly, to communicate with
yourself: the subclasses being taking notes and "thinking aloud on paper"

The other goal being to communicate with others.

Markdown is good for both. Sorry all three.

