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

Printing commands

There are several commands for printing text. There are four commands that have similar formats, differing only in how they justify text.

print location "text"
left location "text"
right location "text"
center location "text"

The location is optional. If the location is omitted, the "print" command will cause the text to be printed beginning at the current horizontal and vertical location. The other commands will cause the text to be placed vertically at the current vertical position, but left justified, right justified, or centered within the current margins of the page.

The location can be specified using the special keyword of "nl" which means "next line." This moves the current location to the beginning of the following line before placing the text. In other words, the current vertical position is moved downward by the height of the current text point size (or by as much as necessary if the string is taller than that). Then the text is printed on that line with the given justification style.

The other way to specify a location is by using coordinates. The justification then takes place relative to the referenced location. For example, consider the following "right" command containing a reference to an absolute location:

right (25, 4) "something"

The y location given is 4. Since this is an absolute location with no location tags being referenced, this means the vertical position will be 4 stepsizes from the bottom of the page. The x location given is 25. Again, this is an absolute location, so the current horizontal position will be 25 stepsizes from the left edge of the page. Since right justification is indicated, the word "something" will be placed such that the right edge of the final "g" will be 25 stepsizes from the left edge of the page. If "center" had been specified, the middle of the word "something" would be at the 25 stepsize point.

Here are some other examples:

print "Author unknown"
center nl "subtitle"
left (h.x - 1.5, h.n + 2.3) "Ad lib"
right (_fine.e + time 3, _note.n + 5) "Duet"

Another type of print command is "title." The full format of this command is:

title fontfamily font size  "text1"  "text2"  "text3"

However, only the word "title" and one quoted text string are required. The fontfamily, if specified, has one of the values valid for the "fontfamily" parameter (avantgarde, bookman, courier, helvetica, newcentury, palatino, or times). The default is the value of the "fontfamily" parameter. The font, if specified, has one of the values valid for the "font" parameter (rom, bold, ital, or boldital). If no font is specified the default is the value of the "font" parameter. The optional size is a point size within parentheses. If not specified, the default is the value of the "size" parameter.

In all cases, the location will be like that obtained via the "nl" location to a print command. In other words, the title text string(s) will be printed on the line below the location that was current when the title command was encountered. If there is only one string given, it will be centered between the margins. If two strings are given, both will be printed on the same line, but the first will be left justified and the second will be right justified. If three strings are given, they will all be printed on the same line, with the first left justified, the second centered, and the last right justified.

Some samples:

title bold (12) "Sonata 12"
title (18) "Song Without Words"
title ital (12) "Text: John Doe" "Tune: Jane Doe"
title "Suite in C" "Trumpet I" "Waltz"
title    ""    "A. Composer"

The final command for printing text is the "paragraph" command. This is used when you have a long section of text, and you would like it to automatically wrap around onto as many lines as necessary. You can specify whether you want the right margin to be "justified" or "ragged." If you don't specify, the type of the previous paragraph is used. The default for the very first paragraph is to be justified. By default, the values of the fontfamily, font, and size parameters are used to determine the text style, but any or all of those parameters can be overridden on the paragraph command. The complete syntax is:
justify_type paragraph fontfamily font (size) "string"
Only the keyword "paragraph" and the string are required. Here are some example paragraphs:

paragraph "This is an example of a paragraph. Since no justification
type was specified, and this is the very first paragraph, the default
(justified) is used. A paragraph will wrap around
to as many lines as needed.
An explicit newline is given at the end of this paragraph,
to force a blank line between it and the following paragraph.\n"

ragged paragraph avantgarde ital (15) "This paragraph
is ragged rather than flush right. It is in a different font and size.
Ragged paragraphs are split onto multiple lines if necessary,
but they are not spread out to make lines go all the way to
the right margin."

justified paragraph (14) "     Here is another paragraph.
This one is justified.
Only the size was specified for this paragraph; the font was not,
so the current default will be used.
Some spaces are included at the beginning of the paragraph text,
to create an indented first line for the paragraph."

