<-- previous page Table of Contents Index next page -->
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 lowercase 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 notehead. However, on tags associated with a chord, the x is at the center line of noteheads 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 reused. The value of a tag will always be its most recent definition.
There are also several "pre-defined" tags. They are:
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.
The _score built-in tag refers to the current or most recent score. _score.x will be at the position of the left edge of the staffs. _score.y will be at the middle line of the top visible staff. _score.w will be the left margin. _score.e will be the right margin. _score.n will be the farthest upward that anything associated with the score protrudes. _score.s will be the farthest downward that anything associated with the score protrudes.
There are also built-in tags for each staff in the current or most recent score. Since there is one per staff, there is a special notation: _staff followed by a dot and the staff number. Only staff numbers that exist (i.e., are between 1 and the value of the staffs parameter) and that are currently visible can be referenced. _staff.2.x will be the place on staff 2 between where the clef and time signature end and the first measure of the score begins. (Actually all staffs have the same x value.) _staff.5.y will be the middle line of the staff 5. _staff.7.w will the left edge of the staff label if it has a staff label; otherwise the left edge of the staff (the same as _score.x). _staff.10.e will be the right margin of staff 10 (or really any staff, since they will all be the same). _staff.4.n will be the farthest upward protrusion of anything associated with staff 4. _staff.15.s will be the farthest downward protrusion of anything associated with staff 15.
Location tags can be referenced by a number of commands, including those
for
printing text,
or
drawing lines or curves,
or in
user-defined PostScript code.
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"
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)
(k.w - 1.3, m.n - 2)
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)
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. If that adjustment is not desired, make sure the location specified is slightly before the bar line.
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)
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
location 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.