[mup] / mup / docs / uguide / basics.html

<HTML>
<HEAD><TITLE>
"Mup Basics"
</TITLE></HEAD>
<BODY>
<P>
&nbsp;&nbsp;&nbsp;<A HREF="intro.html">&lt;-- previous page</A>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="running.html">next page --&gt;</A>
</P>
          
<H1>
MUP BASICS
</H1>
<P>
This section introduces the Mup language, giving some simple examples to
give you the flavor of a Mup input file.
Subsequent sections will go into greater detail.
</P>
<H2>
Notes and chords
</H2>
<P>
Music is described one measure at a time. Each note is specified by its pitch
value, &quot;a&quot; to &quot;g.&quot; As an example, the first measure of &quot;Three Blind
Mice&quot; can be described like this:
<BR><PRE>
1:    4e; 4d; 2c;
</PRE><BR>
<IMG SRC="mugex2.gif" ALT="Picture of Mup output"><BR>
The &quot;1:&quot; at the beginning of the line tells Mup that we are describing
the notes on staff number 1. In this very simple example, we only have one
staff, but later we'll do songs with more than one.
Each staff of each measure is normally put on a separate line.
</P>
<P>
The first three notes of &quot;Three Blind Mice&quot; are E, D, and C. For Mup
input, these pitches are given in lower case to avoid having to use the shift
key. No octave information was specified in this simple example, so Mup
would use its default, which in this case would be the octave beginning
with middle C.
</P>
<P>
The first two notes are quarter notes, and the last note is a half
note. Time values of notes are given as shown in the example. A quarter
note is marked by a 4, a half note by 2, a sixteenth note by a 16, etc.
</P>
<P>
A semicolon is used to separate chords. In this simple example, each chord
has only a single note in it, but it is possible to have lots of notes in one
<A HREF="chordinp.html">chord.</A>
</P>
<P>
At the end of each measure, we have to tell Mup what kind of
<A HREF="bars.html">bar line</A>
to draw. The standard bar line is just called &quot;bar.&quot; So a complete
description of the first measure would be:
<BR><PRE>
1:    4e; 4d; 2c;
bar
</PRE><BR>
</P>
<P>
To save typing, Mup allows a lot of shortcuts. One such shortcut is that
it assumes that unless you tell it otherwise, each note in the measure is
like the note before. You can leave out the second 4, because if you
don't specify a time value, Mup will assume the note is the same length
as the previous note.
</P>
<P>
The same sort of idea works with pitches. The third measure of &quot;Three Blind
Mice&quot; could be stated like this:
<BR><PRE>
1: 4g;8f;;2e;
bar
</PRE><BR>
<IMG SRC="mugex3.gif" ALT="Picture of Mup output"><BR>
The third note has no information given at all in this example--there is
only a semicolon. In this case, Mup will get both pitch and time value from
the previous note, so the actual third note in this measure would be an
eighth note with pitch F.
</P>
<P>
You may have noticed that this example doesn't have spaces between chords.
There are only a few places where the Mup language requires you to put spaces.
However, you can always put some in other places to make things easier to read.
</P>
<H2>
Parameters
</H2>
<P>
Printed music contains a lot more than just notes and bar lines. Among other
things, each staff normally begins with a clef, key signature, and time
signature. Mup provides default values for these, which you can then
override if you want something different. In the examples so far, we didn't
override anything, so Mup would assume its default values, which are
treble clef, a key signature with no sharps or flats, and a time signature
of 4/4.
</P>
<P>
There is a long
<A HREF="param.html">list of "parameters" that can be set.</A>
Things like clef
and key signature are among them. Parameters can be changed with a line of the
form:
<BR><PRE>
<I>parameter_name</I>=<I>value</I>
</PRE><BR>
For example, suppose we have a song written in 6/8 time in the key of D major.
We can convey this information to Mup like this:
<BR><PRE>
score
  time=6/8
  key=2#