paragraph "Here is the final paragraph.
Since no justification type was given,
that of the previous paragraph (justified in this case) was used.
A paragraph may be used for many things,
such as describing how you want a piece to be performed,
or a biography of the composer."

Picture of Mup output

Sometimes you may want to mix blocks of text with music. This can be done by specifying a "block" context. The block context will typically contain one or more "paragraph" commands, although any of the printing commands (paragraph, print, left, center, right, or title) can be used. The block can also contain changes in certain parameters, namely font, size, and fontfamily, which will affect the appearance of the following text. A block can also contain "newscore" or "newpage" commands. Using "newscore" will cause vertical space to be added, as would be used to separate scores. The amount of space is affected by the scoresep and scorepad parameters. Using "newpage" will cause a new page to be started. If a newscore or newpage includes a "leftmargin" specification, that will alter the left margin on the block text that follows. A "rightmargin" specification will alter the right margin of the block text that precedes it.

Here is an example of a block.

block
title bold "Notation in Simple and Compound Meters"
title ""
paragraph "It is common for a person familiar
with mathematics but not with music to assume
that 3/4 and 6/8 time are equivalent,
but that is not the case.
In 3/4 time (which is known as simple triple meter),
a measure containing 3 quarter notes
would be notated like this:"
score time=3/4
music
1: c;;;
bar hidechanges
block
paragraph "whereas in 6/8 time
(which is compound duple meter),
a measure with 3 quarter notes should be notated thus:"
score time=6/8
music
1: 4c;8~;;4;
bar

Picture of Mup output

The printing commands may occur in the header, footer, header2, footer2, top, bottom, top2, bottom2, block, and music contexts. After each printing command, the current location is set to the right edge of the last character printed horizontally and at the baseline of the current line vertically.

Including raw PostScript

There is another command that looks a lot like the printing commands, but gives you a way to insert raw PostScript into the Mup output. This might be used, for example, to include a picture or logo along with your music. The syntax is

postscript optional_location optional_exports "raw PostScript"

As with the other print commands, if the location is omitted, the current location is used.

Instead of specifying an (x, y) coordinate location, you can declare various PostScript "hooks" that will be called at specific times:

afterprolog
The PostScript code you specify will be placed in the generated Mup output right after the %EndProlog, and before the first page. The current location will be the upper left corner of the page. A typical usage might be to set up some global things that you would then use later in other hooks. Or it could be used to override things defined in the Mup prolog.
beforetrailer
The PostScript code you specify will be placed in the generated Mup output right after the final page, and before the %Trailer. The current location will be the lower right corner of the page. One possible use might be to write out some data gathered to some other file.
atpagebegin
The PostScript code you specify will be placed in the generated Mup output on every page, before anything is written to the page. The current location will be the upper left corner of the page. Some possible uses would be to paint the page some background color or add a fancy border. Or it could be used to add a red "Do not copy" watermark, where the music output would still be completely readable, since it would get drawn on top of the mark.
atpageend
The PostScript code you specify will be placed in the generated Mup output on every page, after everything else has been written to the page. The current location will be the lower right corner of the page. An example of a possible use would be to write "SAMPLE" in huge letters across each page. to leave enough music readable that a potential user can get an idea of what the music is like, but overwrite enough that it isn't really usable, to encourage paying for a copy without the mark.
atscorebegin
The PostScript code you specify will be placed in the generated Mup output just before the output for each score. The current location will be the upper left corner of the score. A possible usage would be to put a different color background behind each score, so they would really stand out even on a very crowded page. Another would be to put yellow highlighting behind a particular staff on each score.
atscoreend
The PostScript code you specify will be placed in the generated Mup output just after the output for each score. The current location will be the lower right corner of the score. One possible use would be to "white-out" something Mup printed that you don't like, but have no other way to prevent. With enough work, you could probably even create an ossia.

