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

Headers and footers

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 can have different versions for left and right pages, by following their name with a modifier of "leftpage" or "rightpage." So, for example, you can have both a "top leftpage" and a "top rightpage." These will override any corresponding version without a page side modifier. So if you also defined a plain "top" in addition to ones for leftpage and rightpage, it wouldn't actually ever get used. If, on the other hand, you defined only a "top leftpage" and a plain "top," then the plain top would get used for right-hand pages, and if you only define "top rightpage," and nothing for the other two, nothing would be used on left-hand pages. Pages will always alternate between left and right, but you can control which to start with, using the firstpage parameter.

All of these contexts are optional. Each of the three variations (leftpage, rightpage, and unmodified) of each outer context (header, footer, header2, footer2) 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, which will then be 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"

For this simple example, it would work just as well to use "header" instead of "top," so you can use either one, although top is slightly more flexible. Later we'll see some examples where you might use both header and top in the same file, for different kinds of titles.

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"

Again, in this simple example, you could use "header" and "footer" rather than "top" and "bottom."

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 - \%"

The \% is a special marker that will get replaced on each page with the current page number. While it can be used in any text string, it is probably only likely to be useful in these header and footer kinds of contexts. Another special marker is \#, which will be replaced by the page number of the final page. This could be useful for doing something like "page \% of \#."

As a variation, perhaps you'd prefer the information at the bottom of the page. 

bottom2
   title "This is the title"  "Page \%"

In this variation, two separate text strings are specified, so the first string will be left justified and the second will be right justified.

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 "\%"

But suppose that in addition, you want each song to have its title on its first page in big print, and on subsequent pages in regular size print. To get this, at the beginning of each song, you could use top and top2: 
top
   title (18) "This is the Song Title"
top2
   title "This is the Song Title"

Now suppose you'd prefer to have the page numbers at the left margin of left-hand pages and at the right margin of right-hand pages. Instead of the single unmodified footer2 shown above, you would make two: 

footer2 leftpage
  title "page \%"  ""
footer2 rightpage
  title ""  "page \%"

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. If 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.

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