The breqn package — Alpha Version, 1997/10/30, 1998/10/01, 2001/09/13

Michael Downes

American Mathematical Society

1 To do

• Handling of QED

• Space between \end{dmath} and following punctuation will prevent the punctuation from being drawn into the equation.

• Overriding the equation layout

• Overriding the placement of the equation number

• “alignid” option for more widely separated equations where shared alignment is desired (requires two passes)

• Or maybe provide an “alignwidths” option where you give lhs/rhs width in terms of ems? And get feedback later on discrepancies with the actual measured contents?

• \intertext not needed within dgroup! But currently there are limitations on floating objects within dgroup.

• align={1} or 2, 3, 4 expressing various levels of demand for group-wide alignment. Level 4 means force alignment even if some lines then have to run over the right margin! Level 1, the default, means first break LHS-RHS equations as if it occurred by itself, then move them left or right within the current line width to align them if possible. Levels 2 and 3 mean try harder to align but give up if overfull lines result.

• Need an \hshift command to help with alignment of lines broken at a discretionary times sign. Also useful for adjusting inside-delimiter breaks.

2 Introduction

The breqn package for L^{A}TEX provides solutions to a number of common difficulties in writing displayed equations and getting high-quality output. For example, it is a well-known inconvenience that if an equation must be broken into more than one line, \left … \right constructs cannot span lines. The breqn package makes them work as one would expect whether or not there is an intervening line break.

The single most ambitious goal of the breqn package, however, is to support automatic linebreaking of displayed equations. Such linebreaking cannot be done without substantial changes under the hood in the way math formulas are processed. For this reason, especially in the alpha release, users should proceed with care and keep an eye out for unexpected glitches or side effects.

3 Principal features

The principal features of the breqn package are:

semantically oriented structure The way in which compound displayed formulas are subdivided matches the logical structure more closely than, say, the standard eqnarray environment. Separate equations in a group of equations are written as separate environments instead of being bounded merely by \\ commands. Among other things, this clears up a common problem of wrong math symbol spacing at the beginning of continuation lines. It also makes it possible to specify different vertical space values for the space between lines of a long, broken equation and the space between separate equations in a group of equations.

automatic line breaking Overlong equations will be broken automatically to the prevailing column width, and continuation lines will be indented following standard conventions.

line breaks within delimiters Line breaks within \left … \right delimiters work in a natural way. Line breaks can be forbidden below a given depth of delimiter nesting through a package option.

mixed math and text Display equations that contain mixed math and text, or even text only, are handled naturally by means of a dseries environment that starts out in text mode instead of math mode.

ending punctuation The punctuation at the end of a displayed equation can be handled in a natural way that makes it easier to promote or demote formulas from/to inline math, and to apply special effects such as adding space before the punctuation.

flexible numbering Equation numbering is handled in a natural way, with all the flexibility of the amsmath package and with no need for a special

\nonumber command.

special effects It is easy to apply special effects to individual displays, e.g., changing the type size or adding a frame. using available space Horizontal shrink is made use of whenever feasible.

With most other equation macros it is frozen when it occurs between \left … \right delimiters, or in any sort of multiline structure, so that some expressions require two lines that would otherwise fit on one.

high-quality spacing The \abovedisplayshortskip is used when applicable (other equation macros fail to apply it in equations of more than one line).

abbreviations Unlike the amsmath equation environments, the breqn environments can be called through user-defined abbreviations such as \beq …

     \eeq.

4 Shortcomings of the package

The principal known deficiencies of the breqn package are:

4.1 Incompatibilities

As it pushes the envelope of what is possible within the context of L^{A}TEX2e, the breqn package will tend to break other packages when used in combination with them, or to fail itself, when there are any areas of internal overlap; successful use may in some cases depend on package loading order.

4.2 Indention of delimited fragments

When line breaks within delimiters are involved, the automatic indention of continuation lines is likely to be unsatisfactory and need manual adjustment. I don’t see any easy way to provide a general solution for this, though I have some ideas on how to attain partial improvements.

4.3 Math symbol subversion

