$\LaTeX$ is just amazing for every minimally complex document you need to do. The beauty of it is that you can focus on writing, while it makes all the magic of formatting for you in the background. It is true that LaTeX has a steeper learning curve than other What You See Is What You Get (WYSIWYG) alternatives, but I think, in a perfect world, it would make an enormous difference in productivity and easy of use for researchers, at the cost of five days to familiarize with it.

With just a few packages I will show you, dear researcher, what you could achieve with $\LaTeX$. Just keep reading and you shall see a new world where with just a few lines of specifications people are empowered with the capacity to change the whole document at their will, libremente.

Installation and resources

I will not get in details of the installation and how to learn LaTeX, only the basics. Nevertheless, if you need more information or guidance to start, please feel free (libre 😉) to contact me. I’ll be happy to share the little I know. Let’s get to it!

To work with LaTeX we need an interpreter (compiler), and a text editor. In the text editor we write all the stuff we want to pass to the interpreter to build our document, meaning a mixture of configuration directives and the real text we want in the output. Then, once passed to it, the interpreter processes all the information and return a formatted PDF document.

Getting the compiler

The way I have always installed LaTeX in my computers is by using TeX Live. This will install a comprehensive TeX system ready to work with. The installation in Windows is straightforward, in Mac I don’t know, and in Linux it can even be accessed by sudo apt-get install texlive (or whatever package manager your specific system use). Take into account three things:

  1. The TeX Live package in the systems repositories tend to be outdated, although I have never found the need for it to be up-to-date in practice.
  2. There is the alternative texlive-full package. This will install a LOT of Language Packs that you will never need. For this reason I suggest that you should install the version without full, and afterwards install the languages you rally use. But if you are just starting and have some extra disk space maybe going with the full will save you some time.
  3. There is this Comprehensive TeX Archive Network (CTAN) which contains most of packages you will use. There it is the source code, installation instructions, and documentation.

An exception here is, and as far as I know unique, in Fedora, which is my case. In Fedora you can install three different schemes of texlive: basic, medium, and full. Afterwards you can install the missing packages you need with

1
2
sudo dnf install 'tex(beamer.cls)' 
sudo dnf install 'tex(hyperref.sty)'

Getting the text editor

After you have the installation of TeX Live, you will need a text editor to edit the code of your LaTeX documents. Remember that LaTeX has a What You See Is What You Mean (WYSIWYM) paradigm, so we are telling the interpreter what we want to get. If you are not an Emacs or Vim user already, and just what to make your documents in LaTeX, I recommend you to get TeXStudio, it’s really nice and easy. Nevertheless, if for some circumstance you do not like TeXStudio, there is a list of other availables editors at this StackExchange post.

There is also this other service called Overleaf which some of you may find easy to use. Just create an account and you are all set, without installing anything. Of course it is cloud based etc. but to start it is quite nice, you can try latex without installing anything! I would prefer, however, to have stuffs in my computer and access them any time I want with or without internet access.

At this point you are ready to go.

How do I know the packages I need to install?

Easy, after you have installed any version of TeX Live, if you include a package in you source code which is not installed, when you compile you will get an error. It will say that package[.cls|.sty] is not found. There you know that you need to install it 😎.

What does it looks like

The following code results in this document. If you want to replicate it, you will need the sin.pdf file figure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
\documentclass[a4paper, 12pt]{article}
\usepackage{lipsum}
\usepackage[citecolor=blue, urlcolor=blue, colorlinks, linkcolor=black]{hyperref}
\usepackage{graphicx}

\title{My first article in \LaTeX}
\author{Yaidel}
\date{\today}

\begin{document}

\maketitle

\section{Introduction}

