X-Git-Url: https://git.distorted.org.uk/~mdw/mup/blobdiff_plain/cdb3c0882392596f814cf939cbfbd38adc6f2bfe..ddf6330b56bcfb657e0186b24b9b1422c51d3424:/mup/docs/uguide/tags.html diff --git a/mup/docs/uguide/tags.html b/mup/docs/uguide/tags.html new file mode 100644 index 0000000..0a52157 --- /dev/null +++ b/mup/docs/uguide/tags.html @@ -0,0 +1,224 @@ + +
+ <-- previous page + + Table of Contents next page --> +
+ ++A location tag is associated with a +note, +chord, +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. +
++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: +
+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
+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:
+
+(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 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. +
+
+The various kinds of offsets can be combined.
+
+( _pp + 1.2 - time 3.5, _zz + 2) +
+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:
+
+(10, 20) +
+It is possible to specify multiple offsets of the same type, although
+this is rarely, if ever, useful. Thus the following are equivalent:
+
+( f.x + 1 - 0.5 + time 1 - time 0.5, f.s + .3 - .1) +( f.x + 0.5 + time 0.5, f.s + .2) +