In order for automatic line breaking to work, the operation of all the math symbols of class 2, 3, 4, and 5 must be altered (relations, binary operators, opening delimiters, closing delimiters). This is done by an auxiliary package flexisym. As long as you stick to the advertised L^{A}TEX interface for defining math symbols (\DeclareMathSymbol), things should work OK most of the time. Any more complex math symbol setup is quite likely to quarrel with the flexisym package. See Section 9 for further information.

4.4 Subscripts and superscripts

Because of the changes to math symbols of class 2–5, writing certain combinations such as ^+ or _\pm or ^\geq without braces would lead to error messages; (The problem described here already exists in standard L^{A}TEX to a lesser extent, as you may know if you ever tried ^\neq or ^\cong; and indeed there are no examples in the L^{A}TEX book to indicate any sanction for omitting braces around a subscript or superscript.)

The flexisym package therefore calls, as of version 0.92, another package called mathstyle which turns ^and _into active characters. This is something that I believe is desirable in any case, in the long run, because having a proper mathstyle variable eliminates some enormous burdens that affect almost any nontrivial math macros, as well as many other things where the connection is not immediately obvious, e.g., the L^{A}TEX facilities for loading fonts on demand.

Not that this doesn’t introduce new and interesting problems of its own— for example, you don’t want to put usepackage statements after flexisym for any package that refers to, e.g., ^^J or ^^M internally (too bad that the L^{A}TEX package loading code does not include automatic defenses to ensure normal catcodes in the interior of a package; but it only handles the @ character).

But I took a random AMS journal article, with normal end-user kind of L^{A}TEX writing, did some straightforward substitutions to change all the equations into dmath environments, and ran it with active math sub/sup: everything worked OK. This suggests to me that it can work in the real world, without an impossible amount of compatibility work.

5 Incomplete

In addition, in the alpha release [1997/10/30] the following gaps remain to be filled in:

documentation The documentation could use amplification, especially more illustrations, and I have undoubtedly overlooked more than a few errors.

group alignment The algorithm for doing alignment of mathrel symbols across equations in a dgroup environment needs work. Currently the standard and noalign alternatives produce the same output.

single group number When a dgroup has a group number and the individual equations are unnumbered, the handling and placement of the group number aren’t right.

group frame Framing a group doesn’t work, you might be able to get frames on the individual equations at best.

group brace The brace option for dgroup is intended to produce a large brace encompassing the whole group. This hasn’t been implemented yet.

darray environment The darray environment is unfinished.

dseries environment The syntax and usage for the dseries environment are in doubt and may change.

failure arrangements When none of the line-breaking passes for a dmath environment succeeds—i.e., at least one line is overfull—the final arrangement is usually rather poor. A better fall-back arrangement in the failure case is needed.

6 Package options

Many of the package options for the breqn package are the same as options of the dmath or dgroup environments, and some of them require an argument, which is something that cannot be done through the normal package option mechanism. Therefore most of the breqn package options are designed to be set with a \setkeys command after the package is loaded. For example, to load the package and set the maximum delimiter nesting depth for line breaks to 1:

\usepackage{breqn}
\setkeys{breqn}{breakdepth={1}}

See the discussion of environment options, Section 8, for more information. One package option that may be of interest to TEXnicians is the debug

option; this activates some debugging statements embedded in the code of the alpha release which trace measuring activities related to line breaking.

7 Environments and commands

7.1 Environments

All of the following environments take an optional argument for applying local effects such as changing the typesize or adding a frame to an individual equation.

dmath Like equation but supports line breaking and variant numbers.

dmath* Unnumbered; like displaymath but supports line breaking

dseries Like equation but starts out in text mode; intended for series of mathematical expressions of the form ‘A, B, and C’. As a special feature, if you use

     \begin{math} ... \end{math}

for each expression in the series, a suitable amount of inter-expression space will be automatically added. This is a small step in the direction of facilitating conversion of display math to inline math, and vice versa: If you write a display as

     \begin{dseries}
     \begin{math}A\end{math},
     \begin{math}B\end{math},
     and
     \begin{math}C\end{math}.
     \end{dseries}

then conversion to inline form is simply a matter of removing the \begin{dseries} and \end{dseries} lines; the contents of the display need no alterations.

