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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
I used to do all my docs in Adobe Framemaker. The output was amazing. The software itself felt a little obtuse, but seeing the printed pages was great.
Fair enough. My wife uses Adobe tools for typesetting, she is a professional (she pays $100/month for her CS subscription, however). I'm not a professional, I've looked at the amount of effort needed to refine output in these tools and they make LaTeX look usable...
I find that in most cases InDesign takes an order of magnitude less time/effort and dramatically less frustration to get a particular careful output than MS Word, LaTeX, or other commonly available tools. Your wife probably has difficult requirements and exacting quality standards, and could likely get output with quality equivalent to common documents prepared using amateur/automatic tools in a much shorter time, if she wanted to.
It’s almost impossible to do professional quality typesetting in MS Word. Last time I really tried was about 10 years ago. I spent like 4 hours trying and failing to fix basic typographic mistakes in another person’s 20-page document, and then gave up and did the whole thing over in InDesign in 20 minutes, with great results.
In LaTeX, you can theoretically do anything you want but unless there’s already a template for it (or you have numerous or long documents targeting the same output style, for which you want to make a template and then mostly rely on automatic layout), it’s going to take a huge amount of time. It’s a good tool if you want output that is “good enough” for many practical purposes without direct human input, but it is especially difficult to do anything special-cased for a particular spread (moving images, text boxes, diagrams, ... exactly where you want them).
LaTeX is great for things like auto-generated documentation, long structured outlines, legal documents, or math papers full of complicated formulas. LaTeX is abysmally ineffective for posters, magazines, or the like. I find that for the vast majority of content in between those extremes (e.g. college humanities homework, non-technical journals, resumés, menus, coffee-table books, novels, poetry, personal letters, ...), InDesign ends up giving nicer output with less headaches.
In my field there are always templates. LaTeX, or I guess TeX, works well until it doesn’t, and then fails in ugly ways (quite the opposite of Word, which will work all the time not very well). So overflow and underflow paragraphs are possible, so are orphans, though it tries to avoid them if the output is decent. This is nice because I can fix all my problems usually by refining my content (changing words, orders, etc...), I don’t actually have to dig deep into TeX to otherwise modify the format! This is quite usable in general, though there are huge debates on whether it is appropriate.
From what I can tell, Adobe follows the more technical approach, though I’ve only looked over my wife’s shoulder. The fact that I’m just producing PDFs with LaTeX is also different. If I’m writing a web essay, I don’t mind using straight HTML/CSS, even markdown doesn’t really convey many benefits for me.
Web essays is definitely not the place to use professional typesetting tools. Browsers are simply incapable of doing professional quality typesetting of the type books have had since the 15th century because the output environment is too heterogeneous, unless you abandon html and render documents as SVG or PDF or something (I would not recommend doing that). Authoring tools won’t help you. On the web the best you can do is make (or purchase/find) a decent CSS template and hope it’s readable enough for most viewers on most devices.
I've always been curious: Pretend I'm totally ignorant, and have no idea what need a typesetting tool fulfills. Someone who has used and been happy with Word / Open Office for years to write documents. What does LaTeX/InDesign solve for me, besides "nice looking math" that I'm not getting out of basic word processors? How do I know which one I need? I honestly have no clue. If I were to start writing a book tomorrow, I'd just open Word. Why not? What am I getting when I invest either the time to learn LaTeX or the money to buy InDesign?
For writing a non-fiction book, you should probably use Word or something similar. Just make sure to avoid any formatting tools, only use semantic markup. Word is a pretty decent authoring tool. The end result can then be imported to a typesetting tool for formatting.
InDesign is used when you need precise control of the output. For instance controlling exactly how figures are placed, you might more advanced control of how text flows between boxes, etc. It also has tools for very precise control of how the type is set, how big space should there be between letters and words, how should the right edge of columns look, should there be different number of columns on different pages, etc.
Some of those things can be somewhat managed in Word, but you'll have to fight a lot of the automatic stuff, really not worth it if you are a full time design professional, much cheaper then to buy an expensive InDesign license.
Latex is pretty good at having sane defaults. This was a bigger issue back in the days when the defaults of Word were frankly terrible. Today it's to a large extent about style choice. If you publish in an area where Latex dominates, the Latex styling will make your document appear as more serious. Latex also generally uses a more advanced type setting engine, for example it might join "fi" with ligatures etc. This can also improve the look of the document.
Some people like the fact that you can manage Latex code as raw text. For instance using a VCS to manage version history. Word has some built in version management functionality, but it's quite clunky compared to Git.
Personally I gave up on using Latex after my first master thesis and tend to use Word. I get too caught up in the formatting when I use Latex. Maybe it's too much power to handle for me?
I just updated my resume two weeks ago. Too bad couldn't find the original LaTeX code, so I had to write a new one.
I tried looking for some free MS Word templates, and didn't find anything fit.
If you're doing many one-off designs, I'm sure something like InDesign is faster than TeX. However, if you are producing similar-looking documents, the effort of writing your own LaTeX class is relatively low.
There's also other advantage to using LaTeX, and that is the flexibility that comes with macros. Need to change some notation mid-way through your writing? It's trivial if you've used macros. Need to simplify some commonly used pattern? Define a new macro!
Each tool has their place. Except Word, Word just sucks! (j/k, Word is brilliant when doing collaborative edits with non tech-savvy people, the track changes functionality is great, and not easy to replicate in other environments)
One practical advantage of using free tools is that everyone in your company can use it, you can write automation that uses it, etc. I'm not going to defend LaTeX in particular, but there's a lot of value into using something (like Markdown or reStructuredText or whatever) that anyone in your company can propose edits to, where you can automatically publish nicely-formatted (e.g. HTML) documentation when anyone in your company makes a change, and so forth.
Another way of gaining this advantage is to use something you're already paying for like an internal wiki.
I’m not recommending anyone use InDesign or similar tools for everything.
It’s a typesetting tool designed for producing paper documents. You should use it for your company’s magazine, menu, posters, and published books, not for your auto-generated technical documentation, your blog posts, or your internal emails.
The previous commenter wrote about what to do if you “don't want to spend a few $10k on professional typesetting software.” That’s much steeper than most people will spend on professional typesetting software.
Back to my CS undergrad days, I wrote my assignments in LaTeX. It can handle practically every CS nerds: Complicated math expression? Check. Displaying beautiful pseudocode? Check. Binary tree? Check. Karnaugh map? Check. Etc etc.
Probably you've heard that only real men write LaTeX using plain text editors. I'm not a real man enough, so IDE like TeXnicCenter or Texmaker is needed :p
These days, personally I use Pandoc or Halibut (https://www.chiark.greenend.org.uk/~sgtatham/halibut) for anything not complicated. Or if working on team, then 'unfortunately' MS Word. Well, not every of us are nerds :)
I used Texniccenter also, but I don't find that I use any of the markup help, I just like the syntax highlighting (these days I just use vscode). I try not to do anything complicated with LaTeX anymore, its just never worth the trouble.
> Is a lot of documentation written in LaTeX? I would never use it for that.
No, we have CS interns from the local college who invariably ask about it. We only have them for a few months, so I've probably answered that question several dozen times in the past few years. I know they use LaTeX for their papers as required by their CS department, so I know why we get the question. I'm just tired of answering it.
> Word is a pain if you need something other than very standard formatting.
I don't disagree with that, but our standardized formatting is to use the default styles. Use Title for the doc title, use Heading 1 for each major step or process if the doc has more than one (most don't) and Heading 2 for each individual step. This means the Navigation Pane serves as your document navigation. Most of our docs are less than 20 pages or so (and most of that is screenshots).
Half the people that manage our doc are non-programmers. They're not learning LaTeX. They're not editing raw PDFs while the other half of the team uses LaTeX.
I was with you until the last paragraph. Microsoft Word? Really? I can still read plain text documents written in the late 70s. Can't quite say the same for VIP-Writer. Or even Word Perfect.
Both your issues are solved by LyX. It removes most of the pain, and what remains tends to be with adding obscure document classes anyway, which you don't need for documentation.
Since this is a forum that values reasoned debate, it would help if you actually argued against "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." instead of just dismissing them out of hand. Those seem like important things!
Also, what's wrong with
apt-get install texlive-latex-recommended
(or better yet having your IT department / your provisioning system for new developer machines / whatever do that for you)? If your position was "Documentation edited by lots of people should not require weird CTAN modules," that I would agree with. You can write perfectly good documents of all kinds with just what's in texlive-latex-recommended.
Was with you until your recommendation for Word for documentation. Something like a wiki or Sphinx would be much more appropriate than a flawed and proprietary one.
The proper tool is whatever the IT department has installed on everyone's computer by default, and failing that, something simple and easily edited (like raw text or markdown).
I think the proper analogy is like editing documentation in PDF. Software that can edit PDFs is expensive and difficult to use, like LaTeX can be (difficult, not expensive, just in terms of time).
I have a dream where someone writes a processor that will allow the writer to bang out some Markdown-ish plaintext and turn it into a p&a with automatically generated Table of Contents, Table of Authorities, caption, and pleading paper.
Call it LexDown or something even less mellifluous and free millions from the tyranny of Word style sheets forever.
As far as I'm aware, the vast majority of legal documents are still written with Word or Google Docs. Nearly everybody went to Word when WordPerfect died.
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.
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.
> 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.
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.
"Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables." : but can it do this? -- [Common Lisp Quick Reference](http://clqr.boundp.org/clqr-a4-booklet-all.pdf)
You don't know the requirements of documentation that we're writing. They don't need a table of contents. They don't need an index. They don't need citations. They don't need math symbols. They don't need tables more complex than a word processor can create. We require no features which your typical academic or research paper requires. We are documenting processes with screenshots that users can refer to in order to accomplish specific tasks. Only a dozen of them are more than 25 pages, and in Word if you keep your document formatting simple and use the built-in styles for headings, the Navigation Pane serves as a hyperlinked ToC. None of these documents should be printed because the processes can change, so beyond basic structure, layout isn't particularly important.
Furthermore, our documents can't be written in LaTeX because half the people responsible for maintaining them come from a non-technical background with no experience in programming. No, we are not going to inflict a WYSIWYG LaTeX editor -- all of which are far less usable than Word -- on people just because some technical people want to pretend they're programming.
Nevertheless, our CS interns invariably say, "Why don't we use LaTeX for this documentation?" I understand why they want to. They use LaTeX for all their papers. However, it is inappropriate in our situation and has gotten to be a rather irritating question.
> You don't know the requirements of documentation that we're writing
Yet you seem happy to prescribe your (extremely limited) views on everyone else without knowing their situation.
Good for you if all your documentation requirements are trivial, and I'm sorry to hear that your team cannot cope with trivial software installs or simple markup. Maybe the problems lie not with LaTeX...
Anecdote about LibreOffice 4.2.8.2: Due to a bug, LibreOffice was generating incorrect page numbers in the table of contents of a 80-page document: some sections were 1 page off, even right after I clicked to manually regenerate the TOC.
It was very frustrating, because I noticed it just a few hours before the deadline. To work around of this bug, I had to insert manual page breaks (mostly randomly), and I had to make the vertical margins of the TOC pages smaller.
LaTeX has always generated the correct numbers in the last 25 years I've been using it. And if I got something unexpected, I was able to fix it for good (without document-specific hacks such as manual page breaks) by adding some macro calls. With LibreOffice and Microsoft Office, getting such a fix ready in 1 hour is hopeless for me, so I'll either miss the deadline or I hand in something incorrect and unprofessional.
Also: LibreOffice doesn't support character formatting (of a few words only) in the ToC. LibreOffice doesn't support omitting a few select sections from the ToC. LaTeX supports both.
> 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.
Well, I had to re-encode my documents twice in that time, once to isolatin1, and once to Unicode, because I was writing in Spanish and German. But it was actually fun to figure how to make that translation happen completely automated and happen in a few seconds.
I mean it’s not like it must be either LaTex or a word processor. Markdown is sufficiently easy to turn into text nowadays there’s really no reason not to first instance.
And that’s assuming someone agrees with the general premise of this argument which I don’t think I do
I'm sorry I disagree. Word is absolutely horrible for programmers to write in. It makes even the simplest of formatting repetitive and boring. It does not do automatic layout (things I DO NOT want to bother myself with) nor syntax highlighting.
Just use Markdown if you're so concerned with people writing Latex.
In addition to the other comments, being able to use version control on software documentation is a critical ability. If you develop software without a distributed version control system, you are just stuck in 17th century and there is no need to discuss further.
If you use version control for your code and do not treat documentation as an integral part of the software which accompanies each version, this makes the impression that documentation is just an afterthought.
To address the 'environment' issue, it is, in most cases, unproductive to not work on Linux where all of this stuff works out of the box.
Also, your idea that it is easier to write a /good/ document using Microsoft Word than using LaTeX hugely underestimates the complexity of MS word for anything moderately complex, and even more hugely overestimates the complexity of using LaTeX for simple things. Somebody who has the job to write code in Python or Go should be easily able to document an API in LaTeX within two hours.
And to add finally, maybe you don't believe the world will continue to move without using MS office. Be assured, there are quite a few large companies which have ditched office (say, Google) and this was not the slightest obstacle to their further success.
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
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}
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.
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.
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...
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.
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.
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.
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.
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...
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:
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
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.)
Mike, great job on Observable and thanks for all your work on D3 as well! I read through the whole thread about observable that was on hacker news a couple weeks ago, but I didn't see an answer to a question I have. Are there any plans to allow observable to be run locally like a jupyter notebook? Like an app or anything. Even if the site was like a progressive web app that could be nice.
I know observable as a whole is not open-source so I understand this may not align with the best interests of the company. Also observable is fairly new so I'm sure you have a lot higher priority features on the release radar. I honestly wouldn't mind paying for an application even if it was an electron app.
Anyways good luck with Observable! I think its a great notebook format with a great API.
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.
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.
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.
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!
Interesting, and a bit surprising. Back in the Triassic Age, I picked up LaTeX from an undergrad roommate because it was easier than writing up homework by hand, and because you can turn a basic ".txt" file into a ".tex" file with very few changes.
I agree that Markdown and friends have their place, but they quickly reach their limits. You write that "Pandoc can take care of the presentation for us," but in my experience, Markdown and such will only get you as far as "good enough." If you want to typeset complicated equations, or print something more complicated than a novel, you need more powerful tools.
You can write markdown and pandoc will leave any latex fragments for the backend. This only works for latex based backends like pdf but it works great if you have some formulas.
Code formatting and tabels are also vastly easier with pandoc.
Yeah, LaTeX tables are a pain, so I usually generate them with a script and include them via "\input{...}". But I've come to rely on TeX macros to generate repeated things like fancy chapter intros, and on packages to customize page headers, etc. This stuff is not necessary for a homework assignment, but I doubt it's as easy to accomplish in Pandoc.
On an unrelated note, I hadn't checked out Pandoc's output in awhile, and this bit from http://pandoc.org/demo/example13.pdf looks pretty bad: https://i.imgur.com/Kxy4mic.png . Granted, the terrible word-breaking and spacing is TeX's fault, but typesetting usually seems to require dealing with a few special cases by hand. I wouldn't trust Pandoc, or any other program, to "take care of the presentation" without a bit of hand-holding.
I can second this. Markdown and Pandoc work quite well together. I write documents professionally using this setup.
I do fall back to LaTeX for certain formatting, but it's actually quite easy to build pass-through filters so that raw LaTeX can be inserted when specialized formatting that can't be easily simulated in Markdown is required.
I'd be very interested in any details of your approach that you could share. I added another comment to this thread with the details of what I've been working on for professional spec documents with markdown and rendering to PDF (testing with CSS now).
It's relatively low-tech, but it does work. First, I have some scripts to preprocess the Markdown and extract custom markup that I have built to do things that Pandoc's Markdown can't, but that I can still easily inline in the document. For instance, I replaced the source code markup with a custom one that generates LaTeX formatted the way I want it formatted. I use Pandoc to output LaTeX. I then have a series of shell scripts to postprocess this LaTeX to insert pre-rendered figures, re-introduce the custom markup as rendered LaTeX, or to massage the output so that the document is laid out the way I expect.
I'm planning to use this to write a book in the near future.
I have used latex to typeset most of my work at uni. but recently I began using org-mode, With a bit of knowlegde it is so much easier to structure my notes. And then it can export to a lot of differnt formats like latex.
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.
If you haven’t tried it yet, I encourage you to give Markdown + Pandoc a try for printed docs. Pandoc can take a LaTeX template and flow Markdown into it. I find Markdown formatting simpler to remember and execute than LaTeX, and there are a huge number of editors and live-preview apps that will let you validate your Markdown as you write. A few keystrokes, and you get a beautiful PDF document, flawlessly typeset in Computer Modern - and with a few more keystrokes, you can have an HTML page with exactly the same content.
There is even a company, LeanPub, that is based on generating paper and e-books direct from Markdown.
When you say "rendered to a screen", do you really mean "placed on a webpage"? PDFs generated by LaTeX are rendered to screen all the time.
edit: Actually, I find that I completely agree with your point if "printed" is replaced by "shared in pdf format" and "rendered to screen" is replaced by "shared in plain text or HTML format".
I'll have to think about this further, but at first glance this seems like a better heuristic than what I wrote.
There's a little bit of opinion embedded in my original post, which is that PDF is an inappropriate format when intended for screens. It's okay if you're wanting to provide a primarily printed document on the web or in email, it's okay, but if your primary target is screens, PDF provides a pretty poor user experience.
(In addition / As an alternative) to Pandoc, has anyone tried Bookish [0] by Terrence Parr of ANTLR fame?
It was referenced by Jeremy Howard in a HN comment [1] on the submission for their "Matrix Calculus for Deep Learning " HN submission of 18 days ago [2]:
>Jeremy here. Here to answer any questions or comments that you have.
>
>But more importantly - I need to mention that Terence Parr did nearly all the work on this. He shared my passion for making something that anyone could read on any device to such an extent that he ended up creating a new tool for generating fast, mobile-friendly math-heavy texts: https://github.com/parrt/bookish . (We tried Katex, Mathjax, and pretty much everything else but nothing rendered everything properly).
>
>I've never found anything that introduces the necessary matrix calculus for deep learning clearly, correctly, and accessibly - so I'm happy that this now exists.
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.
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.
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.
Aside from what other commenters told you: LaTeX just typesets better, meaning that it will choose line-breaks, inter-character and inter-word spacing, ligatures, hyphenation, etc. much better than your regular browser.
Try justifying text on a relatively narrow column in HTML, and then try it with LaTeX. There's a world of difference in readability between them.
> Why is LaTeX unambiguously better for print? Is it just the support for math notation, or is there more to it?
LaTeX is techniques and heuristics from hundreds of years of typesetting for print, codified into a program.
HTML is at most 29 years old, and has only supported typesetting of any kind for a fraction of that. What typesetting capabilities it supports are designed by committees, and its primary purpose has always been screen display, never print.
In the simplest/best case, LaTeX will simply produce nicer-looking results for print. In more complex/worse cases, LaTeX can do things that HTML in a browser can't reasonably do at all for print, even with CSS.
> 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.
I can't answer this question directly because it's been a while since I attempted such a thing, but this is largely what I was joking about with the "the project is going down in flames" bit in my previous post. If you are concerned about accessibility, targeting a proprietary format that resists parsing for text-to-speech or fragment translation and doesn't support variable-width lines for screen readers is a bad idea. Tagged PDFs are really just a hacky attempt to fix the problem: HTML was designed with accessibility in mind from the beginning (though admittedly HTML/CSS/JS as used by modern websites do a very poor job of providing accessibility). Maybe there has been progress in adding this to pdflatex, but it's still a bad idea.
Knuth said that doculents should be readable, but artvto be hanged on a wall.
Typesetting my thesis in LaTeX (physics, 2000) was an amazing choice. I could hardly modify anything (it is doable but requires a lot of work and in the meantime you learn that the default is better) so I was left with the content.
I knew that it would just work and took from me all the philosophical sufferingbof choosing such and such fontvsize for the title of adjusting margins, or placing a graph.
I've done the latter, but basically it's been luck that the program I used (Pages 09) works for print, and also copy/pastes decent html.
Currently jerry-rigging a script to get html out of it by pasting the scrivener and exporting, while keeping pages 09 for print.
It....works, but I would not recommend it unless you have a clear reason to do both. And I'd recommend another program, as pages 09 will eventually be made incompatible on mac.
> 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.
What makes you say that? I'm just finished up my first published book. The entire thing is in LaTex, which is extremely powerful. With conditionals and macros etc. etc.
So I make a print-ready pdf and I'm good to go.
I run the whole thing through pandoc and it spits me out an ePub that's good to go for the eBook version.
Works a treat. I do battle LaTeX some days, but the results are gorgeous.
It's mostly a joke. I've worked on a few things that "needed" to be PDFs with links inside them, because the clients couldn't decide whether they wanted a print version or a digital version, and went with "both". I won't write off the idea that it can be done usefully, I've just never seen it result in anything but a bad user experience for both use cases.
While not exactly the simplest tool around, org mode is still a lot simpler than LaTeX and brings excellent export features to both LaTeX/pdf and html. It’s probably a hard sell for anyone who doesn’t use Emacs already, but for someone already using Emacs, it’s quite neat. I’ve found that for me, it offers the right balance between simple basic functionality (like Markdown) and optional advanced features.
I was also required to typeset homework for some classes in college, but I used LyX [1] instead and never really learned how to typeset a whole document. I picked up the equation syntax though.
LaTeX equation syntax is a gateway drug to heavier typesetting systems. I also started out at maths pastebins when wanting to explain things to others in a readable way.
When I was in uni I used Latex to format work that had math and needed better organization (theses, publication papers). For simpler stuff like comp sci assignments I did it in markdown and ran it through pandoc.
I'm a bit confused by this. As I see it, LaTeX can do everything that Markdown can before things get complicated. Where LaTeX does get complicated (e.g. when designing figures or drawings), Markdown doesn't offer any advantage or even any functionality. For composing simple documents or outlines and doing typesetting of equations, LaTeX has some boilerplate but it's really not that much.
I'm not sure... I think you raise a good point, and I would have the same thing as you before I started writing
in Org and exporting to LaTeX, instead of a) writing in LaTeX directly, or b) drafting/outlining in Org and rewriting the final copy in LaTeX. Now I think exporting from Org is so much easier.
LaTeX in my experience, is worse than markdown for one crucial use case: formatting code. Formatting large blocks of monospaced text (especially monospaced text that includes character sequences that can be interpreted as LaTeX commands) has always been kind of a chore. In markdown, on the other hand, it's as simple as enclosing the text between two sets of triple-backticks (```).
Now add syntax highlighting. In Markdown, it's trivial (```language-name), in LaTeX, you're going to have to define a style. LaTeX is more flexible, but it does come at a cost.
It supports the following programming languages:
ABAP2,4, ACSL, Ada4, Algol4, Ant, Assembler2,4, Awk4, bash, Basic2,4, C#5, C++4, C4, Caml4, Clean, Cobol4, Comal, csh, Delphi, Eiffel, Elan, erlang, Euphoria, Fortran4, GCL, Gnuplot, Haskell, HTML, IDL4, inform, Java4, JVMIS, ksh, Lisp4, Logo, Lua2, make4, Mathematica1,4, Matlab, Mercury, MetaPost, Miranda, Mizar, ML, Modelica3, Modula-2, MuPAD, NASTRAN, Oberon-2, Objective C5 , OCL4, Octave, Oz, Pascal4, Perl, PHP, PL/I, Plasm, POV, Prolog, Promela, Python, R, Reduce, Rexx, RSL, Ruby, S4, SAS, Scilab, sh, SHELXL, Simula4, SQL, tcl4, TeX4, VBScript, Verilog, VHDL4, VRML4, XML, XSLT.
For some of them, several dialects are supported. For more information, refer to the documentation that comes with the package, it should be within your distribution under the name listings-*.dvi.
Notes
1 It supports Mathematica code only if you are typing in plain text format. You can't include *.NB files \lstinputlisting{...} as you could with any other programming language, but Mathematica can export in a pretty-formatted LaTeX source.
2 Specification of the dialect is mandatory for these languages (e.g. language={[x86masm]Assembler}).
3 Modelica is supported via the dtsyntax package available here.
4 For these languages, multiple dialects are supported. C, for example, has ANSI, Handel, Objective and Sharp. See p. 12 of the listings manual for an overview.
5 Defined as a dialect of another language
If you want to get fancier, and have pygments in your system, you can use the minted package, instead.
Ah, seems like the situation is better than I remembered. I confused colored syntax highlighting with the default settings, which highlight using font weight/italicness etc.
I did try minted once, but never used it in practice. The dependency on pygments making the documents more system dependent is less than ideal.
You can of course redefine the default style if you don't like it, but that is no more work than doing the equivalent in CSS (I guesS?) for whatever MD renderer one uses.
I agree that pygments adds a bunch of dependencies, which may be too much just to get some colored syntax highlighting.
Thank you for the clarification. This should be top posted to avoid a lot of the posts that have already occurred. LaTeX is far more encompassing than Markdown will ever be.
For an intermediate choice, I would recommend AsciiDoc [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.
Using Typora for WYSIWYG markdown editing using inline LaTeX and a LaTeX-like theme (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.
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).
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).
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.)
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)
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.
Not really! I use an XCompose file derived from the Plan 9
keyboard setup. So to write ∏ i press my modifer (left shift) button
once, and then 'p' followed by 'r'. So it is fewer key presses than \prod (three key presses vs five).
I have similar shortcuts for all maths symbols I use regularly. Here is an excerp from the configuration
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).
Not necessarily -- with the right editor, e.g. Emacs, you can have it automatically convert "\alpha" to "α" (built-in TeX input mode), or if you're using AUCTeX, you can type "`a", which would be easier than "\alpha" or "α"!
Edit: Oops, saw the sibling post. That also works, although sadly I can't take always advantage of that since I'm not always on Linux.
You can avoid having to declare each character separately if you use the unicode-math package: https://github.com/wspr/unicode-math . I suggest you try it; it's life-changing for e.g. general relativity stuff where there are a lot of Greek letters being thrown around!
183 comments
[ 4.9 ms ] story [ 216 ms ] threadHowever, 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.
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).
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.
The other goal being to communicate with others.
Markdown is good for both. Sorry all three.
Typora is a great WYSIWYG Markdown editor that uses MathJax to render LaTeX mathematical expressions.
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.
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.
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.
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.
I would advise anyone who values their time against using LaTeX for any document that doesn’t primarily consist of mathematical formulas.
It’s almost impossible to do professional quality typesetting in MS Word. Last time I really tried was about 10 years ago. I spent like 4 hours trying and failing to fix basic typographic mistakes in another person’s 20-page document, and then gave up and did the whole thing over in InDesign in 20 minutes, with great results.
In LaTeX, you can theoretically do anything you want but unless there’s already a template for it (or you have numerous or long documents targeting the same output style, for which you want to make a template and then mostly rely on automatic layout), it’s going to take a huge amount of time. It’s a good tool if you want output that is “good enough” for many practical purposes without direct human input, but it is especially difficult to do anything special-cased for a particular spread (moving images, text boxes, diagrams, ... exactly where you want them).
LaTeX is great for things like auto-generated documentation, long structured outlines, legal documents, or math papers full of complicated formulas. LaTeX is abysmally ineffective for posters, magazines, or the like. I find that for the vast majority of content in between those extremes (e.g. college humanities homework, non-technical journals, resumés, menus, coffee-table books, novels, poetry, personal letters, ...), InDesign ends up giving nicer output with less headaches.
From what I can tell, Adobe follows the more technical approach, though I’ve only looked over my wife’s shoulder. The fact that I’m just producing PDFs with LaTeX is also different. If I’m writing a web essay, I don’t mind using straight HTML/CSS, even markdown doesn’t really convey many benefits for me.
InDesign is used when you need precise control of the output. For instance controlling exactly how figures are placed, you might more advanced control of how text flows between boxes, etc. It also has tools for very precise control of how the type is set, how big space should there be between letters and words, how should the right edge of columns look, should there be different number of columns on different pages, etc.
Some of those things can be somewhat managed in Word, but you'll have to fight a lot of the automatic stuff, really not worth it if you are a full time design professional, much cheaper then to buy an expensive InDesign license.
Latex is pretty good at having sane defaults. This was a bigger issue back in the days when the defaults of Word were frankly terrible. Today it's to a large extent about style choice. If you publish in an area where Latex dominates, the Latex styling will make your document appear as more serious. Latex also generally uses a more advanced type setting engine, for example it might join "fi" with ligatures etc. This can also improve the look of the document.
Some people like the fact that you can manage Latex code as raw text. For instance using a VCS to manage version history. Word has some built in version management functionality, but it's quite clunky compared to Git.
Personally I gave up on using Latex after my first master thesis and tend to use Word. I get too caught up in the formatting when I use Latex. Maybe it's too much power to handle for me?
Curiosly, I found one while browsing at https://www.overleaf.com. LaTeX again :D
There's also other advantage to using LaTeX, and that is the flexibility that comes with macros. Need to change some notation mid-way through your writing? It's trivial if you've used macros. Need to simplify some commonly used pattern? Define a new macro!
Each tool has their place. Except Word, Word just sucks! (j/k, Word is brilliant when doing collaborative edits with non tech-savvy people, the track changes functionality is great, and not easy to replicate in other environments)
Another way of gaining this advantage is to use something you're already paying for like an internal wiki.
It’s a typesetting tool designed for producing paper documents. You should use it for your company’s magazine, menu, posters, and published books, not for your auto-generated technical documentation, your blog posts, or your internal emails.
The previous commenter wrote about what to do if you “don't want to spend a few $10k on professional typesetting software.” That’s much steeper than most people will spend on professional typesetting software.
Probably you've heard that only real men write LaTeX using plain text editors. I'm not a real man enough, so IDE like TeXnicCenter or Texmaker is needed :p
These days, personally I use Pandoc or Halibut (https://www.chiark.greenend.org.uk/~sgtatham/halibut) for anything not complicated. Or if working on team, then 'unfortunately' MS Word. Well, not every of us are nerds :)
No, we have CS interns from the local college who invariably ask about it. We only have them for a few months, so I've probably answered that question several dozen times in the past few years. I know they use LaTeX for their papers as required by their CS department, so I know why we get the question. I'm just tired of answering it.
> Word is a pain if you need something other than very standard formatting.
I don't disagree with that, but our standardized formatting is to use the default styles. Use Title for the doc title, use Heading 1 for each major step or process if the doc has more than one (most don't) and Heading 2 for each individual step. This means the Navigation Pane serves as your document navigation. Most of our docs are less than 20 pages or so (and most of that is screenshots).
I think you missed the point you were trying to make here because nobody has any difficulty reading the PDFs rendered from latex.
Half the people that manage our doc are non-programmers. They're not learning LaTeX. They're not editing raw PDFs while the other half of the team uses LaTeX.
Also, what's wrong with
(or better yet having your IT department / your provisioning system for new developer machines / whatever do that for you)? If your position was "Documentation edited by lots of people should not require weird CTAN modules," that I would agree with. You can write perfectly good documents of all kinds with just what's in texlive-latex-recommended.I think the proper analogy is like editing documentation in PDF. Software that can edit PDFs is expensive and difficult to use, like LaTeX can be (difficult, not expensive, just in terms of time).
Call it LexDown or something even less mellifluous and free millions from the tyranny of Word style sheets forever.
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.
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.
If only there was a way to create a Word document that forbids manual formatting it could actually be usable.
Furthermore, our documents can't be written in LaTeX because half the people responsible for maintaining them come from a non-technical background with no experience in programming. No, we are not going to inflict a WYSIWYG LaTeX editor -- all of which are far less usable than Word -- on people just because some technical people want to pretend they're programming.
Nevertheless, our CS interns invariably say, "Why don't we use LaTeX for this documentation?" I understand why they want to. They use LaTeX for all their papers. However, it is inappropriate in our situation and has gotten to be a rather irritating question.
Yet you seem happy to prescribe your (extremely limited) views on everyone else without knowing their situation.
Good for you if all your documentation requirements are trivial, and I'm sorry to hear that your team cannot cope with trivial software installs or simple markup. Maybe the problems lie not with LaTeX...
It was very frustrating, because I noticed it just a few hours before the deadline. To work around of this bug, I had to insert manual page breaks (mostly randomly), and I had to make the vertical margins of the TOC pages smaller.
LaTeX has always generated the correct numbers in the last 25 years I've been using it. And if I got something unexpected, I was able to fix it for good (without document-specific hacks such as manual page breaks) by adding some macro calls. With LibreOffice and Microsoft Office, getting such a fix ready in 1 hour is hopeless for me, so I'll either miss the deadline or I hand in something incorrect and unprofessional.
Also: LibreOffice doesn't support character formatting (of a few words only) in the ToC. LibreOffice doesn't support omitting a few select sections from the ToC. LaTeX supports both.
Well, I had to re-encode my documents twice in that time, once to isolatin1, and once to Unicode, because I was writing in Spanish and German. But it was actually fun to figure how to make that translation happen completely automated and happen in a few seconds.
I mean it’s not like it must be either LaTex or a word processor. Markdown is sufficiently easy to turn into text nowadays there’s really no reason not to first instance.
And that’s assuming someone agrees with the general premise of this argument which I don’t think I do
Just use Markdown if you're so concerned with people writing Latex.
If you use version control for your code and do not treat documentation as an integral part of the software which accompanies each version, this makes the impression that documentation is just an afterthought.
To address the 'environment' issue, it is, in most cases, unproductive to not work on Linux where all of this stuff works out of the box.
Also, your idea that it is easier to write a /good/ document using Microsoft Word than using LaTeX hugely underestimates the complexity of MS word for anything moderately complex, and even more hugely overestimates the complexity of using LaTeX for simple things. Somebody who has the job to write code in Python or Go should be easily able to document an API in LaTeX within two hours.
And to add finally, maybe you don't believe the world will continue to move without using MS office. Be assured, there are quite a few large companies which have ditched office (say, Google) and this was not the slightest obstacle to their further success.
A Markdown -> LaTeX -> pdf pipeline was how I wrote all of my algorithm assignments in college. I wrote things like:
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.
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.
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...
∑_{0≤n≤k}n²
expands to
\sum_{0\le n\le k} n^2.
Some of these are suboptimal. But you can just change them, and make your own.
[0]: http://lpaste.net/362623
It have it use cases but writing long and complex documents is not one of them.
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.
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
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/introduction-to-html
I know observable as a whole is not open-source so I understand this may not align with the best interests of the company. Also observable is fairly new so I'm sure you have a lot higher priority features on the release radar. I honestly wouldn't mind paying for an application even if it was an electron app.
Anyways good luck with Observable! I think its a great notebook format with a great API.
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.
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.
Agree. As soon as you want to start having references to other parts of your document(s) RestructuredText wins out over Markdown.
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!
I agree that Markdown and friends have their place, but they quickly reach their limits. You write that "Pandoc can take care of the presentation for us," but in my experience, Markdown and such will only get you as far as "good enough." If you want to typeset complicated equations, or print something more complicated than a novel, you need more powerful tools.
Code formatting and tabels are also vastly easier with pandoc.
On an unrelated note, I hadn't checked out Pandoc's output in awhile, and this bit from http://pandoc.org/demo/example13.pdf looks pretty bad: https://i.imgur.com/Kxy4mic.png . Granted, the terrible word-breaking and spacing is TeX's fault, but typesetting usually seems to require dealing with a few special cases by hand. I wouldn't trust Pandoc, or any other program, to "take care of the presentation" without a bit of hand-holding.
I do fall back to LaTeX for certain formatting, but it's actually quite easy to build pass-through filters so that raw LaTeX can be inserted when specialized formatting that can't be easily simulated in Markdown is required.
I'm planning to use this to write a book in the near future.
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.
There is even a company, LeanPub, that is based on generating paper and e-books direct from Markdown.
https://pastebin.com/raw/H43MKTCq
Referenced utility script:
https://pastebin.com/raw/J6quT7Mj
For cases where you really need to share your doc with coworkers in an editable form, you can even define an MS Word target...
edit: Actually, I find that I completely agree with your point if "printed" is replaced by "shared in pdf format" and "rendered to screen" is replaced by "shared in plain text or HTML format".
Will the content be shown with fixed line lengths, or with responsive line lengths?
There's a little bit of opinion embedded in my original post, which is that PDF is an inappropriate format when intended for screens. It's okay if you're wanting to provide a primarily printed document on the web or in email, it's okay, but if your primary target is screens, PDF provides a pretty poor user experience.
It was referenced by Jeremy Howard in a HN comment [1] on the submission for their "Matrix Calculus for Deep Learning " HN submission of 18 days ago [2]:
>Jeremy here. Here to answer any questions or comments that you have. > >But more importantly - I need to mention that Terence Parr did nearly all the work on this. He shared my passion for making something that anyone could read on any device to such an extent that he ended up creating a new tool for generating fast, mobile-friendly math-heavy texts: https://github.com/parrt/bookish . (We tried Katex, Mathjax, and pretty much everything else but nothing rendered everything properly). > >I've never found anything that introduces the necessary matrix calculus for deep learning clearly, correctly, and accessibly - so I'm happy that this now exists.
[0] https://github.com/parrt/bookish
[1] https://news.ycombinator.com/item?id=16267593
[2] https://news.ycombinator.com/item?id=16267178
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.
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.
Try justifying text on a relatively narrow column in HTML, and then try it with LaTeX. There's a world of difference in readability between them.
LaTeX is techniques and heuristics from hundreds of years of typesetting for print, codified into a program.
HTML is at most 29 years old, and has only supported typesetting of any kind for a fraction of that. What typesetting capabilities it supports are designed by committees, and its primary purpose has always been screen display, never print.
In the simplest/best case, LaTeX will simply produce nicer-looking results for print. In more complex/worse cases, LaTeX can do things that HTML in a browser can't reasonably do at all for print, even with CSS.
> 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.
I can't answer this question directly because it's been a while since I attempted such a thing, but this is largely what I was joking about with the "the project is going down in flames" bit in my previous post. If you are concerned about accessibility, targeting a proprietary format that resists parsing for text-to-speech or fragment translation and doesn't support variable-width lines for screen readers is a bad idea. Tagged PDFs are really just a hacky attempt to fix the problem: HTML was designed with accessibility in mind from the beginning (though admittedly HTML/CSS/JS as used by modern websites do a very poor job of providing accessibility). Maybe there has been progress in adding this to pdflatex, but it's still a bad idea.
Typesetting my thesis in LaTeX (physics, 2000) was an amazing choice. I could hardly modify anything (it is doable but requires a lot of work and in the meantime you learn that the default is better) so I was left with the content.
I knew that it would just work and took from me all the philosophical sufferingbof choosing such and such fontvsize for the title of adjusting margins, or placing a graph.
Currently jerry-rigging a script to get html out of it by pasting the scrivener and exporting, while keeping pages 09 for print.
It....works, but I would not recommend it unless you have a clear reason to do both. And I'd recommend another program, as pages 09 will eventually be made incompatible on mac.
Ah that explains what’s going on at Safari Books...
What makes you say that? I'm just finished up my first published book. The entire thing is in LaTex, which is extremely powerful. With conditionals and macros etc. etc. So I make a print-ready pdf and I'm good to go.
I run the whole thing through pandoc and it spits me out an ePub that's good to go for the eBook version.
Works a treat. I do battle LaTeX some days, but the results are gorgeous.
I'd agree your use case is a good one for LaTeX.
[1] http://www.lyx.org/
Relevant bit:
If you want to get fancier, and have pygments in your system, you can use the minted package, instead.I did try minted once, but never used it in practice. The dependency on pygments making the documents more system dependent is less than ideal.
I agree that pygments adds a bunch of dependencies, which may be too much just to get some colored syntax highlighting.
` is a three-key combination AND a dead key on non-US keyboards.
For an example of its usage and look, here [http://asciidoc.org/INSTALL.txt] is the source from which this [http://asciidoc.org/INSTALL.html] page was rendered.
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).
* 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.)
\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)
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.
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}}
I have similar shortcuts for all maths symbols I use regularly. Here is an excerp from the configuration
2200 fa ∀ for all
2202 pd ∂ partial differential
2203 te ∃ there exists
2205 es ∅ empty set
2206 De ∆ increment
2207 gr ∇ nabla
2208 mo ∈ element of
(…)
220E qed ∎ tombstone
The last one is most sattisfying to type !
Edit: Oops, saw the sibling post. That also works, although sadly I can't take always advantage of that since I'm not always on Linux.