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