Robin's Blog

How to: add simple new commands to LaTeX to help with writing papers

Like a lot of academics, I write many documents in LaTeX – including almost all of my academic papers, and my PhD thesis! So, anything that can make my life easier is of interest to me. I was recently discussing this with a colleague (a co-author on a paper actually), and realised that lots of people don’t know how easy it is to create new custom commands in LaTeX. It’s actually really simple – and can be really useful – as I hope this post will explain.

So, one simple use for custom commands is to save you typing the same thing over and over again. In my thesis I talked a lot about air quality, and particularly PM_2.5. Now, the correct way to typeset that in LaTeX is as:

$\text{PM}_{\text{2.5}}$

This uses math-mode, but keeps the PM and the 2.5 as ‘normal text’ (otherwise it will look like P multiplied by M rather than PM as an abbreviation for particulate matter). This is a pain to keep typing all of the time – so a lot of people just write

$PM_{2.5}$

which looks far worse (the top is ‘right’, the bottom is ‘wrong’):

Luckily, LaTeX’s ability to create new commands really easily can be used to save us a lot of work. Adding the following to your preamble (the section of your document before the \begin{document} line) will create a new command called \pmtext which will insert the ‘proper’ version of the PM_2.5 code from above:

\newcommand{\pmtext}{$\text{PM}_{\text{2.5}}$}

As you can see, \newcommand is quite simple, you give it two arguments: the name of the new command, and what the new command ‘does’. In this case the second argument is just some LaTeX code that typesets the PM text properly. I created this command fairly early on in the process of writing my PhD, and it made life a lot easier: I had less to type, I didn’t have to remember exactly how to typeset PM_2.5 properly, and if I wanted to change how it was displayed I just had to change it in one place (basically all of the standard benefits of commands or functions in any programming language!).

Talking of programming languages, you can do far fancier things with \newcommand, including passing parameters. A good example here is some code that I add to every LaTeX document I write, which creates a new command called \todo. See if you can work out what it does:

\newcommand{\todo}[1] {\textbf{\textcolor{red}{#1}}}

Yup, that’s right: it displays the given text as bold and red – a perfect way to mark something that still needs doing. For example:

\todo{Somewhere here put in the radiosonde type boxplot}

will produce something that looks like this:

If you look at the \newcommand call, you can see that we give it an extra parameter in square brackets: this is the number of parameters that the command has. We can then reference the value of these parameters as #1 for the first parameter, #2 for the second etc. The rest of the ‘body’ of the command is just normal LaTeX code (if you want to use this code, make sure you add \usepackage{xcolor} too, so that the \textcolor command will work!).

The other command I add to almost every document I use is this:

\newcommand{\rh}{\todo{REF HERE }}

It depends on the \todo command, and allows me to mark the fact that I need to add a reference to a bit of text, without having to stop writing and actually find the reference. I find this has actually helped my writing a lot – as I can quite happily write multiple paragraphs and just scatter \rh around to remind me to come back and put in references later.

The final command I used a lot in my thesis, which shows a slightly more advanced use of \newcommand is

\newcommand\xcaption[2]{\caption[#1]{#1#2}}

You may know that the \caption command can take an optional argument in square brackets for a short caption to be used in the List of Figures. Something like

\caption[Example Landsat image over Southampton]{Example Landsat image over Southampton, shown as a true colour composite, with XYZ procedure applied. Image data from USGS.}

As in that example, I often found myself repeating bits of text: I normally wanted the short caption to be the first part of the long caption, without all of the details given in the long caption. So, the \xcaption command (‘extra caption’) command I’ve created just takes two arguments, the first of which is the short caption, and the second of which is the text to add to the short caption to get the long caption – saving a lot of typing and mistakes!

So, I hope that’s shown how easy it can be to create simple new commands in LaTeX that can save you a lot of time and effort.

If you found this post useful, please consider buying me a coffee.
This post originally appeared on Robin's Blog.

Tagged with:

Categorised as: Academic, How To, LaTeX