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

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:

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

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.

Adding "mirrored" at the beginning only has effect when there are at least two strings provided and the output is going onto a left page, in which case the first and last strings are interchanged.

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"
mirrored title "at inner margin" "at outer margin"

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

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

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"

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 in it 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... "

  postscript atpagebegin with _value = _staff.2 "...PostScript... "

	with _staff.2.x

	/Mup_staff.2.x 3.8 def

	with _value.x = _staff.2.x

	/Mup_value.x 3.8 def

	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 verbatim, so it is not necessary to use backslashes before double quotes to preserve them.

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 box behind 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

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