It would be nice to provide the same feature for $ notation but there is no easy way to do that because the $ function has no entry point to allow changing what happens before math mode is entered. Making it work would therefore require turning $ into an active character, something that I hesitate to do in a L^{A}TEX2e context.

dseries* Unnumbered variant of dseries

dgroup Like the align environment of amsmath, but with each constituent equation wrapped in a dmath, dmath*, dseries, or dseries* environment instead of being separated by \\. The equations are numbered with a group number. When the constituent environments are the numbered forms (dmath or dseries) they automatically switch to ‘subequations’- style numbering, i.e., something like (3a), (3b), (3c), …, depending on the current form of non-grouped equation numbers. See also dgroup*.

dgroup* Unnumbered variant of dgroup. If the constituent environments are the numbered forms, they get normal individual equation numbers, i.e., something like (3), (4), (5), ….

darray Similar to eqnarray but with an argument like array for giving column specs. Automatic line breaking is not done here.

darray* Unnumbered variant of darray, rather like array except in using \displaystyle for all column entries.

dsuspend Suspend the current display in order to print some text, without loss of the alignment. There is also a command form of the same thing,

\intertext.

7.2 Commands

The commands provided by the breqn package are:

\condition This command is used for a part of a display which functions as a condition on the main assertion. For example:

\begin{dmath}
f(x)=\frac{1}{x} \condition{for $x\neq 0$}
\end{dmath}.

f(x) = \frac{1}{x}, for x ≠ 0 . (1)

The \condition command automatically switches to text mode (so that interword spaces function the way they should), puts in a comma, and adds an appropriate amount of space. To facilitate promotion/demotion of formulas, \condition “does the right thing” if used outside of display math. To substitute a different punctuation mark instead of the default comma, supply it as an optional argument for the \condition command:

\condition[;]{...}

(Thus, to get no punctuation: \condition[]{...}.) For conditions that contain no text, you can use the starred form of the command, which means to stay in math mode:

\begin{dmath}
f(x)=\frac{1}{x} \condition*{x\neq 0}
\end{dmath}.

If your material contains a lot of conditions like these, you might like to define shorter abbreviations, e.g.,

\newcommand{\mc}{\condition*}% math condition
\newcommand{\tc}{\condition}%  text condition

But the breqn package refrains from predefining such abbreviations in order that they may be left to the individual author’s taste.

\hiderel In a compound equation it is sometimes desired to use a later relation symbol as the alignment point, rather than the first one. To do this, mark all the relation symbols up to the desired one with \hiderel:

T(n) \hiderel{\leq} T(2^n) \leq c(3^n - 2^n) ...

8 Various environment options

The following options are recognized for the dmath, dgroup, darray, and dseries environments; some of the options do not make sense for all of the environments, but if an option is used where not applicable it is silently ignored rather than treated as an error.

\begin{dmath}[style={\small}]
\begin{dmath}[number={BV}]
\begin{dmath}[label={xyz}]
\begin{dmath}[relindent={1em}]
\begin{dmath}[compact]
\begin{dmath}[spread={1pt}]
\begin{dmath}[frame]
\begin{dmath}[frame={1pt},framesep={2pt}]
\begin{dmath}[background={red}]
\begin{dmath}[color={purple}]
\begin{dmath}[breakdepth={0}]

Use the style option to change the type size of an individual equation. This option can also serve as a catch-all option for altering the equation style in other ways; the contents are simply executed directly within the context of the equation.

Use the number option if you want the number for a particular equation to fall outside of the usual sequence. If this option is used the equation counter is not incremented. If for some reason you need to increment the counter and change the number at the same time, use the style option in addition to the number option:

style={\refstepcounter{equation}}

Use of the normal \label command instead of the label option works, I think, most of the time (untested).

Use the relindent option to specify something other than the default amount for the indention of relation symbols. The default is 2em.

Use the compact option in compound equations to inhibit line breaks at relation symbols. By default a line break will be taken before each relation symbol except the first one. With the compact option L^{A}TEX will try to fit as much material as possible on each line, but breaks at relation symbols will still be preferred over breaks at binary operator symbols.

