Reach for Markdown, not LaTeX
blog.jez.io
blog.jez.io
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.
make html pdf
https://pastebin.com/raw/H43MKTCq
Referenced utility script:
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
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.
\usepackage{listings}
\begin{lstlisting}
your code here
\end{lstlisting}
Relevant bit:
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
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.
\begin{minted}{python}
def square(x):
return x * x
\end{minted}
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
apt-get install 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:
* **Basis**. Prove for $n = 0$...
* **Induction**. If \mathcal{G} is a graph ...
\begin{equation}
...
\end{equation}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.
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
# Section Name
\section{Section Name}
*important stuff*
\emph{important stuff}.
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.
Here is a table in pandoc markdown:
| Header 1 | header 2 |
|-|-|
| Column 1 | Column 2 |
Editing ascii tables with no editor support is painful.
There's also some org functionality in vim plugins, though I've never used them, so I don't know how much they cover.
I find that you should use org only if you use Emacs. Vim plugins for Org are very limited, and this is even more true for other editors.
Judging a technology only for its technical merits is unproductive. Markdown has "won", it's everywhere and everyone can learn to use it. Those are damn powerful advantages.
Using Markdown, I gain the ability to read and write on a smartphone or tablet in my phone or tablet, which for some notes is extremely convenient. Many times being able to access my notes on philosophy from my phone during a bus commute allowed me to develop and write down a thought, which would have been a pain to do with other technologies. Of course I could have done the same with other options, but this ubiquitous convenience and effortlessness is great.
What I'd love to see is a way to transition easy-to-write-everywhere to more powerful type-setting easily when needed. May be combining Markdown and Latex? Or converting Markdown to Latex before publishing?
I'm sure this exists already; I just haven't needed it enough yet :)
If popularity alone were sufficient for technological choices, we wouldn't even be having this discussion (and we'd all be using Windows). I try to choose my tools according to how well they work for me. Markdown, in my opinion, is a poor choice compared to org, but I can use it to collaborate with others, no problem.
As for the transition from light markup to TeX, that's pretty much the point of the OP, isn't it? Maybe the break point is different for everybody. For me, LaTeX imposes no extra cognitive load, but then again, I've been using it extensively for many years. If I'm need for something lighter, it'll be org (but really, org usually wins for me because of how well it does all the other stuff, not just the markup part).
- Should the table appear flushed to the left? Centered in the page? flushed to the right? Full-width or only content-width?
- What happens when Column 1 is long? Should the text wrap inside its own cell, overflow, or what?
- Which row/column lines should appear? None? All of them? Only those that separate headers?
These matters will only get more complicated once the table starts growing.
Of course, you could say that all these issues are presentational, and hence it's your theme's job to handle, not yours. That is fine until it breaks and you need to fix it though...
Code blocks are very easy in latex too. Install the "minted" [1] package and you can just:
\begin{minted}[python]
def something():
...
\end{minted}
I do think that writing simple files in markdown feels better than doing it LaTeX. Unfortunately, as the document starts getting more complicated it's always been easier for me to just turn to "pure" LaTeX than to try and deal with it through pandoc extensions.
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.
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?
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. 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.
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.
Apart from that: Microsoft Word /seems/ easy to use but this is not really true, by far. To typeset a minimal LaTeX document as for a homework assignment, very little learning and boilerplate is necessary. This can be done /quicker/ than in Word - an intelligent person will need half an afternoon to write a short presentable text in LaTeX, and the learned knowledge works forever. What you are assuming is that people are already used to write high-quality structured documents in Word, and this is, for most people, simply not true, as Words gets heavily in the way of writing in a structured approach. The ribbons UI has not really helped with that - I curse every time I have to search for a section formatting style in that terrible drop-down menu.
Now when it comes to writing seriously complex larger text documents, like a large software documentation, a piece of literate programming, or a PhD thesis, MS Word is far far behind. It is simply not up to the task.
You also say that Word has been getting better, but having occasionally been forced to work with Microsoft products in the last nine years, I really don't see that. The only thing that changes is the user interface. It is hardly believable that Microsoft will use office programs to try out new paradigms and software metaphors.
And to add, I am also pissed by the appearance that Microsoft - not specifically for this comment, but very much in general - seems to follow the strategy to make their commercial products mentioned as much as possible in the context of free and open source software, in forums and in places such as reddit. There may indeed be a few people which use .NET or c# or the Linux subsystem or which give up the power of UNIX shells for an inferior solution, but I just can't get rid of the strong impression that the huge majority of such comments are just product marketing done by some PR company. It is annoying. And completely hollow. As here, somebody who really has medium knowledge on how to use LaTeX will rarely suggest to use Word instead.
I didn't say that. Like, not even close, where did you get that from? In fact I haven't noticed a single improvement in Word since 2007 except the installer.
> And to add, I am also pissed by the appearance that Microsoft - not specifically for this comment, but very much in general - seems to follow the strategy to make their commercial products mentioned as much as possible in the context of free and open source software,
I'm seriously bothered that you're accusing me of being a talking head for some multinational corporation. I'm a moderately happy customer, that's all. Our financial relationship is 12 euros a month, from me to them.
If you really can't discuss the merits of software alternatives separately from some big "everybody who disagrees with me is on the enemy's payroll" conspiracy theory, the IMO you already lost the argument.
> As here, somebody who really has medium knowledge on how to use LaTeX will rarely suggest to use Word instead.
I used LaTeX in anger, then noticed that getting comfortably good at it doesn't make it a less shitty experience, and I decided that I preferred Word. Please note that I think that both Word and LaTeX are pieces of shit, I simply think that Word is slightly less shit (or, well, shit in a way that bothers me less and you're free to disagree).
I think the fact that you can't imagine anyone knowledgeable could prefer Word over LaTeX shows a severe lack of empathy and imagination on your part.
I have /taught/ MS Word 5.0 in 1997 or so, and written large documents (technical translations) in Word 6.0. Given that I had deadlines and I needed to pay our rent, I had really nerve-wrecking experiences when the whole system failed to work in the early morning hours before our dead-line. Well, Windows is more stable today, but usability of MS Word has not improved. All over all, I am saying that the WYSIWYG or "glorified typwriter methaphor" is just plain wrong if you want a consistently formatted large document. Consistency matters, and it is only achievable if standardized styles are applied to pieces of text. At the some time, enormous flexibility is needed, and this is where WYSIWYG fails. Some people here mentioned that formatting text for the web is different from optimum typesetting of paper documents, which have a fixed width. To some extend, this is true. But here is the rub: The fixed-length lines of paper documents, as well as the whole page layout, is optimized for easy reading - as well as everything else, for example the fonts. Of course you can have a web document with arbitrarily long lines. But there is no browser which formats it for good readbility on a 38 inch wide-screen display. It will make lines that are more than 120 characters long, when optimum readbility is at about 65. LaTeX takes care of the latter, that is why LaTeX documents are more readable.
> Please note that I think that both Word and LaTeX are pieces of shit, I simply think that Word is slightly less shit (or, well, shit in a way that bothers me less and you're free to disagree).
If you really know LaTeX well, it is excellent for formatting large technical documents with minimum efforts. You have to learn how to maintain and compile a biliography, and an index, but this is not really difficult with the tools which TeX and LaTeX provide. Admitted, some documents are not worth that effort, but everyone who has worked with a large software or API knows well that once documentation is longer than maybe 70 pages, finding information becomes the real issue. Again, Word is of no help here.
That has nothing to do with empathy. It is a technical question. Maybe word is useful for some rather limited uses, but even for a one-page letter, LaTeX is less fuss if you care about consistent formatting.
> I'm seriously bothered that you're accusing me of being a talking head for some multinational corporation. I'm a moderately happy customer, that's all. Our financial relationship is 12 euros a month, from me to them.
It would be totally dumb to accuse an individual of astroturfing for a company, because it is nearly impossible to prove. (However, actually I have managed to spot at least one paid shill who admitted it later - if you know German, you can read about it [here](https://www.gen-ethisches-netzwerk.de/agrobusiness/umkaempft...).
That said, it is totally obvious that Microsoft is taking influence here (probably by using various intermediate companies) , and the strategy is clearly to mention Microsoft products as often as possible in comments and contributions which appear to be, but are not, from unpaid users. Microsoft is even well-known to do that since a long time, so this is not a outlandish accusation but simply a fact. The desired effect is totally clear as well - if something is mentioned often enough, it becomes familiar, and what is familiar becomes unconsciously associated with "liked" or "proven", and if then people have to make a choice with limited information and under (possibly self-inflicted) time-pressure, they chose what they have heard or seen often. It is exactly how advertising works, and it should just be called as that.
Of course, the solution is not to accuse individual contributors of astroturfing which cannot be proven, but rather to lay out how the product which is promoted is really inferior and a really really bad choice for the task in question. Let's keep it at that level.
The markdown source is a great deal more readable -- all of those little substitutions that seem inconsequential individually add up to a lot less noise in your document source. Equations just pass through to LaTeX, so you write them the same. All of my floats started out using markdown syntax, which is really beneficial when drafting, since much harder to mess up a single line when cutting and pasting it around. In the end, I wanted finer control over how they looked, so I pasted the generated tex into my sources and worked from there.
My one caveat is, you absolutely must understand LaTeX first, or you will be in for a bad time. Pandoc + markdown + LaTeX is no substitute for understanding LaTeX, but it's a huge win if you're already familiar with LaTeX and you're tired of typing backslashes.
Finally, the recommendation to use article is unfortunate. Memoir will save you a lot of headaches.
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.
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
md2 = x => md([x[0].replace(/\$(.*?)\$/g, m => tex([m.slice(1,-1)]).outerHTML)])
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.
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.
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.
* 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.)
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).
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.
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.
\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)
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.
But it's required some regex "replace_all" to be applied when rendering the PDF.
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.
The other goal being to communicate with others.
Markdown is good for both. Sorry all three.