[Tex/LaTex] Keeping the names of things consistent in LyX.

best practiceslyxmacros

I'm documenting a software project using LyX and many of the "things" (classes, processes, etc.) that I'm describing don't yet have good names. As my understanding of these things improves, I want to give them better names. But I don't want to end up with a situation where a given thing is referred to by more than one name due to a botched search-and-replace.

I vaguely remember that there is a way in LyX to insert a reference to a term that will auto-update when the referenced term is modified. For example, if I have a section titled "All About Foobar", I can insert references to "Foobar" in the subsequent text. If ever I decide on a more descriptive name for Foobar, say Bazqux, I can simply update the section title and–poof!–every Foobar becomes a Bazqux.

It's a simple thing, but my Google-fu is weak this afternoon. Or maybe I'm crazy and no such feature exists.

Best Answer

It's not entirely clear what you want, exactly. But you can easily define a macro which spells out the name and can therefore be changed once in the document. For example, if you have something that for the moment you are calling 'class', you could define the following macro:

\newcommand*{\class}{class}

(The * here means that the macro can't contain any paragraph breaks; see the following question for more details on this.

What's the difference between \newcommand and \newcommand*?

In your text, you would then type \class in every place you want that object name. If you decide that you want to call a class a method, you would simply redefine the \class macro:

\newcommand*{\class}{method}

There are a couple of things you need to bear in mind with this sort of solution. First, spaces after macros are ignored, so if you your source has

In this \class we strip out spaces.

It will be rendered as In this classwe strip out spaces, which is not what you want. You can't simply add a space to the definition, since this will incorrectly add spaces before e.g. punctuation marks, where you don't want them. So there are two ways around this. One is to simply insert an overt space whenever you need one using \:

In this \class\ we strip out spaces.

The other solution is to use the xspace package, which inserts a space automatically and takes care not to insert the space before punctuation.

\usepackage{xspace}
\newcommand*{\class}{class\xspace}

Then you don't need to type the explicit space yourself. Note, however, that there are some drawbacks to using the xspace approach. See:

Drawbacks of xspace

The second pitfall with defining replacement macros this way, is that they don't adjust for things like plurals and capitalization. To capture these cases, it's probably easiest to simply define uppercase and plural version of the macros themselves. (You could do other fancier things, but at the expense of making your source less readable.) So you could define:

\newcommand*{\Class}{Class}
\newcommand*{\classes}{\class es}
\newcommand*{\Classes}{\Class es}

The following article by Will Robertson is a useful guide to these sorts of techniques:

Productivity with Macros and Packages

Here is a small document with all of the examples above included in it.

\documentclass{article}
\usepackage[margin=1in]{geometry}
\usepackage{xspace}
\newcommand*{\class}{class} % if your command will have multiple lines omit the *
\newcommand*{\Class}{Class} % uppercase version
\newcommand*{\classes}{\class es} % plural versions
\newcommand*{\Classes}{\Class es}

\begin{document}
If we don't add an explicit space after the \class macro it doesn't work as we expect.

We can make the \class\ macro work by adding the space explicitly.

Or if we change the macro to use the xspace package, it will insert the space automatically:
\renewcommand*{\class}{class\xspace}

Now the \class macro inserts a space, but not when there is punctuation following \class.
\end{document}

The only thing I haven't mentioned here is how to do all of this in LyX. The \newcommand definitions go into your document preamble the way you would add any other raw LaTeX code to a document. If you will be using them a lot it might be useful to create a LyX layout to do this. For more on how to add customized environments to LyX see:

Create new paragraph style in LyX

Related Question