<-- previous page Table of Contents Index next page -->

## Location tags

A location tag is associated with a note, chord, lyric syllable or barline. It can then be referenced in order to place a second object, like a comment or dotted line, relative to the first object.

A tag name can be either a single lower case letter, or an underscore folowed by one or more letters, digits, or underscores. Each location tag is really a collection of six values, namely the north, south, east, west, x, and y values of the tagged object. These are referenced by giving the tag name followed by a dot, followed by the letter n, s, e, w, x, or y. For example:

    c.n	// north of tag c
    _xyz.e	// east of tag _xyz
    x.x	// x coordinate of tag x

The n, s, e, and w values describe the smallest rectangle that will completely enclose the object being tagged. The north refers to the top of the object, the south to the bottom, the west to the left edge, and the east the right edge. The x and y values correspond to the "center" coordinate of the object. This is not necessarily the geometric center, but more of a "logical center." In the case of a tag associated with an individual note, it is the geometric center of the note head. However, on tags associated with a chord, the x is at the center line of note heads that are on the "normal" side of the stem. (Normally, when a stem is up, notes are put on the left side of the stem, and when the stem is down they are placed on the right side. However, when two notes adjacent on the staff have to be printed in a single chord, one has to be moved to the opposite side.) The y of a chord is always the middle line of the staff containing the chord. The x of a bar line is its geometric center. The y of a bar line is the center line of the top visible staff. For lyrics, the n, s, e, and w give the boundaries of the smallest box that encloses the syllable, including anything inside <^ >, but excluding anything inside < >, while the x and y are the center of that box.

Tag names can be re-used. The value of a tag will always be its most recent definition.

There are also several "pre-defined" tags. They are:

_page
  the entire page
_win
  the available part of the page
_cur
  the current location

The _page tag refers to the entire page. The x and y values of _page are at the geometric center of the page. This tag is seldom useful, but is provided in case you want to force something to a specific place on a page.

The _win tag refers to the area of the page available for printing. The name comes from the idea that it provides a view, as if through a window, of a portion of the page. Its precise meaning depends upon the current context. In header, footer, top, bottom, header2, footer2, top2, bottom2, and block contexts, it refers to the area of the page taken up by the corresponding element. In music context, it refers to the area of the page that remains after excluding the margins and the header, footer, top and bottom for the page. There is no way to access location tags in any other contexts, so _win (and all other location tags) are meaningless in other contexts.

The _cur tag refers to the current location on the page. This is a single point, such that east and west values are the same as x, and north and south values are the same as y. It is only useful immediately after a command that explicitly sets the current location, that is, after a printing command or line or curve command. Since Mup places musical data in an arbitrary order, trying to use _cur at other times is likely to cause output at a seemingly random place.

Location tags can be referenced by a number of commands, including those for printing text, or drawing lines or curves. In the simplest case, two tag references are given in parentheses. The first tag will refer to a horizontal direction (the "x" direction for mathematicians), namely a tag with a w, e, or x after the dot. The second tag is then a vertical tag, having n, s, or y. For example:

    (g.x, g.y)	// x and y of tag "g"
    (_tag.w, _item.n)   // west of tag "_tag" and
                       // north of tag "_item"

The first example refers to the x,y coordinate of tag "g". The second item refers to two different tags. The point referenced has its horizontal location aligned with the west side of the object having the tag "_tag," while its vertical position is in line with the north side of the object having the tag "_item". In other words, if a line were drawn along the west side of the object tagged with "_tag" and another line were drawn along the top edge of the object with tag "_item", the point where those two lines crossed would be the point referenced.

Frequently, you may want to place something relative to a tagged object. You can add offsets in both the x and y dimensions. These offsets are given in stepsizes. As was mentioned earlier, a stepsize is half the distance between two staff lines.

    (g.x + 4.5, g.y + 4.5)

refers to the point 4.5 stepsizes to the right and above the point (g.x, g.y). Adding an offset moves to the right in the horizontal direction and upward in the vertical direction. You can also subtract an offset:

    (k.w - 1.3, m.n - 2)

refers to a point 1.3 stepsizes to the left of the west edge of k and 2 stepsizes below the top of m.