Use the spread option to increase (or decrease) the amount of interline space in an equation. See the example given above.

Use the frame option to produce a frame around the body of the equation. The thickness of the frame can optionally be specified by giving it as an argument of the option. The default thickness is \fboxrule.

Use the framesep option to change the amount of space separating the frame from what it encloses. The default space is \fboxsep.

Use the background option to produce a colored background for the equation body. The breqn package doesn’t automatically load the color package, so this option won’t work unless you remember to load the color package yourself.

Use the color option to specify a different color for the contents of the equation. Like the background option, this doesn’t work if you forgot to load the color package.

Use the breakdepth option to change the level of delimiter nesting to which line breaks are allowed. To prohibit line breaks within delimiters, set this to 0:

\begin{dmath}[breakdepth={0}]

The default value for breakdepth is 2. Even when breaks are allowed inside delimiters, they are marked as less desirable than breaks outside delimiters. Most of the time a break will not be taken within delimiters until the alternatives have been exhausted.

Options for the dgroup environment: all of the above, and also

\begin{dgroup}[noalign]
\begin{dgroup}[brace]

By default the equations in a dgroup are mutually aligned on their relation symbols (=, <, ≥, and the like). With the noalign option each equation is placed individually without reference to the others.

The brace option means to place a large brace encompassing the whole group on the same side as the equation number.

Options for the darray environment: all of the above (where sensible), and also

\begin{darray}[cols={lcr@{\hspace{2em}}lcr}]

The value of the cols option for the darray environment should be a series of column specs as for the array environment, with the following differences:

• For l, c, and r what you get is not text, but math, and displaystyle math at that. To get text you must use a ’p’ column specifier, or put an \mbox in each of the individual cells.

• Vertical rules don’t connect across lines.

9 The flexisym package

The flexisym package does some radical changes in the setup for math symbols to allow their definitions to change dynamically throughout a document. The breqn package uses this to make symbols of classes 2, 3, 4, 5 run special functions inside an environment such as dmath that provide the necessary support for automatic line breaking.

The method used to effect these changes is to change the definitions of

\DeclareMathSymbol and \DeclareMathDelimiter, and then re-execute the

standard set of L^{A}TEX math symbol definitions. Consequently, additional mathrel and mathbin symbols defined by other packages will get proper line-breaking behavior if the other package is loaded after the flexisym package and the symbols are defined through the standard interface.

10 Caution! Warning!

Things to keep in mind when writing documents with the breqn package:

• The notation := must be written with the command \coloneq. Otherwise the : and the = will be treated as two separate relation symbols with an “empty RHS” between them, and they will be printed on separate lines.

• Watch out for constructions like ^+ where a single binary operator or binary relation symbol is subscripted or superscripted. When the breqn or flexisym package is used, braces are mandatory in such constructions: ^{+}. This applies for both display and in-line math.

• If you want L^{A}TEX to make intelligent decisions about line breaks when vert bars are involved, use proper pairing versions of the vert-bar symbols according to context: \lvert n\rvert instead of |n|. With the nondirectional | there is no way for L^{A}TEX to reliably deduce which potential breakpoints are inside delimiters (more highly discouraged) and which are not.

• If you use the german package or some other package that turns double quote " into a special character, you may encounter some problems with named math symbols of type mathbin, mathrel, mathopen, or mathclose in moving arguments. For example, \leq in a section title will be written to the .aux file as something like \mathchar "3214. This situation probably ought to be improved, but for now use \protect.