music
  1: 4d;8e;4f;8d;
  bar
</PRE><BR>
<IMG SRC="mugex4.gif" ALT="Picture of Mup output"><BR>
</P>
<P>
Note that in this example, the key was specified as two sharps.
You can also specify the key by name:
<BR><PRE>
  key = d major
</PRE><BR>
</P>
<P>
These parameters give a very different sort of information than the notes of
a measure, so they go in a separate section of the input file.
Each section of the file describes information for a specific
<A HREF="contexts.html">"context."</A>
Information about musical notes is given in &quot;music&quot; context,
while things that apply in general to the whole
score are given in &quot;score&quot; context.
Once you start a measure in music context, you have to complete that measure
before switching to another context, but otherwise you can pretty much
change from one context to another as necessary.
Each new context section is headed by its name (e.g.,
&quot;music&quot; or &quot;score&quot;).
At the beginning of input, music context is assumed.
</P>
<P>
Here is a more complicated example:
<BR><PRE>
score
	staffs=2
	key=3&amp;
	time=2/4

music
1: ceg;;
2: 2c;
bar
</PRE><BR>
<IMG SRC="mugex5.gif" ALT="Picture of Mup output"><BR>
This example starts by setting some parameters. First it states that this
piece of music should be printed with two staffs, instead of the default of
only one. Then it gives a key signature. Since there is no &quot;flat&quot; symbol
on a standard computer keyboard, Mup uses the &quot;&amp;&quot; symbol for flat.
The time signature is then set to 2/4.
</P>
<P>
Next we find the keyword &quot;music,&quot; which indicates the end of parameters
and the beginning of the music. Data is given for both staff 1 and staff 2.
Staff 1 has two chords in the measure. The first is a C minor triad (it's
minor since the key is three flats). No time value is specified for this
chord. Since it is the very first chord of the piece, Mup cannot use the
previous chord's time value, because there is no previous chord. 
In this case, Mup falls back to using the denominator (bottom number)
of the time signature,
so the chord is a quarter note. Incidentally, if Mup has to back up to
previous notes to deduce pitch and/or time values, it only goes back as far
as the beginning of the current measure. That means the default time value
for the first chord of every measure in this piece would be quarter note.
The second chord on staff 1 is the same as the first, since only a semicolon
is specified. 
</P>
<P>
Staff 2 has only a single chord, consisting of a half note with pitch C.
Mup checks to make sure the time values on each staff add up to the time
signature--no more or less--and will print an error message if they don't.
If you have something like a &quot;pickup&quot; measure, which doesn't add up to the
time signature, you can specify &quot;space&quot; rather than a chord,
to account for the rest of the time.
</P>
<P>
Some parameters can be set on a per-staff basis as well as for the entire
score. Mup also allows for
<A HREF="param.html#vscheme">up to three independent voices on each staff,</A>
and each voice can have parameters
set that apply to only that voice. To get the
value of a parameter, Mup always starts at the most specific place it could
be defined and works toward the most general. In other words, it will first
see if the parameter is set for the current voice. If not, it will see if
it is set for the current staff. If not, it will use the value set for the
entire score. Staff parameters are set in &quot;staff&quot; context, and voice parameters
are set in &quot;voice&quot; context.
As an example:
<BR><PRE>
score
	staffs=3
	key=1&amp;
staff 2
	key=2&amp;
	clef=bass
