The PreTeXt Guide

Documents, pages, and screens tend to run vertically from top to bottom. But sometimes you want to control elements laid out horizontally. A <sidebyside> is designed to play this role. It is best thought of as a container, enclosing panels, and specifying their layout. Examples include three images, all the same size and equally spaced. Or a poem occupying two-thirds of the available width, with commentary adjacent in the remaining third. Or an image next to a table. But the most common use may be a single image (with no caption, and hence no number), whose width and horizontal placement are controlled by the layout.

See the schema for the exact items that are allowed in a <sidebyside>. To author, just place these items within <sidebyside> in the order they should appear, left to right. Then you add attributes to the <sidebyside> element to affect placement.

Instead of placing a @width attribute on each item, instead place this on the <sidebyside> element. A single @width will use the same value for each panel. For different widths, use the plural form @widths and provide a space-separated list of percentages. The default is to give each panel the same width, and as large as possible, which will result in no gap between panels.

The margins can be specified with the @margins attribute, which if given as a single percentage will be used for both the left and right sides. You may also specify asymmetric left and right margins with two percentages, separated by a space, in the same attribute. An additional option is to use the value auto which will set each margin to half of the (common) space between panels. This is also the default. In the case of a single panel, the left margin, right margin, and panel width should all add up to 100%.

Once the widths and margins are known, any additional available width is used to create a common distance separating panels. (Which is not possible when there is just a single panel.)

Independent of horizontal positioning, individual panels may be aligned vertically. The attribute is @valigns and its value is a space-separated list of top, middle, and bottom. The singular version, @valign, is used to give every panel the same alignment, using the same keywords. The default is to have every panel at the top.

<sidebyside widths="20% 40% 25%" margins="auto" valign="middle">

For a single panel with no attributes, the panel will occupy 100% of the width. A single panel with a specified width will get equal (auto) margins, resulting in a centered panel.

Captioned items as panels deserve special mention. These will continue to be numbered consecutively, with one exception. If you place a <sidebyside> inside of a <figure>, then the <figure> will be numbered, and the captioned items inside the <sidebyside> will be sub-captioned. In other words, the second captioned panel of a <sidebyside> inside Figure 5.2 would be referenced as Figure 5.2.b.

An <sbsgroup> (“side-by-side group”) contains only <sidebyside>, which are displayed in order. However, all of the layout parameters allowed on a <sidebyside> may be used on an <sbsgroup>. This might allow a collection of fifteen images to be laid out in three rows of five images each, with widths and spacing identical for each row because the parameters are specified on the <sbsgroup> element. In this way, simple grids can be constructed. Note that any layout parameters given on an enclosed <sidebyside> will take priority over those given on the <sbsgroup>. Captioning behavior extends to an entire <sbsgroup>.

Since <sidebyside> and <sbsgroup> are containers they cannot be referenced and so do not have an @xml:id. However, you can reference their individual contents if they are captioned, and you can reference an enclosing <figure>.

Generally, a <sidebyside> or <sbsgroup> can be placed as a child of a division, or within various blocks, such as <proof> for example. See the schema for (evolving) specifics.

It should be clear now that a <sidebyside> is more about presentation than most PreTeXt elements, though there is some semantic information being conveyed by grouping the panels with one another.