In the horizontal direction, offsets can be given in terms of "time". This is specified by using the keyword "time" followed by a number of beats. As an example, suppose we have the tag reference:

    (q.x + time 1, q.y + 2)

If the time signature is 4/4 and tag "q" happens to be associated with a half note, this tag reference would refer to a point halfway between that note and the following chord, since it includes an offset of a quarter note. If "q" had been associated with a whole note, the point would be only 1/4 of the way between the note and the following chord. Since notes are placed based on various constraints and aesthetic considerations, the actual distance will vary depending on which tag is referenced.

In the case of a tag associated with a bar line, the time to distance mapping is done based on the distance between the bar (at count "0") and the first chord in the measure (at count "1"). So, for example, in 4/4 time, a reference to a bar line tag + time 0.5 would indicate a place halfway between the bar line and the first chord, whereas tag + time 0.25 would be one fourth of the way.

The mapping of time to distance is done based on the note, rest, lyric syllable, or bar line associated with the most recent horizontal tag in the expression. For example, if the most recent horizontal tag is associated with a quarter note, and the distance between that note and the next was 0.5 inches, specifying "+ time 2" (a half note) would mean 1.0 inch to the right, or specifying "- time 2" would mean 1.0 inch to the left, even if the notes to the left or right happened to be spread somewhat differently than 0.5 inches per quarter note. Thus it is usually advisable not to specify a time offset greater than the time value of the note or rest associated with the tag, nor to subtract a time value. Stated another way, when specifying the X portion of a coordinate using a time offset, it is best to use a location tag based on whichever note, rest, or bar is immediately to the left of the X location you are trying to specify.

If the first horizontal tag in a horizontal expression is associated with a bar, and that bar happens to be at the end of a score other than the final score, and the result of evaluating the expression is a location that would be out in the right margin or off the right edge of the page, it will be moved to act as if the bar was at the beginning of the following score.

The various kinds of offsets can be combined.

    ( _pp + 1.2 - time 3.5, _zz + 2)

If no tag is specified, the reference becomes an absolute reference, giving an exact page location. For example:

    (10, 20)

is 10 stepsizes from the left edge and 20 stepsizes above the bottom of the page.

While usually the horizontal and vertical specifications will each be just a tag and direction, possibly plus or minus some offset, they can be more complicated arithmetic expressions. The expressions can involve * for multiplication, / for division, or % for modulo. These operators have higher precedence than addition or subtraction, but you can use parentheses to force different precendence. You can also use + or - as a unary operator, which has the highest precedence of all. The unary + is rarely useful, but unary - is used if you want to have a negative number. There are also several functions available that you can use, namely:

Name | Description | Parameters
sqrt | square root | 1
sin | sine | 1
cos | cosine | 1
tan | tangent | 1
asin | arc sine | 1
acos | arc cosine | 1
atan | arc tangent | 1
atan2 | arc tangent y/x | 2
hypot | hypotenuse | 2

A function name must be followed by parentheses containing its parameter(s). For functions with two parameters, the parameters are separated by a comma. Function parameters can themselves be arithmetic expressions. The sin, cos, and tan function parameters are expected to be in degrees. The return values of the asin, acos, atan, and atan2 functions are in degrees. For the most part, expressions are allowed to include operators and functions in any order. This makes it possible to do things like calculate a horizontal location based on some vertical attribute, if you really want to do that. But it also means Mup will not stop you from creating an expression that may not make any logical sense. Mup will do its best to try to do whatever you say, even if that wasn't what you meant.

A common use for an expression more complicated than just a simple tag reference and offset would be to place something in the middle of a measure. You could set locations tags on the bars at either end of the measure, and then use the average to get the midpoint of the measure.

    1: 2g;e;
    // Note that be able to set a tag on the left of the very first measure,
    // we could make an invisible bar, just to set a tag on it. But here,
    // we can use the actual bar line at the left of the measure of interest.
    bar =_firstbar

    1: c;d;e;f;
    bar =_secondbar

    // Print a centered string at the average of the X values of
    // the bars on either side of the measure,
    // 6 stepsizes above the middle of the top staff of the score.
    center ((_firstbar.x + _secondbar.x) / 2, _firstbar.y + 6) "mid measure";

A much more complicated example is presented later, in the section on macros, demonstrating use of the trigonometric functions.

<-- previous page Table of Contents Index next page -->