This is an introduction to my first \LaTeX article ever. It is followed by 5 
paragraphs of \href{https://en.wikipedia.org/wiki/Lorem_ipsum}{Lorem Ipsum}
placeholder text to demonstrate the format of the document. But you can get
creative here, and write some equations, for example
\begin{equation}
  \label{eq:newton-law}
  \vec{F} = m \cdot \vec{a}
\end{equation}
or even plot a $\sin(x)$ function, as represented in Figure

\begin{figure}[h!]
  \centering
  \includegraphics[scale=0.4]{sin.pdf}
  \caption{$\sin(x)$ function plot generated with GNUPlot.}
  \label{fig:sin-x}
\end{figure}


\lipsum[1-5]

\end{document}

The first line declares that this documents will be based in the article class, with 12pt font size and in a4paper format. The following three lines load three packages which are needed for the generation of the document.

Lines 6-8 define the title, which is then inserted into the needed position in the document, normally at the beginning, by the \maketitle directive (in this case in line 12).

Lines 10 and 36 open and close, respectively, the content of the document. Anything before them is called the preamble of the document (from line 1 to 9 in this case), and it is there where we specify all the formatting directives and load the necessary packages.

The rest of the document can be understood by comparing the resulting PDF file provided above with the source code showed.

Suggested books to start with

  • Spanish: Edición de Textos Científicos LaTEX por Alexánder Borbón y Walter Mora, que debería estar en esta página web, pero por algún motivo no puedo acceder a ella.
  • English: Guide to LaTeX. Tools and Techniques for Computer Typesetting. By Helmut Kopka and Patrick D. Daly (Addison-Wesley).

The dark side of LaTeX

In the beginning you will, maybe, mistype a directive or a symbol, and LaTeX will throw at you 50 error messages and not compile your document. This is can be very hard and disappointing to deal with at the beginning, but it is something you will improve down the way. My advice here is that you should, as I do, start with the basic document structure and compile. If you got some error fix them till it is correctly compiled

Long documents

Lucky people can be defined as follows: Those who have not had the necessity to write a Thesis (or any long form text) in a MS Word document. At this very moments I am siting next to C-, who is writing her PhD. Thesis and Word is just driving her crazy. It gets slow, so you have to write in separate documents each Chapter, to finally put them back together. You could skip the part of putting them together and just printing separately, but then the references would have had to be entered by hand, and not cross reference would work. When gluing the documents together the format of the figures and tables changes, and some even mysteriously disappears. The list of figure is a problem, as well a the list of tables, and the list goes on and on.

I spent like 2 hours setting up the format I wanted for my PhD. Thesis, and that’s it, $\LaTeX$ manage the rest for me. I just had to write. How? Easy peasy lemon squeezy!

There is this functionality in LaTeX called include, and it is beautiful. So, in the body of the document, you do not write your text, but include other files which contain it. The following is almost a replica of my thesis structure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
\begin{document}

\include{frontpages/titlepage}
\include{frontpages/aknowledgements}

\frontmatter
\include{frontpages/abstract}	
\include{frontpages/toc}
\include{frontpages/tof}
\include{frontpages/tot}

\mainmatter
\include{chapters/introduction}
\include{chapters/chap1}
\include{chapters/chap2}
\include{chapters/chap3}
\include{backpages/conclusions}

\appendix
\include{appendix/mr_supporting_data}
\include{appendix/rotameric_analysis}
\include{appendix/methods_comparison}
\include{appendix/pka}

\backmatter
\printbibliography[heading=bibintoc]

\end{document}

With the \frontmatter, \mainmatter, \appendix, and \backmatter directives, LaTeX automatically format for you the page numbers, the label of figures, tables, chapter numbers, etc. If the issue is to generate the Table Of Contents (TOC), or a List Of Figures (TOF), or a List Of Tables (TOT), easy peasy one more time: they are requested in the files toc, tof, and tot with the commands \tableofcontents, \listoffigures, and \listoftables, respectively. Just like that… it’s magic.

But wait, there is more, because LaTeX also lets you specify in the preamble which of those files you want to compile, so you do not waste you time compiling and searching the whole document when editing a chapter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
\includeonly{
  frontpages/titlepage,
  frontpages/aknowledgements,
  frontpages/abstract,
  frontpages/toc,
  frontpages/tof,
  frontpages/tot,
  chapters/introduction,
  chapters/chap1,
  chapters/chap2,
  chapters/chap3,
  backpages/conclusions,
  appendix/mr_supporting_data,
  appendix/rotameric_analysis,
  appendix/methods_comparison,
  appendix/pka
}

That’s it, you just comment (with %) one of those includeonly lines and it disappears from the resulting PDF. So normally, you will have them all commented, except for that one you are working on, and if you want so see how does the complete document looks like, you just uncomment them all. Of course, it’s silly to ask, that all figures, tables, bibliographic references, cross references, page numbers, etc., are correctly and automatically managed by LaTeX.

Did that seem hard to you? Why is people telling LaTeX is hard or complicated? Mmmmmmm….🤔 Anyway, now you are free, and you can ditch you WYSIWYG software, entering once and for all in the realm of $\LaTeX$ and the easy life.

Automatic management of tables and figures

Remember we said that LaTeX will manage the format for you, this includes, of course, the position of the pictures and tables. For example, take the source code above (do not forget to download the sin.pdf file and place it in the same folder than the source code), if you increase the scale=0.4 option to 0.5, the image will be too large to fit in the first page, and although we specifically told LaTeX that it should be included in the exact position it is (with the h! option), it will skip it to the next page, where there is enough room.

You shall no more fight with the position of a figure, nor with its disappearance, nor with its complicated relationship with captions, nor with cross referencing. They will be placed where they look better in your document.

—But man, tables in LaTeX are a pain in the ass.— Got you covered, check out TableConvert or TablesGenerator.

Of course, there are some problems with this, nothing is perfect. Sometimes you will have white spaces in some pages, or even pages with just an image, because it is the only way LaTeX found to correctly place all the elements in your document. Other issues, which may be more frequent, is that your supervisors want the figure in a specific place, where it makes no sense, but they want it there because they know better than those who have developed this software for decades. In this case moving the picture by hand is not possible, and you will probably fight a little changing sizes and arranging text to trick LaTeX, and get it finally positioned where it shouldn’t be.

References outside a document

Have you ever had to write a paper with its supporting information, and manually make references from one tables and figures to the other. That end here!

xr is a package which lets you make external references to other LaTeX document, as long as it has the auxiliary files with it, i.e., it has been previously compiled.

For example, I have my paper.tex and si.tex files, by including the following declarations in the paper.tex I can reference everything in si.tex.

1
2
\usepackage{xr}
\externaldocument{si}

Track changes

—But it is required for the Journal that we provide a track of all the changes we made to our previous version.

The Perls script LaTeXdiff, officially maintained, is capable to take two LaTeX source files as input and then generate another which contains the differences marked up.

Once it has been installed (see the manual), it can be run with

1
latexdiff [option] old.tex new.tex > diff.tex

The available options can be found on the documentation, but the default values (meaning without specifying any option) are normally correct. Now compile diff.tex and you shall see, once more, how the magic happens in front of your eyes.

See this article for more information.

Version control and collaboration

Because it is all text based, maintaining the documents under a Version Control System like Git make stuffs pretty damn perfect. Forget about all those version2.doc, version_revised.doc, last_version.doc, last_last_last_revised_corrected.doc versions of the same document. With Git you can have the cutting edge version always, and return to the previous ones in one key stroke. But things get more interesting when the people that work with you are also aware of all these advantages and set up a Git server for the team. Everyone can contribute to the paper, see what other have done, integrate their opinions, all that without meetings, and guess what? Yeah! You got it right: With only one version!

You will to learn Git, but it is not hard to do. The basics can be learned in one day with the Pro Git book given free in the Git page. No excuses.

Emacs

Most of the time I have used LaTeX with Emacs. It’s really convenient. You can check out my configuration if you are interested in the specific details (search for the * Latex section of the org document), but it is basically the use of AucTeX, RefTeX and not much more. It makes things simpler, for example, while writing, to compile the document I just have to type C-c C-a and it get compiled and the PDF opened. Or to make a citation I just hit C-c [ and it open the menu to make the citation based in the databases I have configured, and many other cool stuffs.

Also, the use of Magit to access the Git functionalities within Emacs is, how to put it?… A Git Porcelain inside Emacs! 😄

It’s not all a bed of roses

Recently I had this experience that I wrote my paper in LaTeX, but when the time came to upload it to the Journal, they had their own template, which by the way used fonts I was not able to install in my computer, and had to go to Overleaf. I spent almost a day getting things to work with their template, and lost functionalities like the use of xr for external references, because as far as I know Overleaf do not lets auxiliary files (needed by xr) in the directory, it should compile the document somewhere else and only keep the files it thinks you will need.

Finally I did it, but lost many of the functionalities because Journals do not take authors seriously.

Also, another experience I have had is that of supervisors and collaborators who does not know that you can comment and review a PDF file. For them all that there is this MS Word program, you know, those who enter the bibliography and figure numbers by hand, and then change them every time they modify the document by hand. Well, this is something quite common in science, and that’s why I am writing this article, to let people know that there is another way, much more efficient and convenient, where everyone saves time. Of course no elder scientist entering citations by hand will change now, but maybe our generation could avoid being like that in when it is our turn to be in their chairs.

Conclusions

It may be overwhelming if you are just starting, but I think you should start with small steps, and add things with time. To get started it’s really easy, following this section and using TeXStudio is easy peasy.

I do not recommend the use of LaTeX, however, for small documents, as the time spent in the configuration of the document layout etc. is not worth it. Just go with LibreOffice Writer in this case, or whatever software you use.

But above all, keep things simple. LaTeX is designed to help you, but it cannot help you if you do not want to be helped. Trying to get specific things at specific locations, at specific sizes, its all a waist of time, believe me. Let as much as you can in the defaults, and only modify that which is strictly needed, this way you will save time spent in tweaking certain things which add no value to the document, but most of the time subtracts it.

Also know that it is possible to make presentations in LaTeX, they are simple and nice looking. You just have to stick 10 times harder to the principle of no deep tweaking. They are called Beamer. And really a bunch other stuffs like posters, etc.

⋇ ⋇ ⋇ ⋇ ⋇

Thanks for reading the post! Do not hesitate to write me an email, and share your point of view 😉: contact@poview.org