An incomplete guide to Markdown, LaTeX, and more, initially written for Jiawen Li.

markdown-latex-etc.md

Markdown, LaTeX, etc.

Caution

• (10/30/2016) I am not sure when and how this gist gained quite a few stars... But as stated in the v1.13 change log (from 06/16/2015): some content may be outdated, and I am not going to fix them. Moreover, having learned much myself, I do not necessarily agree with every point made in this document from 2.5 years ago. Therefore, please take views from this document with a grain of salt, and do further research as you see fit.

• This document was initally written for a friend of mine, Jiawen Li, so it might reflect some personal tastes here and there. For instance, some discussions are geared towards Windows, though *nix is obviously superior. For another example, when I say "you seem to love Sublime Text a lot," I'm certainly not expecting most people to love Sublime (in fact I never used it for more than three minutes in a row).

• This document is written in Markdown. The Markdown rendering engine on GitHub Gist is somewhat limited and easily confused, so there might be some rendering errors not intended by the author. For instance, in the section "Useful stuff for LaTeX beginners (and experts, occasionally)", the outermost numbered list should be numbered 1, 2, 3, ... But it is rendered instead as 1, 1, 2, ... on GitHub Gist due to the complicated stuff in between. (Maybe it's my syntax that's sloppy, but the document is rendered correctly on all of my local engines.)

• My suggestions regarding the Microsoft Windows platform (mainly about TeX) are based on my painful experience with it years ago. Things might have changed over the years when I was absent from the scene (though changes happen slowly in the TeX community). Also, I was sort of a moron back in the Windows days, so the solutions I know might not be the best available ones (even at that time). Use with caution.

• This document is released under WTFPL.

Table of contents

• Markdown vs LaTeX
• Useful stuff for Markdown beginners
• Useful stuff for LaTeX beginners (and experts, occasionally)
• Markdown + LaTeX?
• Tips for Microsoft Office users
• Version info

Markdown vs LaTeX

Markdown: lightweight;

LaTeX: power.

Useful stuff for Markdown beginners

Markdown is a super lightweight markup language. I have reason to believe that it is the most popular (non-HTML) markup language on the web (the other one being wiki markup, I suspect; however, markdown is far more elegant than wiki markup, at least in my opinion). Everyone can master (most of) Markdown in half an hour.

• Originally designed by John Gruber, it is introduced here along with the initial implementation; the syntax is defined here.

• Markdown was mainly popularized by StackOverflow and GitHub (as far as I know). It has grown to a million of flavors and a million of implementations; supported syntax varies across implementations. The core syntax is mostly the same. See StackOverflow Flavored Markdown and GitHub Flavored Markdown (GFM) for most used syntax.

• Markdown, in principle, supports all HTML tags (the reality depends on rendering engine). Therefore, when the bag of tricks provided by Markdown is not enough, just throw in some HTML tags. For instance, <del>strikethrough</del> renders to strikethrough.

• I often write Markdown on GitHub Gist, which automatically gets rendered. Unlike GitHub, private Gists are free. And you can clone (and even push to) a gist repo later if you'd like versioning and local editing.

• There are tons of local Markdown editors. Apart from Emacs Markdown mode, I like Mou on OS X (I'm writing in Mou right now for instant preview). Mou supports both HTML and PDF export. Of course, good Markdown editors exist for every platform (let's face it: a Markdown editor is not that different from a plain text editor).

• Code formatting in Markdown: backticks for inline code: `code` renders to code; indent by 4 spaces for code block, i.e., html <pre></pre>:

  #include <stdio.h>
  
  int main(int argc, char *argv[]) {
      printf("hello, world!\n");
  }
  

  Another block:

  #!/usr/bin/env python3
  print('hello, world!')
  

• Unfortunately, due to the simplicity of Markdown, math is not supported. Math support is usually achieved through MathJax (not for local text editing). Read the section "Markdown + LaTeX" for options to include math.

Useful stuff for LaTeX beginners (and experts, occasionally)

TL;DR: Jump to 2 (and stay a moron).

