Labels

Section 3.4 Labels

It can be helpful to label a graphical component in a diagram to call attention to that component and to connect it to the exposition in the surrounding text. PreFigure allows authors to add labels to a diagram and provides some options for their display.

Subsection 3.4.1 Creating labels

The <label> element provides a way of adding text to a diagram. Labels are composed of plain text, mathematics, or a combination of both. Mathematics is written in LaTeX and enclosed in an <m> element. Figure 3.4.1 demonstrates some possibilities with the PreFigure source given in Listing 3.4.2.

<diagram dimensions="(250,200)" margins="5">
  <coordinates bbox="(0,0,5,4)">
    <label anchor="(1,3)" alignment="east">
      <m>\displaystyle f(a)=\frac{1}{2\pi i}\oint_C \frac{f(z)}{z-a}~dz</m>
    </label>
    <label anchor="(1,2)" alignment="east">
      Temperature
    </label>
    <label anchor="(0.5,1)" alignment="east" rotate="90" scale="1.5">
      Time <m>t</m> (sec)
    </label>
  </coordinates>
</diagram>

Listing 3.4.2. The PreFigure source for Figure 3.4.1.

Labels can span multiple lines and include bold and italic fonts, as shown in Figure 3.4.3 and Listing 3.4.4. While this provides a lot of flexibility, authors should use these features judiciously and make sure text that more properly belongs in surrounding paragraphs does not creep into a diagram.

<diagram dimensions="(350,200)" margins="5">
  <coordinates bbox="(0,0,10,5)">
    <grid/>
    <label anchor="(1,4)" alignment="e" justify="left"
	   clear-background="yes">
      This is a <b>bold</b> statement
      <newline/>
      but we can have <it>itatics</it>
      <newline/>
      and <it>italicized <b>bold</b></it> as well
    </label>

    <label anchor="(5,2)" alignment="c" justify="center"
	   clear-background="yes" interline="10">
      Math can still appear:
      <newline/>
      The <it>derivative</it> of <m>e^x</m> is <m>e^x</m>
    </label>

    <label anchor="(1,1)" alignment="se" scale="0.6"
	   clear-background="yes">
      Use the @scale attribute to change the font size.
    </label>
  </coordinates>
</diagram>

Listing 3.4.4. The PreFigure source for Figure 3.4.1.

Here are some important attributes that determine the placement of labels.

anchor: The label is placed relative to an @anchor point with the default being @anchor="(0,0)".
alignment: The @alignment attribute specifies how the label is positioned relative to the anchor point. Figure 3.4.5 demonstrates the nine possibilities. Each alignment has a 1- or 2-character abbreviation so, for example, @alignment="se" is equivalent to @alignment="southeast".

Figure 3.4.5. Aligning text to an anchor point.
offset: PreFigure inclues some padding between the anchor and the label, but you will sometimes find that you need to fine tune the position of a label using the @offset label. Stating @offset="(2,-3)" will move the label two SVG units to the right and three units down from the position determined by the anchor and the alignment.
clear-background: Setting @clear-background="yes" causes a white rectangle to be filled behind the label so that it stands out from the background, as seen in Figure 3.4.6.

Figure 3.4.6. Setting @clear-background="yes"
scale, rotate: As illustrated in Figure 3.4.1, labels can be scaled and rotated.
justify: If a label includes more than one line, this attribute determines how the lines are spaced horizontally. The possible values are @justify="center", "left", "right" with center being the default.
interline: This attribute will have a numerical value that determines the vertical space, in SVG units, between lines. The default is @interline="3".

We remind authors of one exception in that the @xlabel and @ylabel attributes of an <axes> element are interpreted as LaTeX expressions and automatically wrapped in an <m> element.

PreFigure supports the use of color in labels, though you are encouraged to use it sparingly. Figure 3.4.7 illustrates this feature. First off, notice that is possible to color the entire label by given the <label> a @color attribute. However, individual parts of a label, including <m> elements, may be given a @color attribute as well. Notice that there is a <plain> element that can be used to give color to text that is neither italicized nor bolded.

Figure 3.4.7. Some labels with color added.

<diagram dimensions="(400,150)" margins="5">
  <coordinates bbox="(0,0,10,3)">
    <grid-axes decorations="no"/>
    <label anchor="(1,2)" alignment="east" color="red"
           scale="1.5" clear-background="yes">
      Everything <it>is in <b>red</b></it>: <m>\int_0^1 e^x~dx</m>
    </label>

    <label anchor="(1,1)" alignment="east" scale="1.5"
           clear-background="yes">
      <plain color="blue">Individual</plain>
      parts
      <it color="green">are</it>
      <b color="red">colored:</b>
      <m color="magenta">e^x</m>
    </label>
  </coordinates>
</diagram>

Listing 3.4.8. The PreFigure source for Figure 3.4.7.

Best practices.

Authors should think carefully about the use of labels in their diagrams. In particular, it can be tempting to include lots of labels, possibly even long, complicated labels, in a diagram. However, diagrams should always be carefully integrated into a larger document, which means that the surrounding exposition and caption should help readers interpret the meaning of a diagram. Labels should mainly refer to graphical components and serve as a connection to the surrounding text. This is especially important for the production of tactile diagrams, in which labels that appear relatively short in print can become quite long when parsed into braille. So even though Cauchy’s formula is indeed beautiful, you should probably not include it in a diagram.

Subsection 3.4.2 Legends

PreFigure allows authors to include a legend with a diagram, as seen in Figure 3.4.9 and Listing 3.4.10. A variety of graphical components may be included in a legend, including paths, such as the graph of a function, points, two-dimensional regions. While legends will be faithfully rendered in a tactile diagram, it is likely they will not be as informative as their appearance in a non-tactile diagram. In general, a better practice may be to place individual labels next to the components themselves.

A <legend> tag defines a legend with <item> tags inside to declare the graphical components to include in the legend. An <item> tag must include a @ref attribute that refers to the desired graphical component with the attached label inside the <item> tag.

<diagram dimensions="(300,300)" margins="5">
  <definition>f(x)=sin(x)</definition>
  <definition>g(x)=cos(x)</definition>
  <coordinates bbox="(-1,-1.5,10,2)">
    <grid-axes xlabel="t"/>
    <graph at="sin" function="f"/>
    <graph at="cos" function="g" stroke="red"
	   dash="4 4" tactile-dash="9 9"/>
    <point at="point" p="(4,1)" style="cross" stroke="green"/>
    <rectangle at="rectangle"
	       center="(2,1.5)" dimensions="(2,0.5)"
	       fill="magenta" stroke="gray"/>

    <legend anchor="(bbox[2], bbox[3])"
	    alignment="sw" opacity="0.9"
	    scale="0.9" vertical-skip="10">
      <item ref="sin"><m>x(t)</m></item>
      <item ref="cos"><m>x'(t)</m></item>
      <item ref="point">Point</item>
      <item ref="rectangle">Rectangle</item>
    </legend>
  </coordinates>
</diagram>

Listing 3.4.10. The PreFigure source for Figure 3.4.9.

There are a number of ways to decorate a legend:

anchor: The required @anchor attribute defines the location of the legend.
alignment: The @alignment attribute declares how the legend is aligned relative to the anchor.
stroke: This attribute, whose value could be "none", defines the color of the legend’s border.
scale: This attribute scales the entire legend.
vertical-skip: The @vertical-skip attribute defines the space between legend items. The default is 7 SVG units.
opacity: This controls the opacity of the legend’s white background.

Prev Top Next