music
1: 2f;a;
2: 2c;f;
3: 1f;
bar
</PRE><BR>
<IMG SRC="mugex6.gif" ALT="Picture of Mup output"><BR>
Staff 2 will have two flats, whereas the other staffs will have one flat.
Staff 2 will use the bass clef, whereas the other staffs will use treble
clef (since that is the default when none is specified).
<A HREF="param.html">The complete list of Mup parameters</A>
includes
information about whether they can be set for an individual staff
or voice, or just for the score as a whole.
</P>
<H2>
Page headers and footers
</H2>
<P>
Mup allows you to specify a
<A HREF="headfoot.html">header and/or footer</A>
to put on the first page,
as well as a header and/or footer to use on subsequent pages. These can
include a page number that will be incremented automatically as pages are
printed. The headers and footers can be customized as you like, with
different fonts and sizes of text and items centered or left or right
justified. There is also a shortcut
<A HREF="prnttext.html">"title" command</A>
that can be used to create a canned format title. For example:
<BR><PRE>
title &quot;Three Blind Mice&quot;
</PRE><BR>
will create a centered title. You can also get left and right justified titles.
</P>
<H2>
Lyrics
</H2>
<P>
You can specify
<A HREF="lyrics.html">lyrics</A>
for as many verses as you like. They are specified
somewhat like notes. As an example:
<BR><PRE>
1: 4e;d;2c;
lyrics 1: 4;;2; &quot;Three blind mice,&quot;;
bar
</PRE><BR>
<IMG SRC="mugex7.gif" ALT="Picture of Mup output"><BR>
This example describes the lyrics to go with staff 1. There are three lyric
syllables, having time values of quarter note, quarter note, and half note.
The actual syllables are given inside the double quotes.
Incidentally, since in this example the time values for the lyrics
are the same as those of the notes, the time values don't actually need to
be specified; if no lyrics time values are given, Mup assumes they
match the note time values.
</P>
<H2>
Miscellaneous
</H2>
<P>
Mup provides a way to
<A HREF="textmark.html">print arbitrary text</A>
(like &quot;allegro&quot;) and
<A HREF="mussym.html">musical symbols</A>
(like a fermata). It can also print
<A HREF="phrase.html">phrase marks,</A>
<A HREF="pedal.html">piano pedal marks,</A>
etc. The placement of these items is specified in terms
of &quot;counts&quot; into the measure. For example:
<BR><PRE>
boldital below 1: 3 &quot;mf&quot;;
</PRE><BR>
<IMG SRC="mugex8.gif" ALT="Picture of Mup output"><BR>
tells Mup to print &quot;mf&quot; in bold-italics below staff 1, at count 3 of the
measure.
You can also print
<A HREF="chrdattr.html#withlist">marks associated with specific chords.</A>
All of these facilities are described in detail in following sections.
</P>
<H2>
Displaying, printing, and playing music
</H2>
<P>
Once you have an input file, you can run Mup on it to get the printed
version of the music. Entering:
<BR><PRE>
mup <I>myfile</I>
</PRE><BR>
from a command line prompt or selecting Run &gt; Display from Mupmate
will cause Mup to read <I>myfile</I>, which should contain text in the Mup
input language. If there are no errors in <I>myfile</I>, PostScript output
will be produced, which can be displayed on the screen or printed via
Mupmate or other programs. Mup can also produce
<A HREF="midi.html">MIDI output,</A>
which can then be played on your speakers.
</P>
<P>
If you are using Ghostscript, but without Mupmate,
two utility programs are included with Mup
for
<A HREF="utilpgms.html">displaying and printing music</A>
using Ghostscript.
These are described in more detail in the next section.
</P>
<HR><P>
&nbsp;&nbsp;&nbsp;<A HREF="intro.html">&lt;-- previous page</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="running.html">next page --&gt;</A>
</P>
</BODY></HTML>
Commit	Line	Data
69695f33 MW	1	<HTML>
	2	<HEAD><TITLE>
	3	"Mup Basics"
	4	</TITLE></HEAD>
	5	<BODY>
	6	<P>
	7	<A HREF="intro.html"><-- previous page</A>
	8
	9	<A HREF="index.html">Table of Contents</A>    <A HREF="running.html">next page --></A>
	10	</P>
	11
	12	<H1>
	13	MUP BASICS
	14	</H1>
	15	<P>
	16	This section introduces the Mup language, giving some simple examples to
	17	give you the flavor of a Mup input file.
	18	Subsequent sections will go into greater detail.
	19	</P>
	20	<H2>
	21	Notes and chords
	22	</H2>
	23	<P>
	24	Music is described one measure at a time. Each note is specified by its pitch
	25	value, "a" to "g." As an example, the first measure of "Three Blind
	26	Mice" can be described like this:
	27	<BR><PRE>
	28	1: 4e; 4d; 2c;
	29	</PRE><BR>
	30	<IMG SRC="mugex2.gif" ALT="Picture of Mup output"><BR>
	31	The "1:" at the beginning of the line tells Mup that we are describing
	32	the notes on staff number 1. In this very simple example, we only have one
	33	staff, but later we'll do songs with more than one.
	34	Each staff of each measure is normally put on a separate line.
	35	</P>
	36	<P>
	37	The first three notes of "Three Blind Mice" are E, D, and C. For Mup
	38	input, these pitches are given in lower case to avoid having to use the shift
	39	key. No octave information was specified in this simple example, so Mup
	40	would use its default, which in this case would be the octave beginning
	41	with middle C.
	42	</P>
	43	<P>
	44	The first two notes are quarter notes, and the last note is a half
	45	note. Time values of notes are given as shown in the example. A quarter
	46	note is marked by a 4, a half note by 2, a sixteenth note by a 16, etc.
	47	</P>
	48	<P>
	49	A semicolon is used to separate chords. In this simple example, each chord
	50	has only a single note in it, but it is possible to have lots of notes in one
	51	<A HREF="chordinp.html">chord.</A>
	52	</P>
	53	<P>
	54	At the end of each measure, we have to tell Mup what kind of
	55	<A HREF="bars.html">bar line</A>
	56	to draw. The standard bar line is just called "bar." So a complete
	57	description of the first measure would be:
	58	<BR><PRE>
	59	1: 4e; 4d; 2c;
	60	bar
	61	</PRE><BR>
	62	</P>
	63	<P>
	64	To save typing, Mup allows a lot of shortcuts. One such shortcut is that