1. What you should know about TeX/LaTeX to distinguish yourself from morons (morons from a hacker's point of view, not offensive):

   • TeX is both a (markup) language and a typesetting system/engine, written by Donald Knuth; LaTeX is a (markup) language, or more precisely, a set of macros extending TeX, initially written by Leslie Lamport. Both are absolutely free, open source software.

   • TeX should be pronounced "tech" as in Greek "τεχνολογία", conviniently pronounce "teck" in English. Definitely not "tecks." To quote Donald Knuth The TeXbook chapter 1, "The Name of the Game",

     Exercise 1.1. After you have mastered the material in this book, what will you be, A TeXpert, or a TeXnician?

     Answer. A TeXnician (underpaid); sometimes also called a TeXacker.

     The pronunciation of LaTeX is more flexible. I always pronouce it as "lay-teck," but to quote Leslie Lamport LaTeX, A Document Preparation System, Second Edition section 1.3, "The Game of the Name",

     One of the hardest things about using LaTeX is deciding how to pronounce it. This is also one of the few things I'm not going to tell you about LaTeX, since pronunciation is best determined by usage, not flat. TeX is usually pronounced teck, making lah-teck, lah-teck, and lay-teck the logical choices; but language is not always logical, so lay-tecks is also possible.

   • While TeX was designed for power and precise control, LaTeX was designed with casual-user-friendliness in mind. To quote the official introduction,

     LaTeX is based on the idea that it is better to leave document design to document designers, and to let authors get on with writing documents.

   • The bible for TeX is The TeXbook by Donald Knuth (casual TeXackers: do NOT read). The definitive guide for LaTeX(2e) is LaTeX, A Document Preparation System, second edition by Leslie Lamport.

   • On March 18, 2014, Leslie Lamport was announced the 2013 winner of ACM Turing Award. So the architects of both TeX and LaTeX are Turing Award winners now. (Donald Knuth won Turing Award in 1974.) Bragging rights!

   • The current version of TeX is 3.14159265. Each release attaches one digit to the version number. The version number will be fixed to \pi when Knuth dies.

2. Installation (choosing your TeX distro).

   General advice: do download a complete distro; do NOT download a basic/smaller distro unless you have a genuinely bad internet connection. Two extra gigabytes of disk space usually isn't a problem these days (unless you have a 128GB SSD, in which case — I'm sorry). If your internet connection is slow, simply perform an overnight download, which will save you a lot of trouble later. (Yeah, MikTeX, I'm specifically talking to you. The not-so-tech-savvy beginner could run into nightmares when they later try to stretch the limits of a basic distro.)

   Below are platform-specific info.

   • OS X: MacTeX, based on TeX Live.

   • Other *nix: TeX Live.

   • Windows: there are two major contenders — TeX Live and MiKTeX (or proTeXt, a MiKTeX-based distro maintained by TUG, which "aims to be an easy-to-install TeX distribution for Windows"). According to the UK TeX FAQ (which, by the way, is a highly renowned source of TeX knowledge),

     Windows users nowadays have a real choice, between two excellent distributions, MiKTeX and TeX Live. TeX Live on windows has only in recent years been a real challenger to the long-established MiKTeX, and even now MiKTeX has features that TeX Live lacks.

     Of course, TeX Live also has features that MikTeX lacks. Most importantly, it is cross-platform, and maintained by the TeX Users Group, aka TUG. (In TUG I trust.)

     I'm not in the position to suggest a choice here. Apart from initial setup, the differences should be minimal for beginners if you install complete distros as I nagged you earlier. If you don't care (most beginners don't), pick the one whose name appeals to you the most — for instance, "proTeXt" sounds clever to me. (In case you don't see why it's clever, go back to 1.) If you do care, put in some research then. I've Googled for you here. Note that timeliness is important for comparisons in the software industry — for instance, you want to be cautious when taking advice from "Choosing between MikTeX 2.7 and Tex Live 2008." Customize the Google Search time range if you'd like to.

3. The canonical tutorial for beginners — The (Not So) Short Introduction to LaTeX2e. More tutorials/documentations: LaTeX documentation.

4. The canonical place to find LaTeX macros for symbols (depreciated; see next one) — The Comprehensive LaTeX symbol list.

5. The best place to find LaTeX macros for symbols — Detexify. (Draw symbol, out pops the corresponding macro).

6. One of the best sources of LaTeX usages and tricks — LaTeX on Wikibooks. But you don't need to go there intentionally. Just Google what you want, and chances are it will show up in the first few entries.

7. The best place to find TeX/LaTeX help from humans: TeX.SX.

8. The best document class: amsart.

   \documentclass{amsart}
   

9. The easiest way to format code is the verbatim environment. There are more advanced ways, e.g., the listings package.

   \begin{verbatim}
   #include <stdio.h>
   
   int main(int argc, char *argv[]) {
       printf("hello, world!\n");
   }
   \end{verbatim}
   
   \begin{verbatim}
   #!/usr/bin/env python3
   print('hello, world!')
   \end{verbatim}
   

10. Which editor should you use? (Assuming you are on Windows.) Two things to keep in mind:

    • LaTeX needs compilation, so your editor needs pdfLaTeX integration (or you need to go to cmd.exe / PowerShell to manually compile).

    • LaTeX is NOT WYSIWYG, which means you need a previewer. (Some genuine TeXnicians might type up a whole 100KB document without previewing; that's not the way we mortals work, and come on, why torture yourself and waste your beautiful Retina display.) So your editor needs previewer integration, or your previewer needs editor integration. The default previewer in MikTeX is Yap, if my memory doesn't fail me. It seems to be compatible with any editor (not sure, haven't used it for years).

    Given these, below are the options you could consider:

    • Sublime Text, which you seem to love a lot. I guess it doesn't come with LaTeX integration out of box, so you probably need the (official?) plugin LaTeX Plugin for Sublime Text 2 and 3. However, I highly suggest that you take this opportunity to explore a new language as well as a new / less familiar editor (knowing more never harms).

      Other reasons why I would recommend against Sublime Text:

      1. Sublime Text is closed source, proprietary software.

      2. Sublime Text is developed by a single developer (as far as my knowledge goes). The bus factor is too low.

    • Emacs. Yes! Emacs has out of box LaTeX integration, but to get the most of Emacs+LaTeX, check out AUCTeX. To install AUCTeX with the least amount of work, use ELPA (caution: require Emacs 24.1 or higher) — M-x list-packages in an Emacs buffer, and find auctex to install. Emacs+AUCTeX greatly speeds up LaTeX editing. They are so powerful that I don't really know what tricks I should list here. Anyway, grab the official AUCTeX cheat sheet first. You can also find some random tips in this gist.

    • If you want to get started with LaTeX right away, choose an IDE instead. Best IDE for Windows — TeXnicCenter (there are some controversies around this as always). Initial setup is guided and easy. It even offers clickable buttons for common constructs — fractions, integrals, etc., which makes it a bit contemptible for power users, but useful for learners.

    • ed, the standard text editor. Just kidding. (But do give it a try in case you have time.)

    • Give up Windows, and switch to *nix (including OS X, which is UNIX certified). It will open up a whole world of awesome open source software. (Of course, TeXnicCenter is also open source.)

11. (This is more advanced.) Ever want to create a beautifully typeset diary in LaTeX? Or novel? Or a weekly calendar? Then you need custom document classes. The canonical reference point — CTAN, the Comprehensive TeX Archive Network. It helps you locate packages that are already included in your TeX distro (a TeX distro, just like a Linux distro, comes with infrastructure plus a selected set of preinstalled packages), or if not, let you download them.

    Note that not all authors release their packages on CTAN — some prefer their personal websites. So Google for more (and sometimes better) options.

Markdown + LaTeX?

This is not easy. Options I know:

(Caution: I'm by no means knowledgeable on this subject, since I never mix the two — after all, I'm a mathematician, so whenever I need LaTeX I need it heavily. When I said "this is not easy," I really meant I don't know any easy approach — I might be overlooking some well-known and/or obvious solutions. Please proceed with caution; better yet, Google it yourself, or consult an expert.)

• 04/09/2014 update: I was told today that Mou, which I recommended above, actually has basic math (LaTeX) support. You need to enable math in Preferences, and the syntax is $$$ for inline math and $$ for display math (kind of weird, for us Knuth worshippers).

  Note that the support is pretty basic as far as I've tested. For instance, I tried a simple aligned enviroment and failed — output was squeezed into one single line. I also tried a more exotic substack and again got wrong, single line output, which, combined with the previous aligned example and a few more that I didn't list here, seems to suggest that multiple line constructs are all broken in Mou. (Suprisingly or not, symbol support is pretty comprehensive; I throwed at it a bunch of amssymb-only symbols that happened to pop to mind, e.g., \unlhd and \Subset — they all got rendered.)

  Anyway, not-so-sophisticated inline and one-liner display math already go a long way, and might be sufficient for most not-so-technical purposes.

• 04/09/2014 update: I also did a little bit of research while waiting in line, and found quite a few supposedly MathJax-friendly markdown editors on MathJax's official website. See this page: MathJax in use — applications. If I've got time, I'll test some of these and report my findings.

  A note on MathJax (may skip): MathJax is one of the greatest open source web projects, from a mathematician's point of view. Most of your (my) favorite math/physics websites, forums, and blogs are powered by MathJax. Math rendered by MathJax is beautiful and elegant, just as in TeX (with Computer Modern or Lucida Bright) — by the way, the elegance of mathematical typography is one of my reasons for loving math. MathJax even lets you copy raw TeX code when available. Unfortunately, in some places, for instance PlanetMath (powered by planetary), MathML — the terribly unreadable XML language — is the only option available, which is pretty much useless if you want to keep your source code cross-platform and human-friendly. You can view source in PlanetMath, though, so MathML is not a big problem. (MathML is currently supported by Gecko and WebKit but dropped by Blink; I think Google made the right choice. Though I'm not in the position to say this, MathML wasn't a good idea in the first place — TeX ought to rule it all. Why create a sort of one way language, with which you can't possibly recover the math by looking at the source code, or re-generate the source code without machine intervetion?)

• Pandoc, "a universal document converter." It's surely a powerful tool: it can convert documents between Markdown, LaTeX, HTML, PDF, and more (even docx). Moreover, it supports inline LaTeX in Markdown. Remarkably, unlike MathJax, it works outside the browser.

  Power doesn't come for free. For one thing, there's a little bit of learning curve. Moreover, (for those of you who would laugh at pre-compiled packages,) installation via Haskell platform on OS X 10.9 is a nontrivial task. Haskell platform seems to be broken on OS X 10.9 with Xcode 5 and hasn't been fixed five months after the 10.9 stable release. (Anyway, a quick fix will do.)

• Some online Markdown editors support math. I know a seemingly cool one: StackEdit. It supports inline LaTeX (via MathJax), instant preview, autosave (tested, no worries for accidentally quitting your browser), HTML/PDF exportation, Google Drive / Dropbox syncronization, etc.

  Caveats:

  • StackEdit (surprisingly) doesn't support Emacs keybindings, which in principal should work with any text field. There is an open issue here.

  • StackEdit doesn't support HTTPS, which means NSA could easily grab what you type. The scene has changed since I last checked it. HTTPS is now supported. Hooray!

  By the way, I was introduced to StackEdit via Math.SE community ads.

• Looking for other options? Sorry, there is a trade-off between ease-of-use and power. The last resort is full LaTeX.

Tips for Microsoft Office users

1. Stop using Microsoft Office, RIGHT NOW;
2. Do 1;
3. Do 2;
4. ......

Why I hate Microsoft Office

1. Microsoft Office is non-free, free both as in "free speech" and "free beer."

2. Microsoft Office is not only non-free, but also expensive.

3. .docx is proprietary format. Microsoft has full control over it (correct me if I'm wrong). Hopefully they at least released it as a standard, so vendor lock-in won't happen. However, Microsoft could change mind any time.

4. Most Microsoft Word documents are text documents. But they are not readable and editable at all with text editors (in principle you could read and edit XML, but seriously, who would bother to do that). So why Microsoft Office when plain text is nice, elegant, efficient, fast, and free? Even when you need some formatting, there are Markdown and other plain text, human readble, and open source formats. I really hate it when people send me docx or ask me to send docx. Why assume I have the crap proprietary software installed? You could at least save as PDF before sending to me.

   (PDF is another story. It started as proprietary, but was released free of charge a long time ago, and has since been made an open standard. There are a good number of great open source PDF generators, PDFLaTeX being one notable example. And after all, PDF and PostScript are intended for printers — they are not so easily made human readable without an interpreter, so using a proprietary format in this setting is reasonable.)

   You might argue that docx can be edited with LibreOffice, OpenOffice, etc. However, first of all, documents created by Microsoft Office are not always (always not) rendered the same in these Offices; 100% compatibility has never been achieved. If you choose to work with Microsoft Office documents, you either be cheap and worry about lock-out/lock-in/damage/permanent damage (people who love Microsoft Office are often not competent enough to do back-up right), or throw your money at Microsoft. And point is: plain text is both free and reliable in the first place.

5. Microsoft could change their pricing model at any time, just as Adobe did to their Creative Suite. They've already been exploring the subscription model via Office 365 for a while, which is $99.99 a year (home). In the future, Office might turn to subscription only, meaning that you would never have a full copy of your (already crappy) software that is guaranteed to work regardless of time, and that they could raise the subcription price at any time and drive you nuts instantly. (Microsoft recently released Office on iPad, which is already subscription only. Watch out for the trend.)

6. Forgot to highlight one major annoyance. As you already know, I hate Microsoft Office; however, as mentioned in 4, I'm forced to keep the crap installed and occasionally launch it (which takes something around ten minutes just to launch) thanks to other people who insist on Microsoft Office. Every single launch deepens the hatred.

7. (05/04/2014 update) Apart from storage, transmission, and distribution, Microsoft Office — and word processors in general — are also bad for writing. To quote the AsciiDoc official introduction, the "Word processors, the real writer’s block" section,

   When you are in the writing (i.e., typing) phase, you want the words to flow onto the screen with minimal distractions and interruptions. Flow, not just time, is essential.

   Most word processor excel at distracting you from writing. The result: you write less (ironic, huh?).

   In a word processor, before you can type the first word on a blank screen, you're forced to think about what font family you want, what font size you want, what lines spacing you want and so on. Once you do get going, auto-correct, spelling and grammar suggestions entice you to backtrack and lose your next thought. "Smart" quotes and auto-linking messes with the text as fast as you can enter it. If you paste text, it likely gets added to the document with a different font family, size and even color.

   Undo. Undo. Undo!

   Let's not even talk about inserting source code. The designers of word processors clearly did not.

   Format. Format. Format!

   After burning time fighting with its interface, you rightfully conclude that the word processor is trying to sabotage your writing process.

   We need an easier way to write!

   But how?

   It's kind of ironic to quote AsciiDoc in a document promoting Markdown, but at the very least, we are all against Word. This section is so well written that I can't resist the temptation to quote it out in full. Moreover, I actually typed it in myself to enjoy it to the fullest.

8. (05/04/2014 update) By the way, there is more to quote against docx (and XML in general), this time from Linus Torvalds, in a Google+ comment:

   no [sic], XML isn't even good for document markup.

   Use 'asciidoc' for document markup. Really. It's actually readable by humans, and easier to parse and way more flexible than XML.

   XML is crap. Really. There are no excuses. XML is nasty to parse for humans, and it's a disaster to parse even for computers. There's just no reason for that horrible crap to exist.

   If you don't believe in me, you certainly believe in Linus don't you, who is much better at this art than you and me. If you don't even believe in Linus, you are not my reader in mind anyway.

9. There are infinitely many other reasons to hate Microsoft Office, which grabs money from the most basic workflow — text editing. The reasons to hate Microsoft Office occur infinitely often in the decimal expansion of \pi.

Version info

Current: Version 1.13, updated 06/16/2015. Changes:

• Fix broken links and retarded English;
• Warning: some content may be outdated; I'm not going to fix them.

Version 1.12, updated 05/04/2014. Changes:

• Add pointer to my other gist, which gives some random tips on Emacs and AUCTeX;
• Quote AsciiDoc official intro to make the point that Microsoft Word is not only bad for distribution — it is also bad for writing.

Version 1.11, updated 04/10/2014. Changes:

• Discuss basic math support in Mou;
• Add MathJax related stuff (with pointer to reportedly MathJax-friendly markdown editors).

Version 1.10, updated 04/06/2014. Changes:

• Add caution about the Micsoft Windows platform;
• Add installation instructions;
• Add tips about finding custom packages (namely, CTAN);
• Restructure version info and push it to the end of the document.

Version 1.04, updated 04/05/2014. Changes:

• Add Caution at the beginning (after I found out that the list numbering is ruined)
• Add one major reason of hating Microsoft Office.

Version 1.03, updated 04/05/2014. Changes:

• Add pronunciation guide for LaTeX;
• A few tiny changes.

Version 1.02, updated 04/04/2014. Changes:

• Tweaks and tiny fixes here and there.

Version 1.01, updated 04/04/2014. Changes:

• Add discussions on LibreOffice/OpenOffice.

Version 1.0, written 04/04/2014.

• First draft.

Just a note, the Atom text editor has a markdown-preview-enhanced plugin that supports markdown and LaTeX