@Section
   @Title { Displaying equations }
   @Tag { mathdisplays }
@Begin
@PP
The result of the @Code "@Eq" symbol is an object which, according to the
displayed.equations @Index { displayed equations }
golden rule (Section {@NumberOf objects}), may appear anywhere:  inside
a paragraph, inside a table, and so on.  In particular, equations are
often displayed using the @Code "@CentredDisplay" or @Code "@IndentedDisplay"
symbols from Section {@NumberOf displays}:
@ID @Code "@IndentedDisplay @Eq { ... }"
Now displayed equations are often numbered, and often aligned with one
another on their equals signs.  For this there are special display
symbols which are the the subject of this section.  These symbols can
align and number any display at all, but since in practice they seem to
be used only with equations, we discuss them here rather than in
Section {@NumberOf displays} where they really belong.
@PP
Let's begin by looking at a first example of a numbered display:
aligned.displays @Index { aligned displays }
aligned.equations @Index { aligned equations }
numbered.displays @Index { numbered displays }
numbered.equations @Index { numbered equations }
@BeginNumberedDisplays
@BeginAlignedDisplays
@CentredAlignedNumberedDisplay
  @Tag { fibeq }
@Eq { F sub n ^= F sub n-1 + F sub n-2 }
After the display we might have some more text for a while, and then
we might want a second display, aligned on its equals sign with the
first, and also numbered in sequence with it:
@CentredAlignedNumberedDisplay
@Eq { F sub n - F sub n-1 ^= F sub n-2 }
@EndNumberedDisplays
@EndAlignedDisplays
Notice that the two displays are centred as a block as well as
aligned.  Altogether there are four ways in which displays vary:
@BL
@LI { A display can be raw or not raw (see below); }
@LI { It can be a {@Code "@Display"}, {@Code "@LeftDisplay"},
{@Code "@IndentedDisplay"}, {@Code "@QuotedDisplay"},
{@Code "@CentredDisplay"} or {@Code "@CenteredDisplay"}; }
@LI { It can be aligned or not aligned; }
@LI { It can be numbered or not numbered. }
@EL
All possible combinations are allowed.  The display that has everything
is called
@ID @Code "@RawCentredAlignedNumberedDisplay"
By leaving out some or all of {@Code Raw}, {@Code Aligned}, and
{@Code Numbered}, and by changing or leaving out {@Code Centred},
we get all these combinations.
@PP
When aligned displays are used, it is necessary to indicate where the
aligned group begins and ends, by placing @Code "@BeginAlignedDisplays"
beginaligneddisplays @Index @Code "@BeginAlignedDisplays"
endaligneddisplays @Index @Code "@EndAlignedDisplays"
just before the first, and @Code "@EndAlignedDisplays" just after the
last.  The alignment points are indicated by preceding them by the
symbol {@Code "^"}, so you aren't restricted to aligning at
equals signs.  Numbered displays are similarly bracketed by
@Code "@BeginNumberedDisplays" and {@Code "@EndNumberedDisplays"}.  So
beginnumbereddisplays @Index @Code "@BeginNumberedDisplays"
endnumbereddisplays @Index @Code "@EndNumberedDisplays"
numbereddisplay. @Index @Code "@NumberedDisplay"
aligneddisplay. @Index @Code "@AlignedDisplay"
then, here is how the two displays given earlier were made:
@ID @OneRow @Code {
"... a first example of a numbered display:"
"@BeginNumberedDisplays"
"@BeginAlignedDisplays"
"@CentredAlignedNumberedDisplay"
"  @Tag { fibeq }"
"@Eq { F sub n ^= F sub n-1 + F sub n-2 }"
"After the display we might ... numbered in sequence with it:"
"@CentredAlignedNumberedDisplay @Eq { F sub n - F sub n-1 ^= F sub n-2 }"
"@EndNumberedDisplays"
"@EndAlignedDisplays"
"Notice that the two displays are centred ..."
}
All numbered displays have an optional @Code "@Tag" option which is
used for cross referencing (see Section {@NumberOf cross}).  Alignment
and numbering work quite independently; they don't have to start or end
together, and there can be non-aligned and non-numbered displays among
the others.
@PP
@Code "@BeginNumberedDisplays" has two options:
@ID @OneRow @Code {
"@BeginNumberedDisplays"
"   style { [tag] }"
"   start { 12.5 }"
}
will cause the associated numbered displays to be labelled [12.5],
[12.6], and so on.  The first label is the @Code style option with
@Code tag replaced by the @Code start option.  Font changes and other
symbols are acceptable within the @Code style option.  When omitted, the
options have default values @Code "(tag)" and @Code "1" respectively.  A
good value to give to a @Code "start" option in a section whose @Code "@Tag"
option is @Code "integral.transforms" would be
@ID @Code "start { @NumberOf { integral.transforms }.1 }"
since then the correct section number is inserted automatically.  There
ought to be a way of saying `the number of this section,' but there isn't.
@PP
@Code "@BeginNumberedDisplays" and @Code "@EndNumberedDisplays"
cannot span across several sections or subsections:  the equations
numbered by them must lie within a single large-scale structure
symbol.  The same is true of @Code "@BeginAlignedDisplays" and
{@Code "@EndAlignedDisplays"}.
@PP
In our example of aligned and numbered displays, the two displays
were separated by some ordinary text.  Very often, though, aligned
displays follow directly after each other.  This is a problem, because
if you have one display directly following another there will be too
much vertical space between them.  This problem was mentioned in
Section {@NumberOf displays}, and the recommended solution was to
use a list.  However, there are no aligned or numbered (in this sense)
lists.
@PP
To solve this problem, each display symbol has a `raw' version, which
means that no space is inserted above or below the display.  Instead,
raw.displays @Index { raw displays }
you must insert it yourself using paragraph symbols:
@ID @OneRow @Code {
"preceding text"
"@DP"
"@RawAlignedDisplay @Eq { ... }"
"@DP"
"@RawAlignedNumberedDisplay @Eq { ... }"
"@DP"
"following text"
}
You get the right spacing by placing {@Code "@DP"} symbols before,
between, and after each display; and you get to use the specialized
displays that you need.  Raw and non-raw displays may be numbered and
aligned together.
@PP
Every display symbol has an abbreviated form consisting of @Code "@"
followed by its capital letters only.  For example,
@Code "@BeginNumberedDisplays" may be abbreviated to {@Code "@BND"},
and the display that has everything to {@Code "@RCAND"}.
@End @Section
