Skip to content

Latest commit

 

History

History
239 lines (161 loc) · 14.6 KB

writing-with-latex.md

File metadata and controls

239 lines (161 loc) · 14.6 KB

writing with latex

introduction

Any text document you encounter (including the one you are reading now) is a combination of plain text and formatting.

Plain text is what we write – the content of the document. Formatted text on the other hand is what we read – the content plus the form, where the latter is chosen in a way as to allow the former to best serve its purpose. It is only rarely – e.g. as computer code or a manuscript fresh off of a typewriter – that the two are the same.

Separating content and form has many benefits (think of several yourself) and is possible thanks to typesetting systems such as LaTeX. LaTeX workflow requires you to write plain text interspersed with formatting commands (which are but plain text themselves) using your favorite text editor, then merge the text and formatting by compiling the document with a TeX engine.

Note that this workflow is different from using a word processor such as MS Word or LibreOffice Writer which make you apply the formatting on the fly. Although this might seem as a more convenient route, separating content from form is the serious-level standard and does result in better publications.

terminology

For someone to be 'using LaTeX for the thesis' means to be using a special system of commands called LaTeX to set the formatting of the thesis's text. These commands placed here and there in the .tex file will be interpreted by a TeX compiler (aka engine) to apply the formatting and produce a readable document. LaTeX is not the only such system, but the most popular one. Similarly, there are several TeX engines to interpret the commands.

LaTeX is what is called a format: a convenient collection of macros (programming instructions) written in the programming language called TeX. TeX has been around for years, but is a little too flexible and complex for everyday tasks, which is why people have collected many frequently used TeX macros, e.g. those that change fonts and insert hyperlinks, and bundled them together to produce LaTeX and other formats. Without the latter you would have to write TeX code for every piece of formatting.

A format alone is not enough: as mentioned previously an engine is also required. To name a popular one, pdfLaTeX would compile a document typeset in LaTeX to produce a pdf.

For better typesetting experience, other software might come in handy, e.g. a bibliography formatter or graphics manipulation program. When all things necessary to transform an idea into a readable document are bundled together, a TeX distribution appears. Two distributions are currently maintained as open source: MiKTeX and TeX Live, but there may be others circulating in the private sector. Of the two mentioned, MiKTeX is claimed to be better optimized for Windows but to suffer from security problems; when on Linux or when security is key, TeX Live might be a better option.

Separate collections of macros designed to perform specific tasks (e.g. to insert a figure) within a specific format are called packages. These can be thought of as add-ons filling a gap here and there.

See resources for more info.

setup

To get latexing up and running we would need a format, an engine, a bibliography processor (to be discussed later) and a text editor. You can either install these locally as a distribution (see above), or use docker (pull texlive/texlive), or use the app called Overleaf to work on your documents online. Note that a local installation gives you the most control, but can be frustrating when things don't work; Overleaf is neat, but doesn't allow for an easy integration with your favorite text editor; docker is the preferred solution despite suffering from the usual docker problems, so let's take a minute to see how it could work for you.

First, select an texlive image from the dockerhub; for most purposes, just use the most extensive (and hence, the heaviest) tag latest, which is the default:

docker pull texlive/texlive:latest

From this image you can run a container with all the TeX formats and compilers; to get access to them, while working on your files, you could mount the working directory onto a directory inside the container (check a possible destination first!), and execute appropriate commands on demand:

docker run -v $(pwd):/workdir texlive/texlive

packages

If you would like to install a missing package, e.g. threeparttable, google it first. Almost all packages you will ever need are registered on CTAN; in this case, check if the package is contained in your distribution:

With some luck, you would be able to install it the easy way through the package manager.

Packages that are not available through the package manager – e.g. those written by you and/or distributed as files with extension .sty – can still be installed manually, although the process is a bit trickier. Please see the documentation and threads on MiKTeX or Tex Live for instructions.

useful packages

  • package threeparttable and environment tablenotes;
  • package dcolumn allowing to align columns on a separator, such as the decimal dot;
  • package endfloat to push all figures and table to the end (please avoid it).

workflow

  1. Know your macros. You are aware which macros produce the formats you need and in which packages those macros are to be found. For instance, multi-line equations require package amsmath and are inserted as follows:
\begin{gather}
...
\end{gather}

  1. Follow the layout. LaTeX documents are expected to be rigidly structured: please take a look at the latex wiki.

  2. Write text. Write plain text inserting macros to set formatting. A document might look as simple as:

\documentclass{article}
\usepackage{amsmath}
\begin{document}
\begin{gather}
  x = 1 \\
  y = -1
\end{gather}
\end{document}
  1. Compile. To turn your collection of text and macros into a readable document, the file must be compiled using an engine such as latex (will produce a .dvi file) or pdflatex (will produce a pdf). From whenever your .tex file is located, execute the following in the command line:
pdflatex <filename>.tex