• Watch out for the [ character at the beginning of a dmath or similar environment, if it is supposed to be interpreted as mathematical content rather than the start of the environment’s optional argument.

This is OK:

\begin{dmath}
[\lambda,1]...
\end{dmath}

This will not work as expected:

\begin{dmath}[\lambda,1]...\end{dmath}

• Watch out for unpaired delimiter symbols (in display math only):

( ) [ ] \langle \rangle \{ \} \lvert \rvert ...

If an open delimiter is used without a close delimiter, or vice versa, it is normally harmless but may adversely affect line breaking. This is only for symbols that have a natural left or right directionality. Unpaired \vert and so on are fine.

When a null delimiter is used as the other member of the pair (\left. or \right.) this warning doesn’t apply.

• If you inadvertently apply \left or \right to something that is not a delimiter, the error messages are likely to be a bit more confusing than usual. The normal L^{A}TEX response to an error such as

\left +

is an immediate message

! Missing delimiter (. inserted).

When the breqn package is in use, L^{A}TEX will fail to realize anything is wrong until it hits the end of the math formula, or a closing delimiter without a matching opening delimiter, and then the first message is an apparently pointless

     ! Missing \endgroup inserted.

11 Examples

Example 1

Replace $j$ by $h-j$ and by $k-j$ in these sums to get [cf.~(26)]
\begin{dmath}[label={sna74}]
\frac{1}{6} \left(\sigma(k,h,0) +\frac{3(h-1)}{h}\right)
  +\frac{1}{6} \left(\sigma(h,k,0) +\frac{3(k-1)}{k}\right)
=\frac{1}{6} \left(\frac{h}{k} +\frac{k}{h} +\frac{1}{hk}\right)
  +\frac{1}{2} -\frac{1}{2h} -\frac{1}{2k},
\end{dmath}
which is equivalent to the desired result.

Replace j by h − j and by k − j in these sums to get [cf. (26)]

(11.2)

\frac{1}{6} (σ(k, h, 0) + \frac{3(h − 1)}{h}) + \frac{1}{6} (σ(h, k, 0) + \frac{3(k − 1)}{k}) = \frac{1}{6} (\frac{h}{k} + \frac{k}{h} + \frac{1}{hk} )

+ \frac{1}{2} − \frac{1}{2h} − \frac{1}{2k} ,

which is equivalent to the desired result.

Example 2

\newcommand\mx[1]{\begin{math}#1\end{math}}% math expression
%
Now every column which has no circled entry is completely zero;
so when $k=6$ and $k=7$ the algorithm outputs two more vectors,
namely
\begin{dseries}[frame]
\mx{v^{[2]} =(0,5,5,0,9,5,1,0)},
\mx{v^{[3]} =(0,9,11,9,10,12,0,1)}.
\end{dseries}
From the form of the matrix $A$ after $k=5$, it is evident that
these vectors satisfy the equation $vA =(0,\dotsc,0)$.

Now every column which has no circled entry is completely zero; so when k = 6 and k = 7 the algorithm outputs two more vectors, namely

v^{[2]} = (0, 5, 5, 0, 9, 5, 1, 0) , v^{[3]} = (0, 9, 11, 9, 10, 12, 0, 1) . . (11.3)

From the form of the matrix A after k = 5, it is evident that these vectors satisfy the equation vA = (0, …, 0).

Example 3

\begin{dmath*}
T(n) \hiderel{\leq} T(2^{\lceil\lg n\rceil})
  \leq c(3^{\lceil\lg n\rceil}
    -2^{\lceil\lg n\rceil})
  <3c\cdot3^{\lg n}
  =3c\,n^{\lg3}
\end{dmath*}.

T (n) ≤ T (2^{⌈lg n⌉}) ≤ c(3^{⌈lg n⌉} − 2^{⌈lg n⌉})
< 3c · 3^{lg n}
= 3c n^{lg 3} .

Example 4

The reduced minimal Gr\"obner basis for $I^q_3$ consists of
\begin{dgroup*}
\begin{dmath*}
H_1^3 = x_1 + x_2 + x_3
\end{dmath*},
\begin{dmath*}
H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2
\end{dmath*},
\begin{dsuspend}
and
\end{dsuspend}
\begin{dmath*}
H_3^1 = x_1^3 - 2x_1 q_1 - x_2 q_1
\end{dmath*}.
\end{dgroup*}

The reduced minimal Gröbner basis for I_{3}^{q} consists of

H_{1}^{3} = x_{1} + x_{2} + x_{3} ,
H_{2}^{2} = x_{1}^{2} + x_{1}x_{2} + x_{2}^{2} − q_{1} − q_{2} ,

H_{3}^{1} = x_{1}^{3} − 2x_{1}q_{1} − x_{2}q_{1} .