--- /dev/null
+<HTML>
+<HEAD><TITLE>
+Location Tags
+</TITLE></HEAD>
+<BODY>
+<P>
+ <A HREF="roll.html"><-- previous page</A>
+
+ <A HREF="index.html">Table of Contents</A> <A HREF="prnttext.html">next page --></A>
+</P>
+
+<H2>
+Location tags
+</H2>
+<P>
+A location tag is associated with a
+<A HREF="noteattr.html#ntag">note,</A>
+<A HREF="chrdattr.html#ctag">chord,</A>
+or
+<A HREF="bars.html#btag">barline.</A>
+It can then be referenced in order to place a second object, like a comment
+or dotted line, relative to the first object.
+</P>
+<P>
+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:
+<BR><PRE>
+c.n // north of tag c
+_xyz.e // east of tag _xyz
+x.x // x coordinate of tag x
+</PRE><BR>
+</P>
+<P>
+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.
+</P>
+<P>
+Tag names can be re-used. The value of a tag will always be its most
+recent definition.
+</P>
+<P>
+There are also several "pre-defined" tags. They are:
+<DL>
+<DT>
+_page
+<DD>
+the entire page
+<DT>
+_win
+<DD>
+the available part of the page
+<DT>
+_cur
+<DD>
+the current location
+</DL>
+</P>
+<P>
+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.
+</P>
+<P>
+<A NAME="wintag">The _win tag</A>
+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.
+</P>
+<P>
+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.
+</P>
+<P>
+Location tags can be referenced by a number of commands, including those
+for
+<A HREF="prnttext.html">printing text,</A>
+or
+<A HREF="linecurv.html">drawing lines or curves.</A>
+In the simplest case, two
+tag references are given in parentheses. The first tag
+must 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:
+<BR><PRE>
+(g.x, g.y) // x and y of tag "g"
+(_tag.w, _item.n) // west of tag "_tag" and
+ // north of tag "_item"
+</PRE><BR>
+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.
+</P>
+<P>
+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.
+<BR><PRE>
+(g.x + 4.5, g.y + 4.5)
+</PRE><BR>
+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:
+<BR><PRE>
+(k.w - 1.3, m.n - 2)
+</PRE><BR>
+refers to a point 1.3 stepsizes to the left of the
+west edge of k and 2 stepsizes below the top of m.
+</P>
+<P>
+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:
+<BR><PRE>
+(q.x + time 1, q.y + 2)
+</PRE><BR>
+If the
+<A HREF="param.html#time">time signature</A>
+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.
+</P>
+<P>
+In the case of a
+<A HREF="bars.html#btag">tag associated with a bar line,</A>
+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.
+</P>
+<P>
+The mapping of time to distance is done based only on the note, rest, or bar
+line associated with the tag. For example, if the 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.
+</P>
+<P>
+The various kinds of offsets can be combined.
+<BR><PRE>
+( _pp + 1.2 - time 3.5, _zz + 2)
+</PRE><BR>
+</P>
+<P>
+At least one of the three possible items--tag, stepsize offset, or
+time offset--must be specified for each direction. Only one
+tag is allowed for each direction. If no tag is specified, the reference
+becomes an absolute reference, giving an exact page location. For example:
+<BR><PRE>
+(10, 20)
+</PRE><BR>
+is 10 stepsizes from the left edge and 20 stepsizes
+above the bottom of the page.
+Time offsets are not allowed on absolute references, and must follow the tag
+reference.
+</P>
+<P>
+It is possible to specify multiple offsets of the same type, although
+this is rarely, if ever, useful. Thus the following are equivalent:
+<BR><PRE>
+( f.x + 1 - 0.5 + time 1 - time 0.5, f.s + .3 - .1)
+( f.x + 0.5 + time 0.5, f.s + .2)
+</PRE><BR>
+</P>
+<HR><P>
+ <A HREF="roll.html"><-- previous page</A> <A HREF="index.html">Table of Contents</A> <A HREF="prnttext.html">next page --></A>
+</P>
+</BODY></HTML>
~mdw / mup / blobdiff