latex_once_expanded_abbrev.md

LaTeX Pearl: Once-expanded Abbreviations

As I get further into my PhD thesis I expect more of these pearls to be about LaTeX. This one came about while I was trying to satisfy a common writing style requirement (one of those rigidly enforced by my advisor): abbreviations and acronyms must be defined once and only once, namely when they are first used.

It's a little hard to remember to do this, and when the editing process involves wholesale reordering of paragraphs and sections, that can require moving the definition to the new first use of an acronym, which is annoying. I'm writing this thesis in separate files per chapter, which are then combined when compiling the whole thesis. So the first use might be in a different file altogether. Furthermore, the chapter files can be compiled individually, so I might want an acronym explained at first use in-chapter in that situation, even if it's omitted when compiling the final thesis.

To implement this, I ended up writing a self-modifying command. That bent my brain a little, but it worked out. Without further ado, here is the macro:

\newcommand{\abbronce}[3]{%
    \newcommand{#1}{%
        \renewcommand{#1}{#2}%
        #2 (#3)%
    }%
}

A couple of example abbreviations defined using it:

\abbronce{\imu}{IMU}{inertial measurement unit}
\abbronce{\mdf}{MDF}{medium-density fiberboard}

And here is how it's used:

The sensor frame is made of \mdf{}, which is shaped using a laser cutter. This process allows for rapid prototyping and design iteration, and using \mdf{} keeps the frame light and rigid. In the middle we mount an \imu{} with the Z axis pointing up.

Data from the \imu{} is processed at 100 Hz...

<tex_output/>

Let's see that macro again.

\newcommand{\abbronce}[3]{%
    \newcommand{#1}{%
        \renewcommand{#1}{#2}%
        #2 (#3)%
    }%
}

We'll go through it one element at a time. First a few notes.

What are the funny percent signs at the end of each line? That's how you start a comment in LaTeX, but here they prevent the newline from affecting the macro output. I'll be honest, this seems like a huge hack (but this is LaTeX we are talking about) and I learned this trick by copying conference paper templates.
The three arguments are:
1. Name of the command that will be defined to write our acronym
2. The short form of the acronym or abbreviation
3. The expanded form which will be shown only once

Now we can get into the meat of the macro itself. Taking a deep breath... \abbronce is a command which defines a command (named #1") that when invoked, redefines itself to produce only #2, then outputs #2 (#3)`. This can be demonstrated by showing a few expansions:

\newcommand{\abbronce}[3]{%
    \newcommand{#1}{%
        \renewcommand{#1}{#2}%
        #2 (#3)%
    }%
}
\abbronce{\imu}{IMU}{inertial measurement unit}
\imu{}

\imu{}

\newcommand{\imu}{%
    \renewcommand{\imu}{IMU}%
    IMU (inertial measurement unit)%
}%
\imu{}

\imu{}

\imu{}

\imu{}

\renewcommand{\imu}{IMU}%
IMU (inertial measurement unit)%

\imu{}

IMU (inertial measurement unit)%

\imu{}

IMU (inertial measurement unit)%

IMU

It works! An added benefit of this approach to abbreviations is since they are always written using a macro throughout the document, there's a potential for using \abbronce to create a registry of abbreviations and write out a glossary somewhere.

durka/latex_once_expanded_abbrev.md

LaTeX Pearl: Once-expanded Abbreviations