Define and manage math commands in LyX with macros

LyX is an awesome LaTeX frontend that supports editing in a WYSIWYM (what you see is what you mean) way. Although LyX supports all LaTeX commands, not all commands can be rendered well in the WYSIWYM editor. But LyX is flexible enough to allow users to define the command and how it should look in the WYSIWYM editor.

How to insert a macro? #

LyX does not parse the preamble in your document, nor does it parse the \usepackage part, so you need to tell LyX explicitly what new commands you are introducing and what should they look like.

If you haven't, please read the math manual from Help → Math, and then Navigate → 22 User-defined Commands → 22.2 Math Macros. You will find some useful information there, and we are not covering every detail here.

In short, click Insert → Math → Macros, enter the name of the command, and type the definition in the TeX box. If the functionality you want is already supported in LyX and you just want some shortcut, you can type the definition just like in a regular LyX math box, and reference parameters like \#1.

To add \ket support via "vanilla LyX", in the TeX box, click the "Insert delimiters" button in the math tool, uncheck "Keep matched", and select $|$ and $\rangle$. Click the "Append argument" button and enter \#1 in the ket. Since LyX understands the TeX command, we can just ignore the LyX box, and LyX will use the definition in the TeX box.

Again, details are covered in the manual, and make sure to read that.

What if I want LyX to support command in a package? #

Note

From LyX-2.4.0-beta3, things are a lot easier. You can just fill the LyX box to define how the macro displays in LyX and leave the TeX box empty, and things will work as expected.

* Format incremented to 616: Do not output LaTeX for a macro if the LaTeX part is empty
- This allows the user to define the LyX display for LaTeX commands
  that are already defined (e.g., in user preamble or a package).

text

Well, that's a tricky part. LyX uses the \def command under the hood. For example, the \ket definition above results in:

\global\long\def\ket#1{\left|#1\right\rangle }%

This means you cannot add a \ket macro and point to the \ket command in the braket package. Because this attempt will produce something like:

\global\long\def\ket#1{\ket{#1} }%

This will cause recursions and the document will fail to compile, yielding:

TeX capacity exceeded.

As Sean Allred suggests, you can first rename \ket to \realket by adding \let\realket\ket in the preamble, and use \realket inside the macro \ket. This will not cause infinite recursions because \let is static but \def is dynamic. \realket will always be \ket at that moment.

Curly brackets are escaped in the TeX box? #

Yes, it's tricky for LyX to determine whether a curly should be escaped. Try one of these solutions:

1. Type \{ instead of {.
2. Delete and type again. LyX will skip escaping a curly pair if typed after a command.
3. Copy the correct ones and paste them.
4. Type the \newcommand TeX command in plain LyX, then select it and convert it to math macro.

Too many macros? #

As the number of macros added to the document increases, they can soon bloat your document, making the document a mess. There are two ways to fix this: either fold all the macros or manage macros in an external file.

Fold the macros #

There is no built-in way to fold a part of the LyX document, but there is a workaround. In the menu, select Insert → Branch → Insert New Branch..., and enter "macro". Right-click on the inserted "Branch: macro" and click "Activate Branch". Put your macros there and click the label to fold/unfold the box.

Manage macros in external files #

You can create a new clean LyX file and enter the macros there. After saving that file, go back to you document and select Insert → File → Child Document... to add that file to your document. (Source)

One disadvantage is that the file path can be relative or absolute. If it's relative, you have to copy the macros.lyx along when moving the document. But if it's absolute, it's not convenient for sharing. That's why I personally prefer including macros in the document and folding them.