5 circles of LaTeX hell

Here I gather some advices I would give a younger version of myself (if I could). Seriously, following some of the rules from the very beginning would save me a lot of time over the course of my PhD.

I hope this reference will be useful for students who have just started to discover a beautiful world of LaTeX, or for those who want to do a collaboration with the other guys more efficient.

1. Thou shall give good names to ya labels!

  • Use a convention section:introduction, subsection:model_assumption, eq:drift_approximation, table:comparison_schemes, not a mess of intro, assum1, DrAppr, CompScheme.
  • Be sure to write informative labels: \label{eq:solution_of_sde} is better than \label{eq:s_o_s}. Violation of the rule: 5 years of article writing with no right for spellchecker.
  • Don't overlabel your equations, if you are not sure to use them later in text. Of course, you may always leave in text the numbers only for the labeled equations by using a package showonlyref (and, by the way, show all your labels in a draft text using showkeys), but why loading a hell of packages, if you can just avoid creating a mess?
  • For Odin's sake, do not use the abbreviations unless they are absolutely obvious! SDE for "Stochastic differential equation" is OK, NESU for "Numerical evidence of snowflakes uniqueness" is NO (you will surely forget it in one week!)

Why to use the conventions:

  • It makes so much easier to use autocompletion without scrolling through all those names...
  • Which you will forget sooner than you believe! Keep in mind that you will probably reuse your reports, abstract, papers etc. dozens of time!
  • ... And think about your poor comrades collaborators!

ProTip: If your tex editor has no autocompletion, think about changing the editor (or adding a proper plugin, if you are using vim, emacs or something similar).

2. Don't mess with your references!

When adding a new bibliography entry to the .bib-file, please use the following convention:

  • Start the key with NameYear[Completing], where Name is the name of the FIRST author, Year - the date of publication, [Completing] (without brackets) is the supplementary info about the article which should be used - for example, second author or a topic, preferably, only if the author Name had several articles on Year.
  • Be sure your bib entries are properly formatted - in particular, multiple authors are correctly written ("Name1, Surname1 and Name2, Surname2" - and not "Surname1 Name1, Surname2 Name2")
  • Don't use umlauts, accents or cyrillic letters. Think of your international comrades who may using different encoding!
  • No abbreviations in keys!

Why to use the conventions:

  • To simplify your autocompletion life! AuthorYear is just much simpler to remember than trying to write the name of the paper, all authors in line, or, what is even more horrible, the abbreviations like DS_uni_book for the book about unicorns written by J. Doe and A. Smith - either you will forget it and die from despair, or your collaborators will kill you some day.

ProTip: For your information, the umlauts can be replaced by using \"o instead of ö, \'e instead of é and so on. For cyrillic letters - just don't use them! Better translate the entry in English (stating that it is written in another language), or keep a separate .bib file for your Russian\Ukrainian\Belorussian language articles. Also, consider using JabRef (see further).

3. Don't mess with the long formulas!

The beautiful world of equation-like environments in LaTeX remains mostly unexplored. Negligence leads to undesirable - and unreadable! - consequences, especially if you are dealing with half-page long formulas. Here is a short guide:

  • {equation} is used for one-line equations only AND group of equations, referenced like one (with the environment {gathered} or "{aligned}* put inside)
  • {multline} is used for ONE equation, splitted on several lines, with cascade-style alignment
  • {gather} is used for centering a GROUP of equations (with separate label for EACH equation). Environment {gathered} is used inside an environment {equation} and does exactly the same job as {gather}, but using it you will allocate ONE label to the group.
  • {align} (and, respectively, {aligned}) allows a custom alignment for multiline equations (or group of equations).
  • If you want to write a system of equations\ineqalities etc. - consider using {array}.

4. Play well with the others!

  • When collaborating, don't delete anything you have not written yourself. If you feel it is absolutely necessary to delete --- put the passage in comment (either environment "comment" or \iffalse passage to delete \fi) with, if possible, a remark, why do you think it is necessary to get rid of your comrades work.
  • You may also consider using different colors for redacting the text to make it obvious who has changed what.

ProTip You may also have a look on a brilliant package changes. First, it gives you a possibility to track your own changes in the document (without endlessly multiplying the copies of the document). But what is more important, it gives you quite a powerful tool to make a collaboration effective - be sure to check this manual.

5. Life-changing magic of using JabRef.

  • It gives you several powerful search-engines (Springer, GoogleScholar etc.) which allow you to add a BibTex reference to your bibliography without lurking through the websites in vain to find the copy-pasteable text.
  • It keeps your bibliography organized. If you need to find a specific paper and change, for example, its status from a preprint to a journal publication - you do it simply by sorting your entries by, for example, a year, and save yourself time which you would otherwise spent on scrolling through txt file which contains few hundreds entries.
  • Since it treats your library as a true database, you have an access to all the good database features as export\import to another format, removing dublicates, autogenerate keys in a proper format.
  • JabRef is free, cross-platform and open source (consider a donation!)