to produce a readable pdf. In a text editor such as Sublime Text with LaTeX integration enabled, you can compile a .tex file from the editor directly. Do read more about compilers here.

generating .tex exogenously

Often, you can use the same software that generates your research findings such as tables and figures to latexify them, or transcribe to LaTeX-interpretable code. It might be a function such as xtable in R, a method of a class, such as pandas.DataFrame.to_latex() in python or a button in the navigation bar as in gretl. In any case, before starting to manually input numbers into a .tex file, do search for a solution first, for instance:

julia write table to latex

jupyter notebook export to latex

or ask ChatGPT!

bibliography

Bibliography is a collection of all references you cite in your work. As it is in general a bad idea to type citations by hand (at the bare minimum to avoid awkward spelling errors), a better idea is to organize them in a well structured database and point to its entries whenever needed. In a LaTeX document, this is achieved using two things, which you will always encounter in discussions of bibliography: a backend processor such as biber or bibtex and a package providing bibliography formats such as biblatex or natbib. The backend takes a bibliography database (usually a .bib file) and processes it to produce a TeX-conforming file (usually with extension .bbl), while the format uses a collection ogf macros to place, point to and and keep track of citations.

Many possible bibliography variants such as bwl-FU are contained in biblatex, differing in the way names are abbreviated and ordered, mnemonics defined etc.

structure

A bibliography database is biblatexsaved as a .bib file and has entries of the form:

@<TYPE>{<KEY>,
  <FIELD> = {<FIELD_VALUE>},
}

where

  • <TYPE> is the type of the source, most commonly article, techreport or book,
  • <KEY> is the unique identifier of this entry to be used in text, most commonly a short memorizable string such as cieslak2019stock which refers to the paper by Cieslak, Morse and Vissing-Jorgensen called 'Stock returns over the FOMC cycle' published in 2019;
  • <FIELD> is the name of one of many fields containing information about the source, e.g. title and journal;
  • <FIELD_VALUE> is the field value.

Look up the bib guide in resources for a broad overview of the structure of .bib files.

maintenance

Surely, it is too time-consuming to manually type in every one of hundreds of bibliography entries you want to cite. More often than not however, you would be able to find citation info in the same place as the cited piece. Look for 'Export to BibTeX' or 'Cite this item' or similar. For instance:

https://www.nber.org/papers/w27638

or

https://www.jstor.org/stable/10.1086/605130

JabRef is a nice little reference manager that helps the user collect and organize references. Among other things, it can boast an auto-collect feature based on document identifiers such as ISBN or DOI. Take a look at the user's guide for more information.

implementation

Place biblatex package import statement in the preamble of the document, not forgetting to specify the parameters:

% bibliography
\usepackage[
    backend=bibtex,
    style=bwl-FU,
    url=false,
    doi=false,
    eprint=false
]{biblatex}
\addbibresource{<bibliography_name>.bib}

And to print the bibliography, put

\printbibliography

where it is supposed to appear.

beamer

Package beamer provides functionality to create presentations with LaTeX. You should now be able to guess what it does: through a plethora of macros, it redefines the geometry of the canvas to have the usual 'presentation' aspect ratio (4:3) and size of print-outs (128x96mm), allocates one page per frame, creates titles and subtitles, meaningful footers etc. A simplest layout of a beamer-style presentation is as follows:

\documentclass[10pt]{beamer}

\begin{document}

\author{your name goes shere}

% ---------------------------------------------------------------------------
\begin{frame}
\titlepage
\end{frame}
% ---------------------------------------------------------------------------

\end{document}

More elaborate examples are in the package documentation.

custom classes and packages

If you are not happy with off-the-shelf solutions LaTeX has to offer or have a strong preference for individuality in design, you can write your own packages and classes and \usepackage{} or \documentclass{} them in the preamble of the document. Here is a short explanation when to use which. A frequent reason to write a .cls is indeed:

[...] if a company needs branded reports that use a special font and have the logo of the company in the footer; you need a new class.

resources

exercises

  1. Install a TeX distribution or familiarize yourself with docker image texlive/texlive or learn how Overleaf works;
  2. Setup your favorite text editor for LaTeXing;
  3. Make sure that packages threeparttable and blindtext are installed;
  4. In your repo create folder text/ with subfloders paper/ and presentation/;
  5. In folder paper/ create the .tex file that will become your report and lay out the basic structure;
  6. Compile it with pdflatex to produce a .pdf;
  7. Install JabRef;
  8. Locate the DOI a paper that you will cite and use it to auto-parse the info to JabRef;
  9. Create a .bib file with the entry for it;
  10. Sketch a draft of your final report consisting of:
    • a title page with title, author(s), affiliation(s), date, abstract and thanks;
    • the usual sections: introduction, data, methodology, results etc. filled with actual or dummy text (use blindtext for that);
    • bibliography on a separate page.
  11. Sketch a draft of a simple beamer presentation.

Do use this template for your actual text and presentation later.