65	it assumes that unless you tell it otherwise, each note in the measure is
66	like the note before. You can leave out the second 4, because if you
67	don't specify a time value, Mup will assume the note is the same length
68	as the previous note.
69	</P>
70	<P>
71	The same sort of idea works with pitches. The third measure of "Three Blind
72	Mice" could be stated like this:
73	<BR><PRE>
74	1: 4g;8f;;2e;
75	bar
76	</PRE><BR>
77	<IMG SRC="mugex3.gif" ALT="Picture of Mup output"><BR>
78	The third note has no information given at all in this example--there is
79	only a semicolon. In this case, Mup will get both pitch and time value from
80	the previous note, so the actual third note in this measure would be an
81	eighth note with pitch F.
82	</P>
83	<P>
84	You may have noticed that this example doesn't have spaces between chords.
85	There are only a few places where the Mup language requires you to put spaces.
86	However, you can always put some in other places to make things easier to read.
87	</P>
88	<H2>
89	Parameters
90	</H2>
91	<P>
92	Printed music contains a lot more than just notes and bar lines. Among other
93	things, each staff normally begins with a clef, key signature, and time
94	signature. Mup provides default values for these, which you can then
95	override if you want something different. In the examples so far, we didn't
96	override anything, so Mup would assume its default values, which are
97	treble clef, a key signature with no sharps or flats, and a time signature
98	of 4/4.
99	</P>
100	<P>
101	There is a long
102	<A HREF="param.html">list of "parameters" that can be set.</A>
103	Things like clef
104	and key signature are among them. Parameters can be changed with a line of the
105	form:
106	<BR><PRE>
107	<I>parameter_name</I>=<I>value</I>
108	</PRE><BR>
109	For example, suppose we have a song written in 6/8 time in the key of D major.
110	We can convey this information to Mup like this:
111	<BR><PRE>
112	score
113	time=6/8
114	key=2#
115
116	music
117	1: 4d;8e;4f;8d;
118	bar
119	</PRE><BR>
120	<IMG SRC="mugex4.gif" ALT="Picture of Mup output"><BR>
121	</P>
122	<P>
123	Note that in this example, the key was specified as two sharps.
124	You can also specify the key by name:
125	<BR><PRE>
126	key = d major
127	</PRE><BR>
128	</P>
129	<P>
130	These parameters give a very different sort of information than the notes of
131	a measure, so they go in a separate section of the input file.
132	Each section of the file describes information for a specific
133	<A HREF="contexts.html">"context."</A>
134	Information about musical notes is given in "music" context,
135	while things that apply in general to the whole
136	score are given in "score" context.
137	Once you start a measure in music context, you have to complete that measure
138	before switching to another context, but otherwise you can pretty much
139	change from one context to another as necessary.
140	Each new context section is headed by its name (e.g.,
141	"music" or "score").
142	At the beginning of input, music context is assumed.
143	</P>
144	<P>
145	Here is a more complicated example:
146	<BR><PRE>
147	score
148	staffs=2
149	key=3&
150	time=2/4
151
152	music
153	1: ceg;;
154	2: 2c;
155	bar
156	</PRE><BR>
157	<IMG SRC="mugex5.gif" ALT="Picture of Mup output"><BR>
158	This example starts by setting some parameters. First it states that this
159	piece of music should be printed with two staffs, instead of the default of
160	only one. Then it gives a key signature. Since there is no "flat" symbol
161	on a standard computer keyboard, Mup uses the "&" symbol for flat.
162	The time signature is then set to 2/4.
163	</P>
164	<P>
165	Next we find the keyword "music," which indicates the end of parameters
166	and the beginning of the music. Data is given for both staff 1 and staff 2.
167	Staff 1 has two chords in the measure. The first is a C minor triad (it's
168	minor since the key is three flats). No time value is specified for this
169	chord. Since it is the very first chord of the piece, Mup cannot use the
170	previous chord's time value, because there is no previous chord.
171	In this case, Mup falls back to using the denominator (bottom number)
172	of the time signature,
173	so the chord is a quarter note. Incidentally, if Mup has to back up to
174	previous notes to deduce pitch and/or time values, it only goes back as far
175	as the beginning of the current measure. That means the default time value
176	for the first chord of every measure in this piece would be quarter note.
177	The second chord on staff 1 is the same as the first, since only a semicolon
178	is specified.
179	</P>
180	<P>
181	Staff 2 has only a single chord, consisting of a half note with pitch C.
182	Mup checks to make sure the time values on each staff add up to the time
183	signature--no more or less--and will print an error message if they don't.
184	If you have something like a "pickup" measure, which doesn't add up to the
185	time signature, you can specify "space" rather than a chord,
186	to account for the rest of the time.
187	</P>
188	<P>
189	Some parameters can be set on a per-staff basis as well as for the entire
190	score. Mup also allows for
191	<A HREF="param.html#vscheme">up to three independent voices on each staff,</A>
192	and each voice can have parameters
193	set that apply to only that voice. To get the
194	value of a parameter, Mup always starts at the most specific place it could
195	be defined and works toward the most general. In other words, it will first
196	see if the parameter is set for the current voice. If not, it will see if
197	it is set for the current staff. If not, it will use the value set for the
198	entire score. Staff parameters are set in "staff" context, and voice parameters
199	are set in "voice" context.
200	As an example:
201	<BR><PRE>
202	score
203	staffs=3
204	key=1&
205	staff 2
206	key=2&
207	clef=bass
208	music
209	1: 2f;a;
210	2: 2c;f;
211	3: 1f;
212	bar
213	</PRE><BR>
214	<IMG SRC="mugex6.gif" ALT="Picture of Mup output"><BR>
215	Staff 2 will have two flats, whereas the other staffs will have one flat.
216	Staff 2 will use the bass clef, whereas the other staffs will use treble
217	clef (since that is the default when none is specified).
218	<A HREF="param.html">The complete list of Mup parameters</A>
219	includes
220	information about whether they can be set for an individual staff
221	or voice, or just for the score as a whole.
222	</P>
223	<H2>
224	Page headers and footers
225	</H2>
226	<P>
227	Mup allows you to specify a
228	<A HREF="headfoot.html">header and/or footer</A>
229	to put on the first page,
230	as well as a header and/or footer to use on subsequent pages. These can
231	include a page number that will be incremented automatically as pages are
232	printed. The headers and footers can be customized as you like, with
233	different fonts and sizes of text and items centered or left or right
234	justified. There is also a shortcut
235	<A HREF="prnttext.html">"title" command</A>
236	that can be used to create a canned format title. For example:
237	<BR><PRE>
238	title "Three Blind Mice"
239	</PRE><BR>
240	will create a centered title. You can also get left and right justified titles.
241	</P>
242	<H2>
243	Lyrics
244	</H2>
245	<P>
246	You can specify
247	<A HREF="lyrics.html">lyrics</A>
248	for as many verses as you like. They are specified
249	somewhat like notes. As an example:
250	<BR><PRE>
251	1: 4e;d;2c;
252	lyrics 1: 4;;2; "Three blind mice,";
253	bar
254	</PRE><BR>
255	<IMG SRC="mugex7.gif" ALT="Picture of Mup output"><BR>
256	This example describes the lyrics to go with staff 1. There are three lyric
257	syllables, having time values of quarter note, quarter note, and half note.
258	The actual syllables are given inside the double quotes.
259	Incidentally, since in this example the time values for the lyrics
260	are the same as those of the notes, the time values don't actually need to
261	be specified; if no lyrics time values are given, Mup assumes they
262	match the note time values.
263	</P>
264	<H2>
265	Miscellaneous
266	</H2>
267	<P>
268	Mup provides a way to
269	<A HREF="textmark.html">print arbitrary text</A>
270	(like "allegro") and
271	<A HREF="mussym.html">musical symbols</A>
272	(like a fermata). It can also print
273	<A HREF="phrase.html">phrase marks,</A>
274	<A HREF="pedal.html">piano pedal marks,</A>
275	etc. The placement of these items is specified in terms
276	of "counts" into the measure. For example:
277	<BR><PRE>
278	boldital below 1: 3 "mf";
279	</PRE><BR>
280	<IMG SRC="mugex8.gif" ALT="Picture of Mup output"><BR>
281	tells Mup to print "mf" in bold-italics below staff 1, at count 3 of the
282	measure.
283	You can also print
284	<A HREF="chrdattr.html#withlist">marks associated with specific chords.</A>
285	All of these facilities are described in detail in following sections.
286	</P>
287	<H2>
288	Displaying, printing, and playing music
289	</H2>
290	<P>
291	Once you have an input file, you can run Mup on it to get the printed
292	version of the music. Entering:
293	<BR><PRE>
294	mup <I>myfile</I>
295	</PRE><BR>
296	from a command line prompt or selecting Run > Display from Mupmate
297	will cause Mup to read <I>myfile</I>, which should contain text in the Mup
298	input language. If there are no errors in <I>myfile</I>, PostScript output
299	will be produced, which can be displayed on the screen or printed via
300	Mupmate or other programs. Mup can also produce
301	<A HREF="midi.html">MIDI output,</A>
302	which can then be played on your speakers.
303	</P>
304	<P>
305	If you are using Ghostscript, but without Mupmate,
306	two utility programs are included with Mup
307	for
308	<A HREF="utilpgms.html">displaying and printing music</A>
309	using Ghostscript.
310	These are described in more detail in the next section.
311	</P>
312	<HR><P>
313	<A HREF="intro.html"><-- previous page</A>     <A HREF="index.html">Table of Contents</A>    <A HREF="running.html">next page --></A>
314	</P>
315	</BODY></HTML>