Today, in an effort to combat this particular scourge (and in keeping with the theme of this blog’s title), I will be your Virgil on a tour through the nine circles of LaTeX hell. My intention is not to shock or frighten you, dear Reader. I hope, like Dante before me, to promote a more virtuous lifestyle by displaying the wages of sin. However, unlike Dante I will refrain from pointing out all the famous people that reside in these various levels of hell. (I’m guessing Dante already had tenure when he wrote The Inferno.)
The infractions will be minor at first, becoming progressively more heinous, until we reach utter depravity at the ninth level. Let us now descend the steep and savage path.
1) Using {\it ...} and {\bf ...}, etc.
Admittedly, this point is a quibble at best, but let me tell you why to use \textit{...} and \textbf{...} instead. First, \it and \bf don’t perform correctly under composition (in fact, they reset all font attributes), so {\it {\bf ...}} does not produce bold italics as you might expect. Second, it fails to correct the spacing for italicized letters. Compare $latex \text{{\it test}text}$ to $latex \text{\textit{test}text}$ and notice how crowded the former is.
2) Using \def
\def is a plain TeX command that writes macros without first checking if there was a preexisting macro. Hence it will overwrite something without producing an error message. This one can be dangerous if you have coauthors: maybe you use \E to mean $latex \mathbb{E}$, while your coauthor uses it to mean $latex \mathcal{E}$. If you are writing different sections of the paper, then you might introduce some very confusing typos. Use \newcommand or \renewcommand instead.
3) Using $$...$$
fleqn to stop working. Moreover, it is syntactically harder to parse since you can’t detect an unmatched pair as easily. Using [...] avoids these issues.
4) Using the eqnarray environment
If you don’t believe me that eqnarray is bad news, then ask Lars Madson, the author of “Avoid eqnarray!”, a 10 page treatise on the subject. It handles spacing in an inconsistent manner and will overwrite the equation numbers for long equations. You should use the amsmath package with the align environment instead.
Now we begin reaching the inner circles of LaTeX hell, where the crimes become noticeably more sinister.
5) Using standard size parentheses around display size fractions
Consider the following abomination: $latex (\displaystyle \frac{1+x}{2})^n (\frac{x^k}{1+x^2})^m = (\int_{-\infty}^{\infty} \mathrm{e}^{-u^2}\mathrm{d}u )^2.$
Go on, stare at this for one minute and see if you don’t want to tear your eyes out. Now you know how your reader feels when you are too lazy to use \left and \right.
6) Not using bibtex
Manually writing your bibliography makes it more likely that you will make a mistake and adds a huge unnecessary workload to yourself and your coauthors. If you don’t already use bibtex, then make the switch today.
7) Using text in math mode
Writing $latex H_{effective}$ is horrendous, but even $latex H_{eff}$ is an affront. The broken ligature makes these examples particularly bad. There are lots of ways to avoid this, like using \text or \mathrm, which lead to the much more elegant and legible $latex H_{\text{eff}}$. Don’t use \mbox, though, because it doesn’t get the font size right: $latex H_{\mbox{eff}}$.
8 ) Using a greater-than sign for a ket
At this level of hell in Dante’s Inferno, some of the accursed are being whipped by demons for all eternity. This seems to be about the right level of punishment for people who use the obscenity $latex |\psi>$.
9) Not using TeX or LaTeX
This one is so bad, it tops Scott’s list of signs that a claimed mathematical breakthrough is wrong. If you are typing up your results in Microsoft Word using Comic Sans font, then perhaps you should be filling out TPS reports instead of writing scientific papers.
Steve you should convert this over to a LaTeX style guide! Which includes not just these circles, but also how the hell one should format LaTeX equations in a text editor. We have coding style guides, why not LaTeX styling guides? (See http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) for example.
Ah, yes, this could become the Strunk & White of LaTeX coding. Not a bad idea, but I guess I don’t have time for it.
There are a lot of Strunk&White haters out there.
http://chronicle.com/article/50-Years-of-Stupid-Grammar/25497
I haven’t read it, but I like the name “Strunk.”
Dave, if you’re interested in tracking-back Google’s coding standards, it’s evident that these standards largely reflect Bjarne Stroustrup’s web page “C++ Style and Technique FAQ”. In turn, the ideas of Stroustrup’s FAQ are developed at greater length in a (remarkably interesting) document that Stroustrup helped write, and that his FAQ recomments: JSF air vehicle C++ coding standards.
Kind of like $latex LaTeX$ documentation, software documentation manages to be incredibly interesting at the microscale, yet utterly daunting at the macroscale.
Someday (pretty soon) we’re going to understand the body’s healing processes with similar molecular-level epigenomic granularity; hence my own interest in these complexity-management techniques.
Nice list. One issue I’ve never figured out is at the intersection of 5) and 8). How do you get a nicely formatted bra-ket when the stuff inside includes large formulas?
You use “\left\langle” and “\right\rangle”. If you need to split between lines, use “\left.” and “\right.”, and if the sizes don’t match across lines, use \bigl (\bigr), \biggl (\biggr), \Bigl (\Bigr) or \Biggl (\Biggr), whichever is appropriate.
@prasad, the simplest method is to use \left and \right, as in the following:
\left| \frac{1}{2} \right\rangle
If you compare that to just |\frac{1}{2}\rangle, then you can see that the fraction overhangs the top and bottom of the ket a bit. This effect will be even more exaggerated if you have a bigger formula.
There are more subtle methods that give you finer control over the spacing and size, but this is good enough to avoid winding up in circles #5 or #8.
I mean how to get the sizes of the equal for
gah, it ate all the useful text. I mean, when you have
You should size all brackets manually. LaTeX doesn’t know how to do it. For example, use \bigl\langle u \big\vert v \bigr\rangle for < u | >. The scaling commands are \big, \Big, \bigg, \Bigg.
It is also better to use \lvert instead of \vert or |. In all of these commands, “l” and “r” stand for left and right, and give improved horizontal spacing.
Prasad: the only real way to automatically handle this is to force the height in each half to be the maximum of the two, by various nasty tricks.
E.g.
\newcommand{\ip}[2]{\left\langle{#1} \vphantom{#2} \right\vert \left . {#2} \vphantom{#1} \right\rangle}
A half-assed approach is \left \langle foo \left \vert \right . bar \right \rangle , which keeps the angles the right size as a matched pair, but may incorrectly size the vertical bar in the middle.
Both of these can prove very distracting and ugly when there are many differently sized ones near each other, though.
You can also use \middle. The following should work for the inner product between A and B:
\left\langle A \middle\vert B \right\rangle
Handy, thanks. Technically, it’s an e-tex extension, but any recent installation will have it. I will definitely be using this in the future.
On the related Path to ArXiv-purgatory:
1. Raw latex commands left in the \textit{plain text} abstract.
2. Double
spacing
Once you’ve realized that your LaTeX skills are atrocious, you can go here to fix them 🙂
http://tex.stackexchange.com/questions/577/best-practices-references
Another outstanding reference that covers pretty much every aspect of typographic excellence is the documentation (587 pages!) to Peter Wilson’s memoir.cls. Wilson’s “once class to rule them all” encompasses more than thirty other LaTeX classes, debugs them, provides handles to customize them, and (best of all) carefully explains the typographic rationale for using them properly. I use the memoir class to produce my wife’s books, and the overall experience has been very pleasant.
LOL … another invaluable typographic resource is the on-line game/trainer Kern Type. My wife and I disagree about many matters that other couples consider important, but because she and I agree on kerning, all else is negotiable.
In addition to seconding Suresh’ recommendation of the $latex text{TeX}$ StackExchange, I would also like to commend the PDF documentation to three packages:
• mathtools
• tensor
• fixltx2e
All three documents show how to fix numerous typographic infelicities and outright bugs in $latex text{LaTeX}$ and amsmath. In some cases these bugs had bothered me for years, and in other cases they had escaped my conscious notice. Almost anyone who reads these documents will say “Oh, so that’s how to make it better!” 🙂
Oh yeah … a final invaluable document is A Few Notes on Book Design, by Peter Wilson (author of the magisterial $latex text{LaTeX}$ memoir class). This document is included in standard $latex text{LaTeX}$ distributions as the file “memdesign.pdf”.
Remember, when Donald Knuth designed $latex text{TeX}$, as he describes in his article Mathematical Typography (1979), his objective was not to exceed the beauty and utility of traditional typography, but rather (more modestly) to approximate it. Perhaps Knuth succeeded so well, because his grasp of typographic history and artistic tradition was so firm.
Let me just mention here a thread started by Pieter Kok on G+. (I don’t know how to link to G+ posts…) People have started swapping tips and tricks for typesetting quantum-related stuff. It gives me the idea that we should crowdsource the creation of a “quantum.sty” package. If there is interest in that, then I can turn it into a separate post and we can solicit suggestions for code and how to organize the package. I think it would be a useful tool.
I host a LaTeX package with exactly this name on my web site. I haven’t uploaded this particular package to CTAN, as it’s mostly a collection of useful shorthands for commonly used notation, simple commands for Dirac notation, etc. And it seemed arrogant to grab the “quantum.sty” name for this. (Once a package name has been taken on CTAN, it’s essentially taken forever, and can never be reused for something else.)
I’m sure lots of people have their own private collections of useful quantum LaTeX definitions. Maybe this could serve as a starting point for gathering them into a single package, and putting it on CTAN. I’d be happy to help coordinate this, if there’s interest.
Thank you Suresh for posting those links.
I just skimmed through
http://anorien.csc.warwick.ac.uk/mirrors/CTAN/info/l2tabu/english/l2tabuen.pdf
and my jaw dropped. I’d been smugly agreeing with the points in Steve’s post, but now feel considerably less smug.
It’s essential reading for ancient Latex users from the previous century.
Wow. I like that two of the “deadly sins” will also land you in LaTeX hell. How appropriate! 🙂
Never use \left or \right. See Section 6.1 of the AMS Short Math Guide to LaTeX ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf for an explanation.
Thanks for the link!
I try to use \big (and it’s variants) and avoid using \left and \right. My opinion is that using \left and \right will only put you in LaTeX purgatory, not LaTeX hell. But people should definitely be made more aware of the \big family of commands.
Why can’t LaTeX – the great tool that let’s you concentrate on content instead of formatting – even infer the right height of brackets by itself in the first place? I’m not even demanding handling of Dirac notation, just plain well-formed formulas of open and closed brackets?
I guess you might conceivably want to use a rangle that doesn’t behave that way. I think the right way to do these things is with macros, like this.
newcommand{bra}[1]{leftlangle #1right|}
newcommand{ket}[1]{left|#1rightrangle}
Sure, but your \bra and \ket commands still don’t know whether they should be \big or not. Even with regular brackets, the mere need for explicit \big commands shows that LaTeX doesn’t do what it’s philosphy would require: do the formatting automatically.
Steve, what is your ruling on the \split command as an alternative exit from circle 4? I understand its functionality is a little different but I almost always \nonumber all but one equation in an array anyway. More importantly, do you know if it handles spacing correctly?
Both split and aligned, inside either equation or align environments, handle spacing correctly.
Bah. “Don’t have time for it.”. You’re an academic, what else do you have but time?
One thing I’ve come to appreciate in my classical life is the role that craft can play, in your own work, but also in effective collaboration. I only wish I had realized this as an academic. (for examples of what I mean by craft, read Nielsen or Preskill or Caves’ notes.)
If LaTeX style guides were developed and adhered to, you could open up any LaTeX document and feel at home. And stop expending effort on parsing bad LaTeX (like the kind you’ve most certainly found in my papers.)
A foolish consistency is the hobogoblin of small minds, but a non-foolish one?
Oh, I’m well aware of what you’re talking about. The thing is, I only have to parse the LaTeX of my coauthors… I’m rarely reading the source of someone else’s document. It’s more useful to have style guides for the scientific content of papers. We basically already have that: standardized notation for important concepts is one example. (Nobody calls a wavefunction “n” and a positive integer “\psi”.)
You sound like a libertarian choosing only to optimize locally 🙂
Our planetary civilization may be tottering, but golly! our species’ typography is excellent. Here is a file that generates scientific LaTeX in precisely the typographic style of JK Rowling’s Harry Potter books:
documentclass[12pt]{article}
RequirePackage[T1]{fontenc}
usepackage[ascii]{inputenc} % for strictly ASCII input files
% usepackage[utf8]{inputenc} % for non-ASCII input files
RequirePackage{fixltx2e} % fixes broken stuff in LaTeX
RequirePackage{amsmath}
RequirePackage{amsthm}
RequirePackage{mathtools} % fixes broken stuff in amsmath
% *******************************
% *** switch to Garamond ********
% *******************************
RequirePackage[garamond]{mathdesign}
RequirePackage[small,euler-digits]{eulervm}
renewcommand{mathbold}[1]{boldsymbol{#1}}
renewcommand{mathbf}[1]{boldsymbol{#1}}
RequirePackage{eucal}
linespread{1.025}
% *************************************
% *** tune kerning (can be slow and buggy)
% *************************************
RequirePackage[%
tracking=basictext,%
kerning=basictext,%
spacing=basictext%
]{microtype}
% make the tracking more open
% ... open up the interword spacing by "50*" = 5%
% ... open up the intercharacter spacing by "7" = 0.007 em
SetTracking[spacing = {50*,0*,0*}]{encoding = *}{7}
% adjust the kerning of "(" and ")"
SetExtraKerning{encoding=*}{) = {25,},( = {,75}}
begin{document}
The scientific LaTeX of Hogwarts:
[partial_t|psirangle = iH|psirangle ]\
end{document}
Needless to say, your mileage may vary! 🙂
Here is a braket function that I wrote using the xparse package. It let’s you write a braket with 1, 2, or 3 arguments separated by | and then automagically parses and resizes everything. You may not like the spacing if you don’t like \left and \right, but you could make different versions of this instead like \bigbraket,…,\Biggbraket.
\documentclass{article}
\usepackage{xparse}
% \Braket{ | | }
% this function reads in the arguments and parses the | delimiters, then resizes them.
\NewDocumentCommand \Braket
{ >{ \SplitArgument{2}{|} } m }
{ \InternalFunctionBraket #1 }
\NewDocumentCommand \InternalFunctionBraket
{ m m m }
{\IfValueTF {#3}
{ \left\langle #1 \middle\vert #2 \middle\vert #3 \right\rangle }
{\IfValueTF{#2}
{ \left\langle #1 \middle\vert #2 \right\rangle}
{ \left\langle #1 \right\rangle }
}
}
\begin{document}
Behold! This function parses each vert and resizes it correctly!
\[
\Braket{\int_{0}^t x^k \mathrm{d}x}
\Braket{A | \frac{1}{2} }
\Braket{ X | \bigotimes_{j=1}^{n} A_j | Y }
\]
\end{document}
Using bibtex is no guarantee that you will have a decent bibliography. Often, there will be many inconsistencies in cut&pasted BIB files that bibtex will dutifully copy out. Have you ever seen: Inconsistent capitalization in paper titles? Inconsistent abbreviations for conference names? Entries where some authors have first names, others just have initials? Mixing and matching of date styles? Errors in conference dates/locations? Errors in editor names? etc. etc.
I got sick and tired of these ad developed CrossTeX. It enforces stringent consistency rules. It enables you to pick short or long citation formats at the drop of an option. It has the DBLP built in. It lets you cite by specifying constraints on bibliography entries (e.g. “author was sirer, and it appeared at sosp in 1999”) instead of arcane keys. Discerning LaTeX users should check it out.
For text in math mode, \mathrm is fine as long as it’s just one character. But for an abbreviation like “eff”, \mathrm doesn’t space the characters like normal text — it just bunches them together. Using \textnormal is the right thing to do.
For a glimpse into $latex text{LaTeX}$ Heaven (as contrasted with $latex text{LaTeX}$ Hell), consider this TUG interview with physicist-and-craftsman Peter Wilson, author of the memoir class.
It would be good to update your post by adding punishments for each offense that last for eternity and have to do with the crime committed. For example, those who used greater than signs in place of kets should never again be able to make comparisons with certainty. Also, where is the offense of using Scientific Workplace and asking your coauthors to work with the source generated by this program? Surely this fits in there among the most heinous, perhaps as part of the 9th circle…Unfortunately I have committed this one a number of times… 🙂
I thought about adding punishments, but I decided against it… I think feeling the shame of the greater sins (#5-#9) should be enough to get people back on the virtuous track.
Some $latex text{LaTeX}$ packages that (in my experience) usually “just work” to make documents better are:
RequirePackage[l2tabu,orthodox]{nag} % nag about obsolete LaTeX
documentclass{article}
RequirePackage[T1]{fontenc} % --*better*-- typography
RequirePackage{lmodern} % -**better**- typography
RequirePackage{microtype} % ***better*** typography
RequirePackage{fixltx2e} % silently fix various LaTeX bugs and infelicities
RequirePackage{amsmath} %
RequirePackage{amsthm} %
RequirePackage{mathtools} % silently fix amsmath bugs and infelicities
RequirePackage{colonequals} % better :=
Hey, your website’s latex interpreter isn’t working!
It does not work for me either.
I tried Firefox and Chrome but it seems to be an website issue. Looks like wordpress removed all your backslashes.
Greetings,
Klaus La Tex
Any idea how to fix this? I didn’t find a solution on google.
I am not 100% sure what might be the problem, since I am lacking a lot of information about you blogs setup and configuration, but I think it is one of the following two:
You are using the wrong plugin or a plugin wrong. Check your latex plugings documentation or chose a diffrent one, e.g. here: http://wordpress.org/plugins/tags/tex (John Sidles on the other hand is able to use your plugin just fine, see a few comments above.)
Secondly, and more likely, you are having some issues with escaping backslashes in your blog entry html or text properly. There can be quite a few reasons for that on various levels. Using two slashes instead of one should often do the trick, e.g. like this \\Latex . These issues are discussed often and throughout the internet, e.g. here: http://en.forums.wordpress.com/topic/wordpress-eating-my-backslash-on-ltpregt-tag
Good luck,
Klaus La Tex