The Nine Circles of LaTeX Hell

This guy had an overfull hbox

This guy had an overfull hbox

Poorly written LaTeX is like a rash. No, you won’t die from it, but it needlessly complicates your life and makes it difficult to focus on pertinent matters. The victims of this unfortunate blight can be both the readers, as in the case of bad typography, or yourself and your coauthors, as in the case of bad coding practice.

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 text{{it test}text} to 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 mathbb{E}, while your coauthor uses it to mean 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 $$…$$

This one is another plain TeX command. It messes up vertical spacing within formulas, making them inconsistent, and it causes 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: (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 H_{effective} is horrendous, but even 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 H_{text{eff}}. Don’t use mbox, though, because it doesn’t get the font size right: 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 |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.

This entry was posted in Off The Deep End, Scientific Publishing. Bookmark the permalink.

46 Responses to The Nine Circles of LaTeX Hell

  1. Dave Bacon says:

    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.

    Like or Dislike: Thumb up 0 Thumb down 0

    • Steve says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

    • John Sidles says:

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

      Like or Dislike: Thumb up 0 Thumb down 0

  2. prasad says:

    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?

    Like or Dislike: Thumb up 0 Thumb down 0

    • Varun says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

  3. sflammia says:

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

    Like or Dislike: Thumb up 0 Thumb down 0

    • prasad says:

      I mean how to get the sizes of the equal for

      Like or Dislike: Thumb up 0 Thumb down 0

      • prasad says:

        gah, it ate all the useful text. I mean, when you have
        , how do you get the less-than, vertical and greater than lines to all be of the same height.

        Like or Dislike: Thumb up 0 Thumb down 0

        • John says:

          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.

          Like or Dislike: Thumb up 0 Thumb down 0

        • Aaron says:

          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.

          Like or Dislike: Thumb up 0 Thumb down 0

          • sflammia says:

            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

            Like or Dislike: Thumb up 1 Thumb down 0

          • Aaron says:

            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.

            Like or Dislike: Thumb up 0 Thumb down 0

  4. Dan Browne says:

    On the related Path to ArXiv-purgatory:

    1. Raw latex commands left in the \textit{plain text} abstract.
    2. Double

    spacing

    Like or Dislike: Thumb up 0 Thumb down 0

  5. Suresh Venkat says:

    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

    Like or Dislike: Thumb up 0 Thumb down 0

    • John Sidles says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

      • John Sidles says:

        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.

        Like or Dislike: Thumb up 0 Thumb down 0

    • John Sidles says:

      In addition to seconding Suresh’ recommendation of the \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 \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!” :)

      Like or Dislike: Thumb up 0 Thumb down 0

    • John Sidles says:

      Oh yeah … a final invaluable document is A Few Notes on Book Design, by Peter Wilson (author of the magisterial \text{\LaTeX} memoir class). This document is included in standard \text{\LaTeX} distributions as the file “memdesign.pdf”.

      Remember, when Donald Knuth designed \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.

      Like or Dislike: Thumb up 0 Thumb down 0

  6. Steve says:

    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.

    Like or Dislike: Thumb up 0 Thumb down 0

    • Toby Cubitt says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

  7. Dan Browne says:

    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.

    Like or Dislike: Thumb up 0 Thumb down 0

    • Steve says:

      Wow. I like that two of the “deadly sins” will also land you in LaTeX hell. How appropriate! :)

      Like or Dislike: Thumb up 0 Thumb down 0

  8. John says:

    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.

    Like or Dislike: Thumb up 0 Thumb down 0

    • Steve says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

    • blk says:

      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?

      Like or Dislike: Thumb up 0 Thumb down 0

      • aram says:

        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}

        Like or Dislike: Thumb up 0 Thumb down 0

        • blk says:

          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.

          Like or Dislike: Thumb up 0 Thumb down 0

  9. seth says:

    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?

    Like or Dislike: Thumb up 0 Thumb down 0

    • John says:

      Both split and aligned, inside either equation or align environments, handle spacing correctly.

      Like or Dislike: Thumb up 0 Thumb down 0

  10. Dave Bacon says:

    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?

    Like or Dislike: Thumb up 0 Thumb down 0

    • sflammia says:

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

      Like or Dislike: Thumb up 0 Thumb down 0

  11. John Sidles says:

    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|\psi\rangle = iH|\psi\rangle \]\\
    \end{document}

    Needless to say, your mileage may vary! :)

    Like or Dislike: Thumb up 1 Thumb down 0

  12. sflammia says:

    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}

    Like or Dislike: Thumb up 0 Thumb down 0

  13. Emin Gün Sirer says:

    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.

    Like or Dislike: Thumb up 3 Thumb down 0

  14. Varun says:

    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.

    Like or Dislike: Thumb up 0 Thumb down 0

  15. John Sidles says:

    For a glimpse into \text{\LaTeX} Heaven (as contrasted with \text{\LaTeX} Hell), consider this TUG interview with physicist-and-craftsman Peter Wilson, author of the memoir class.

    In the ancient days of art
    Builders wrought with greatest care
    Each unseen and hidden part
    For the gods see everywhere

       – Unknown (possibly Masonic?)

    Like or Dislike: Thumb up 1 Thumb down 0

  16. Pingback: No LaTeX at all | Between the Candle and the Star

  17. 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… :)

    Like or Dislike: Thumb up 0 Thumb down 0

    • sflammia says:

      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.

      Like or Dislike: Thumb up 0 Thumb down 0

  18. John Sidles says:

    Some \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 :=

    Like or Dislike: Thumb up 1 Thumb down 0

  19. Pepe Mandioca says:

    Hey, your website’s latex interpreter isn’t working!

    Like or Dislike: Thumb up 1 Thumb down 0

    • Klaus La Tex says:

      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

      Like or Dislike: Thumb up 0 Thumb down 0

      • aram says:

        Any idea how to fix this? I didn’t find a solution on google.

        Like or Dislike: Thumb up 0 Thumb down 0

        • Klaus La Tex says:

          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

          Like or Dislike: Thumb up 0 Thumb down 0

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>