X-Git-Url: https://git.distorted.org.uk/~mdw/mup/blobdiff_plain/cdb3c0882392596f814cf939cbfbd38adc6f2bfe..ddf6330b56bcfb657e0186b24b9b1422c51d3424:/mup/docs/uguide/headfoot.html diff --git a/mup/docs/uguide/headfoot.html b/mup/docs/uguide/headfoot.html new file mode 100644 index 0000000..697a5f5 --- /dev/null +++ b/mup/docs/uguide/headfoot.html @@ -0,0 +1,199 @@ + +
+ <-- previous page + + Table of Contents next page --> +
+ ++Mup provides ways to put headers and footers on pages of output. +Often you may want a certain kind of header and footer on the first +page, but a different kind on any subsequent pages, so Mup makes it +easy to do that. Mup also offers two different "layers" of headers and +footers. These layers may be particularly useful if you have a single Mup +file that contains multiple songs, or multiple movements of a song. +In that case, there may be certain things that you want printed in +headers and footers throughout, +like the current page number and the name of the entire collection, +but other things that you want to have change with each new song or +movement. +
++The "outer" layer is specified by four contexts: header, footer, header2, +and footer2. The "inner" layer is specified by four contexts: +top, bottom, top2, and bottom2. +All of these contexts are optional. +The outer contexts can only be specified once per file. +The inner contexts can be specified more than once per file, and +each time a set of them occurs, a new page is started. +On output pages, all of these contexts are placed horizontally +between the left and right margins, and vertically the +elements appear in the following order: + (topmargin) +header +top + (one or more scores of music or blocks of text) +bottom +footer + (bottommargin) +
++Which version is used--the one with or without the "2" suffix--depends +on which page is being printed. The items in header and footer +appear on only the very first page, +while those in header2 and footer2 appear on all subsequent pages. +Somewhat similarly, the items in top and bottom will appear on the page +that is started when they are encountered in the input, +while top2 and bottom2 will then be used on all subsequent pages. +However, you can specify a new top and/or bottom later, +that will then to used for one page, and you can specify +a new top2 and/or bottom2 later which will replace the previous top2/bottom2. +Note, however, that if you change top2 but not top, +that new top2 is used immediately on the new page, +whereas if you change both, the new top applies +to the immediately following new page, +and the new top2 isn't used until the following page. Subsequent pages +will use top2 in either case. +
+
+Some examples may help.
+First a simple case: suppose you have a single song, and you'd like a title
+at the top of the first page. This is straightforward:
+
+top + title "Here is the Title" +
+Now suppose you'd like to make the title bigger and bolder, and would like
+to add a subtitle and composer information, as well as add a copyright
+notice to the bottom of the page.
+
+top + title bold (18) "Here is the Title" + title ital (14) "Here is a subtitle" + title "Lyrics: Ann Author" "Composer: Me" +bottom + title "\(copyright) Copyright 2003 by Ann Author and Me" +
+Now suppose the song is long enough to take several pages,
+and you would like to repeat the title along with the page number on
+all pages after the first. To accomplish this, you could add:
+
+top2 + title "Here is the Title - \%" +
+As a variation, perhaps you'd prefer the information at the bottom of
+the page.
+
+bottom2 + title "This is the title" "Page \%" +
+Note that if you give a top2 or bottom2, +but it turns out there aren't any additional pages, +they would never actually get used. +But it wouldn't hurt to have set them. +
+
+Now let's consider a more complicated example, using both outer and inner
+contexts. Suppose you are publishing a book of songs,
+entitled "My Favorite Songs," and you want to put that title at the top
+of every page throughout the book, and you want a page number at the bottom
+of each page except the first.
+You could get that much using:
+
+header + title "My Favorite Songs" +header2 + title "My Favorite Songs" +footer2 + title "\%" +
+top + title (18) "This is the Song Title" +top2 + title "This is the Song Title" +
+A composition with multiple movements can be handled similarly, +by giving header, footer, header2, and footer2 (or any subset thereof) +for the composition as a whole, +and then giving new top, bottom, top2, and bottom2 definition (or any subset) +at the beginning of each new movement. +
++These contexts are conceptually in a separate coordinate space, +which will be overlaid on each page coordinate space. +When in these contexts, +the _win special tag +applies to +the header or footer window rather than the space between the header and +footer as it does in the music context. +
++Since headers or footers will expand as necessary, the +value of _win.s and _win.y +may be changed by any of the statements in the context. At any given +time, they refer to the boundaries as defined by what has been printed +so far. Thus, if the first line of a header contains an 18 point title, +after that, _win.s would be 18 points below _win.n. +It the header then contained a 12 point title, after that it +would be 31 points below _win.n (12 points for the title string, plus 1 point +of padding that is added between lines printed). +
++In addition to the "title" commands used in the examples above, +you can also use +the "print," "left," "right," or "center" commands. +In most +cases you will want to use "nl" for the location on those commands +to place things. If you don't specify a location for the first of these +commands in a header or footer, Mup will start at the left margin, just far +enough down from the top to accommodate the text string to be printed. +These contexts can also contain settings of the +font, +fontfamily, +and +size +parameters. +These parameter values will be used until the end of the context or until +set again to some other value. +
+