It should be noted that since a postscript command can contain arbitrary PostScript code that is merely passed through by Mup, any tools that try to transform Mup input to some other music notation format (e.g. Music XML) will most likely be unable to understand any of that PostScript code, and any information it in will almost certainly be completely lost during the transformation. So while it is provided as an "escape hatch" to allow you to do things Mup does not support natively, its usage is discouraged, unless you really need to do something that Mup does not support directly, and if you are willing to accept the fact that doing so will compromise portability.

The optional_exports let you specify a list of Mup location tags whose values you want to pass to your PostScript code. If you list a tag by itself, all six values (x, y, n, s, e, w) are passed to Postscript, or you can list just a specific direction:

  postscript atscorebegin with _score, _mytag.y, "...PostScript... "

As a special case, you can specify _staff, which will pass all six values for all visible staffs. The PostScript name will be the Mup name with Mup prepended to it. So _tag.x in the Mup input will become Mup_tag.x in the PostScript output. Often it is useful to use a more generic name in your Postscript code, and then pass the values from different tags to it at different times. You can do this by specifying an alias tag.
  postscript atspagebegin with _value = _staff.2 "...PostScript... "

In that example, _value will be an alias, and the PostScript name will be Mup_value but its value will be that of _staff.2. So suppose the value of _staff.2.x is 3.8. If you say
	with _staff.2.x
the output would be
	/Mup_staff.2.x 3.8 def
but if you say
	with _value.x = _staff.2.x
the output would be
	/Mup_value.x 3.8 def
and you can later use the exact same PostScript code (that uses Mup_value.x), but pass it the value from some other tag, like _staff.5.x or your own tag. Note that you don't have to use the same direction for both, so you could say
	with _value.x = _another_tag.w

The string containing raw Postscript is copied directly to the Mup output. You can use the usual \" to embed a double quote in the string, but otherwise the string is copied exactly as it is, enclosed inside a PostScript save/restore. After the restore, the current location is reset back to where it was originally.

Alternately, you can use the keyword "file" and then give a file name as the string. The contents of the file are copied to the output, and no escaping of double quotes is necessary.

Since the PostScript code is copied without any interpretation, Mup does not reserve any space on the page for it, and it is your responsibility to provide valid PostScript. The PostScript language is beyond the scope of this User's Guide; consult a book on PostScript if you need more information.

As a simple example, you might include an Encapsulated PostScript file near the lower left corner of the current page using

postscript "50 50 translate (file.eps) run"

Or you could print a message in red italics near the bottom of the page like this:

postscript (70, 20) "
              1 0 0 setrgbcolor
              /NewCenturySchlbk-Italic findfont
              16 scalefont setfont
              (Photocopying prohibited) show
              "

Next we show an example of a hook, that allows you to do the equivalent of a yellow highlighting pen on a particular staff.

score
	staffs=2
music

 define SOPRANO 1 @
 define ALTO 2 @

ifdef HIGHLIGHT
// If HIGHLIGHT is set to a staff number,
// highlight that staff by drawing a yellow boxbehind it.
postscript atscorebegin with _box = _staff.HIGHLIGHT  "
	newpath
	Mup_box.w Mup_box.n moveto
	Mup_box.e Mup_box.n lineto
	Mup_box.e Mup_box.s lineto
	Mup_box.w Mup_box.s lineto
	closepath 0.9 0.9 0.0 setrgbcolor fill stroke"
endif

SOPRANO: g;8c+;;4;;
ALTO: e;8g;;4a;e;
lyrics below SOPRANO,ALTO: "This is a sam-ple";
bar

newscore

SOPRANO: e+;d+;b;c+;
ALTO: g;b;g;e;
lyrics below SOPRANO,ALTO: "of high-light-ing.";
bar

Picture of Mup output
If you invoke Mup with -DHIGHLIGHT=SOPRANO, the top score will be highlighted. If you invoke with -DHIGHLIGHT=ALTO (as shown), the second will be highlighted. Otherwise nothing will be.


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