release: 1.1.4

[lilypond.git] / Documentation / tex / tutorial.yo

COMMENT(-*-text-*-)

redef(var)(1)(whenlatex(latexcommand({\normalfont\scshape )ARG1+latexcommand(}))\
    whenhtml(sc(ARG1)))

COMMENT( This document contains Mudela fragments.  You need at least
Yodl-1.30.18 to convert this to tex or html.

TODO

need to rethink paper size stuff?

pipethrough(date) sucks.

paragraphs have too much space.

in stead <-> instead
)

COMMENT(
        Mainly written by Han-Wen Nienhuys, 

        with help of (among others)

        * Jan Nieuwenhuizen

        * Lambert Meertens,

        * Adrian Mariano

        * Mats Bengtsson

)

htmlbodyopt(bgcolor)(white)
htmlcommand(<font color=black>)

latexlayoutcmds(
    \topmargin -0.25in  
    \textheight 53\baselineskip
    \advance\textheight by \topskip
    \marginparwidth 1 in        %   Width of marginal notes.
    \oddsidemargin 0.25 in      %   Note that \oddsidemargin = \evensidemargin
    \evensidemargin 0.25 in
    \marginparwidth 0.75 in
    \textwidth 5.875 in % Width of text line.
    \input mudela-book
)

whenlatex(notableofcontents())
whentexinfo(notableofcontents())

article(Mudela, the Music-Definition Language)
      (Han-Wen Nienhuys and Jan Nieuwenhuizen)
      (nop()PIPETHROUGH(date "+%B %d, %Y")()()nop())


latexcommand(\def\interexample{})
latexcommand(\def\preexample{\par})
latexcommand(\def\postexample{\par\medskip})
latexcommand(\def\file#1{{code(#1)}})

whenhtml(
includefile(html-disclaimer.yo-urg)
)


sect(Introduction)
label(tutorial:introduction)
latexcommand(\parindent2pc)
  
If you are reading this, you probably are interested in printing
music.  LilyPond is a program that can print music from a
specification that you, the user, supply.  Using LilyPond may be a bit
quaint in the beginning, because you have to give that specification
using a em(language) named mudela.  This chapter is a gentle
introduction Mudela.

We will demonstrate the working of Mudela by presenting a examples of
input alongside with the resulting output.  We will comment on these
examples using English terms for notation, so if you are not familiar
with these terms, you should consult the glossary that is distributed
with LilyPond: it contains a list of musical terms along with
explanations and translations in some other languages.

sect(The first tune)
label(sec:firsttune)

To demonstrate what LilyPond input looks like, we start off with a
full fledged (yet simple) example. It is somewhat convoluted version of one of the  menuets in  J.~S.~Bach's ``Clavierbuchlein".

mudela(verbatim)(
% lines preceded by a percent are comments.
\include "paper16.ly"
\score {
    \notes                      % let's start music
    \relative c'' {             % octave quotes are relative now
        \key G;
        \time 3/4;              % set the time signature.

        d4 [g,8 a b c] d4 g, g |
        e'4 [c8 d e fis] g4 g, g |
        c4 [d8 c b a] b4 [c8 b a g] |
        a4 [b8 a g fis] g2.  |

        \bar ":|";              % a repeat sign


        b'4 [g8 a b g]
        a4 [d,8 e fis d] |
        g4 [e8 fis g d] cis4 [b8 cis] a4 |
        [a8-. b-. cis-. d-. e-. fis-. ]
                                % try some super and subscripts.
        g4 fis e |
        fis a,  r8 cis8
        d2.-\fermata
        \bar "|.";
    }
    \paper {
       linewidth = 10.0 \cm; % standard settings are too wide for a book
   }
})

Before we will discuss the contents of the above, it would be best if
you would try to enter and save this text with a text editor, compile
it with LilyPond and view the output.  Details of this procedure may
vary from system to system.  On a Unix system, you should enter the
input in a file ending in file(.ly), such as file(menuet.ly).  To
create the output, one would issue
verb(
        ly2dvi menuet
)
file(ly2dvi) is a little program that does the job of calling the LilyPond
and  
TeX() and adjusting page margins.

If all goes well, this will create the output file file(menuet.dvi).
To view this output, isssue the command
verb(
        xdvi menuet
)

[running on W32?]

Now for some explanation of the input itself, we will dissect the
input line by line

verb(\input "paper16.ly")

By default, LilyPond will use definitions for a staff of 20 point
high.  If you want smaller output (e.g., 16 point), you have to import
the setting for that size.  You can do this by including a file.
code(\include "file") is replaced by the contents of the code(file).


verb(\score {
)

A mudela file combines music with directions for outputting that
music.  The music is combined with the output directions by putting
them into a code(\score) block.
verb(
   \notes                       % get ready for notes
)
This makes LilyPond ready for accepting notes.  The percent sign
(code(%)) introduces a line comment.  If you want make larger
comments, you can use block comments. These are delimited by code(%{)
and code(%})

verb(
    \relative c''               % octave quotes are relative now
)
As we will see, pitches are combinations of octave, note name and
chromatic alteration.  In this scheme, the octave is indicated by using raised
quotes (') and lowered" quotes (commas: code(,)).  The central C is denoted
by code(c').  The C one octave higher is code(c'').  One and two
octaves below central C is denoted by code(c) and code(c,)
respectively.

If you have to indicate the pitches in a long piece that is written in
either a high or very low octave, you would have to type very many
quotes.  To remedy this, LilyPond has a so-called "relative" octave
entry mode.  In this mode, notes without quotes are chosen in such an
octave that they are the closest to the preceding note.  If you add a
high-quote an extra octave is added.  The lowered quote will substract
an octave.  Because the first note obviously has no predecessor, you
have to give the (absolute) pitch of the note to start with.

verb(
       {                          % sequential music follows
) COMMENT(

) The brace indicates that what follows is sequential music, i.e.,
notes that are to be played and printed after each other.  This is in
contrast with simultaneous music: notes that are to be played like a
chord.  You should be careful not to confuse this brace with the one
coming after code(\score).


verb(
        \time 3/4;              % set the time signature.
) COMMENT(

) This command changes the time signature of the current piece: this
prints a 3/4 sign.  The 3/4 value is also used to generate bar lines
in the right spots.
verb(
        \key G;
) COMMENT(

) This command changes the current key to G-major.  Notice that in the
output, the key comes before the time signature, like it should be.
verb(
        d4
) COMMENT(

) This is a code(d) note.  The relative music was started with a
code(c''), the real pitch of this note is code(d'').  The 4 is
designates the duration of the note (it is a quarter note).
verb(
        [g,8
)
The open bracket starts a beam.  This bracket is connected to the
following note, which is an eighth pitch code(g') (remember relative mode)
verb(
        a b
)
These are notes with pitch code(a') and code(b').  Because their
duration is the same as the code(g), there is no need to enter the
duration (It is not illegal to enter it anyway.  Then you would have
to enter code(a8 b8))
verb(
          c]
)
This ends the beam started 4 notes before at the c.  In the output,
you will notice a measure bar following this note.  You do not have to
enter anything to make LilyPond create a bar.  Instead Lily deduce
where bars have to be by comparing durations of notes with the current
time signature.
verb(
          d4 g, g |
)
3 more notes.  The code(|) is a "barcheck".  When processing the
music, LilyPond will check  that barchecks are found at the start of
a bar precisely.  This makes it easy to spot where one left out a
note. 
verb(
        e'4 [c8 d e fis]
)
Up till now, no notes were chromaticall altered.  Here is the first
one that is: code(fis). Mudela by default uses Dutch note names, and
``Fis'' is the Dutch note name for ``F
sharp''.  However, there is no sharp sign in the output. The program
keeps track of key signatures, and will only print accidentals if they
are needed.

The next 2 lines are  not very interesting, nothing happens what we
haven't seen already.  The next line introduces  a small new feature:
verb(
        a4 [b8 a g fis] g2.  |
)
A duration that is to be augmented with a duration dot, is notated
with a number followed by periods, as many as you want augmentation
dots.
verb(
        \bar ":|";              % a repeat sign
)
Lily can not detect where you want your music to be repeated, so you
have to instruct her: a special bar symbol can be entered by the
code(\bar) command followed by a string that signifies the bar symbol
that you want.  Then comes a semicolon to separate the string from the
rest of the notes, analogously with code(\key) and code(\time).
verb(
     cis'4 [b8 cis] a4 |
)
This line shows that Lily will print an accidental if that is needed:
the first C sharp will be printed with an accidental, the second without.
verb(
        [a8-. b-. cis-. d-. e-. fis-. ]
                                % try some super and subscripts.
)
There is more to music than just pitches and rhythms.  An important
aspect is articulation.  You can enter articulation signs either in an
abbreviated form, e.g., by using code(-.) for staccato as shown above.

verb(
        fis a,  r8 cis8
)
Rests are denoted by the special notename code(r).  You can also make
an invisible rest by using the special notename code(s).
verb(d2.-\fermata)
Finally, all articulations has a verbose form, like code(\fermata).
The ``command'' COMMENT(Hi Adrian :-)
code(\fermata) is not part of the core of the language (most of the
other discussed elements are), but it is an abbreviation of a more
complicated description of a fermata.  code(\fermata) refers to that
abbreviation and is therefore called an em(identifier).

verb(
        }
)
This ends the sequential music.

verb(\paper {
            linewidth = 10.0\cm;
})
This specifies a conversion from music to notation output.  Most of
the details of this conversions (font sizes, dimensions, etc.) have
been taken care of, but  to fit the output  in this document, it has
to be smaller.  We do this by setting the line width to 10 centimeter
(approximately 4 inches).

verb(
        }
)
Finally, the last brace ends the code(\score) block.



There are a couple of things to note here.  The input format tries to
capture the meaning of em(music), and not notation.  Therefore the
format contains musical concepts like pitches and durations, in stead
of symbols and positions.  Second, the format tries to be
em(context-free): a note will remain to sound the  same regardless of
the current time signature, the key nop(etc.)COMMENT(footnote The
code(\relative) mode is a concession to this, but a )


The purpose of LilyPond informally is explained by the term `music
typesetter'. As you may have figured out by now, this is not a really
adequate name: not only does the program print musical symbols, it
also tries to make esthetic decisions, and it also em(generates) both
the symbols and the decisions from a high-level musical description.
In other words, the function of LilyPond would be best described by
`music compiler' or `music to notation compiler'.

We find that ---once you master the language--- there are big
advantages of using LilyPond over GUI oriented programs: first,
entering music is quite efficient.  Second, it is possible to explain
exactly what the meaning piece of mudela is, and you can transform
these pieces automatically (eg, by transposing them).  Third, the
program that is not interactive, so much less tradeoffs have to be
made between processing speed and the beauty of the output: you get
prettier output by using LilyPond.


As you can see, the most interesting parts of the input is music
itself, in this case the sequence of notes.  We will therefore focus
on entering music for now.  Consequently, when we mean
verb(\score {
        \notes { XXXX } 
        \paper {  }
})
we will leave out the the repetitive details and just print
code(XXXX).



sect(When you know the notes to nop(print)ellipsis())

The basic building block of music is the note.  We lightly touched
notes in the previous example.  Here comes the full explanation A note
is made of a pitch and a duration.  The pitch of the central C is
written as code(c').  This is in line with musicological notation;
there this pitch is transcribed as nop(c)sups(1) or c'.  A
quarter-note duration is written as code(4).  So, to print a quarter
note whose pitch is central C, you enter the following code(c'4).

subsect(Duration)

The duration of a note is specified as a number: a whole note is
denoted by 1, a half note by 2, a quarter by 4, and so on.  If you
want to augment a duration with a dot, simply affix a period to the
number.  You can also print notes longer than a whole.  You do this by
using identifiers (code(\breve) and code(\longa):
Here are some random notes to show how it works.

verb(
  c'\longa c'\breve  
  c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
)

mudela()(
\score {
       \notes {
         c'\longa c'\breve  
         c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 c'2. c'8. c'16
         }
         \paper {
                linewidth = -1.0;
                \translator { \StaffContext
                            \remove "Staff_symbol_engraver";
                            \remove "Bar_engraver";
         }}}
         
)

subsect(Basic pitches)

The pitch code(c')  consists of two parts: one part for the
note name, and one for the octave.  The letter specifies which note
name to use: note names simply are the letters code(a) to code(g).
The number of apostrophes specifies the octave to use: the central C
is denoted by code(c').footnote(By convention, the A above central C
at concert pitch is the tone that is used to tune instruments.  Its
frequency is about 440 Hz.)  The C which is an eighth higher (the C in
the ``two-line octave'') is denoted by code(c''): every octave adds a
quote.  A note name without quotes designates the pitch below code(c')
(the C in the ``small octave''). If you want to go down even further,
commas should be added, e.g., the C in the ``contra octave'' is
expressed as code(c,,).footnote(The comma is meant to represent a
sunken apostrophe.)

This example demonstrates pitches
mudela(fragment,verbatim,center)(
   c,,4 c, c c' c'' c''' d'4 e'4 f'4 g'4
)


subsect(Alterations)

We have so far ignored chromatically altered pitches.  The names `a'
to `g' for entering pitches are convenient: they are short,
pronounceable and they resemble the words for pitches in normal
musical vocabulary.

Enter flats and sharps.  In English there is no standard terse word
for C sharp or C flat.  For this reason, mudela uses a different,
non-English convention for entering altered pitches: a note is made
sharp by adding the suffix `--is' to its name, and flat by adding the
suffix `--es'.  For a double sharp another `--is' suffix is added, for
flats another `--es' suffix. The names for the alterations of C are
given in bind(Table)ref(notename-tab).

latexcommand(\begin{table}[h])
  center(
    table(2)(ll)(
      row(cell(english)cell(LilyPond))
      rowline()
      row(cell(c double flat)cell(ceses))
      row(cell(c flat)cell(ces))
      row(cell(c natural)cell(c))
      row(cell(c sharp)cell(cis))
      row(cell(c double sharp)cell(cisis))
    )
  )
  latexcommand(\caption{Default note names})
  label(notename-tab)
latexcommand(\end{table})

Variations on this convention are used in a number of germanic
languages, notably Dutch, German, Swedish, and Norwegian.

Throughout this document we will continue to use these names.footnote(
  Mudela defaults to Dutch notenames.  To make (Dutch) pronunciation
  easier, the a-flat and e-flat are contracted to code(as) and
  code(es).  Similarly, the a double flat and e double flat are
  contracted to code(ases) and code(eses).  For consistency, the dutch
  names also include code(aes), code(aeses), code(ees) and
  code(eeses)) consistency

If you are not comfortable with these names, you can make your own.
Note names for different languages are included with the example
initialisation files, amongst others English (C sharp is abbreviated
to code(cs)), Italian, Swedish and Norwegian.  If you want to use
these names, issue code(\include "LANGUAGE.ly") where you could
substitute code(italiano), code(deutsch) etc.  for LANGUAGE.  You
should include these files at toplevel, i.e., before opening a
code(\score) block.


sect(Chords)

The previous examples all notes   that were to be played sequentially,  one
note following the other.  You can also use LilyPond to typeset
chords.  You do this  by expressing in mudela simultaneous music,
i.e.,   notes that are to be played concurrently. 

In Mudela you can form simultaneous music by enclosing notes in
pointed parentheses, bind(i.e.)bind(langle())bind(and)rangle().  ASCII
doesn't really have these delimiters, so Mudela uses the larger-than
(code(>)) and smaller-than (code(<)) signs instead.  For example, a
D-major chord is expressed as
mudela(fragment,verbatim,center)(
  <d'8  fis'8 a'8 d''8>
)

Chords can be entered in the music in the same places that notes
can.  As an example we give a snippet of ``Twinkle Twinkle Little
Star'' in chords.  The chords may seem slightly unconventional, but
they only serve to show how chords work.  We've aligned the chords in
the input on their starting beat just to help you reading it.  This
layout does not influence the typesetting result in any way.

mudela(verbatim, fragment)(
  \relative c' {
  \time 2/4;
  c4       c            <c g'>    <c e g>
  <c e a>  <b d a'>     <b2 d g>
  <a4 d f> <bes d f>    <bes c e> <g c e>
  <e a d>  <a, g' cis'> <d2 f d'>
  }
)

You can nest simultaneous and sequential music in any way you want,
e.g.,
mudela(verbatim,fragment)(
        < { c''4 c''4 }
          { c8 <c e> c <c e> } >
)
As you can see, LilyPond has some difficulty typesetting this
elegantly.  To adequately solve this, you have to persuade LilyPond to
make separate stems for both sequential music lists.   This is a topic
that is covered in bind(Section)ref(sec:polyphonic).


sect(Adding nuances: articulation and dynamics)

Having just chords and notes does not give you real music.  Real music
has more liveliness to it: music can have articulation, dynamics
(louder and softer), etc.  This liveliness has notation, so LilyPond
can print it.  We'll start out by explaining how to obtain the
smallest grains of nuance: the articulation of a single note.  Articulation
is entered by writing a dash and the name of the desired articulation
mark.  You have to add a backslash in front of the name to distinguish
it from the name of a note.  mudela(fragment,verbatim)(
  c''4-\staccato
  c''4-\tenuto )

Typing a lot of staccato notes in this syntax will get tedious very
quickly.  Therefore, Mudela has some handy abbreviations for
articulation marks such as staccato and tenuto.  They are shown in the
following example:

mudela()(
\score{ <
        \property Score.textstyle = typewriter
        \type Staff \notes {
                c''4-.
                c''4--
                c''4-+
                c''4-|
                c''4->
                c''4-^
                }
        \type Lyrics\lyrics {
              "."4 "-" "+" "|" ">" "\^{ }" }
        >
        \paper { linewidth = 12.\cm; }
})

Text and digits for fingering can be entered in the same manner: add a
dash and the text or digit to be printed:
mudela(fragment,verbatim)(
  c''4-1 g''4-5 c''-"Sul tasto" )
Currently, the meaning of the
syntax `note-dash-digit/articulation/text' is just ``add a superscript to this
note.''  This is not in line with our goal to em(define) music with
Mudela.  We hope that this will be fixed in a future version of the
language.  In the meantime you can abuse this: the super- and
subscripts can be forced into up or down position respectively by entering an
a caret (code(^)) or an underscore, code(_) instead of the dash:
mudela(fragment,verbatim,center)(
  c'4-^ c'4^^ c'''4-^ c'''4_^
)

Dynamic markings are another way to add a nuance to a note.  They are
entered by adding the name for the dynamic sign after the note.  You
should not enter a dash between the name and the note.footnote(This
  is inconsistent.  We hope that this will be fixed in a later
  version of the language.)
mudela(verbatim,fragment)(
  c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
)
COMMENT(UGH)

sect(Bridging the notes: beams, slurs and ties)

Up till now most of the typesetting concerned simple fixed symbols
only.  Now we turn to variable symbols: symbols that run from one note
to another. In LilyPond terminology, such a symbol is called a
em(spanner).  To print a spanner, you have to attach a marker to the
note that begins it and to the one that ends it.


The first example of such a symbol is the slur.  For the slur, the
start marker is the opening parenthesis. It won't be a surprise that
the stopping marker is the closing parenthesis.
For example:
mudela(fragment,center,verbatim)( c'4( )c'4 )

Notice that the parentheses should be between the notes.footnote(The
location of the parentheses might be changed in a future version of
the language.)

It is your job to make sure that each slur that you start also ends.
If it doesn't end, then Bad Things are likely to happen.  The slur is
quite flexible: you can nest nop(slurs,)footnote(This is inconsistent
when compared to the syntax for articulation hints.  This will be
fixed some time, we hope.) and you can connect a note with a slur on
both the left and the right side:

mudela(fragment,verbatim,center)(
  c'4((   )c''4 )c'4( )g'4 
)

Another spanner is the beam (see bind(Figure)ref(mud:beam)).  Strictly
speaking, a beam is not a musical concept.  The pattern of a beam can
be derived from the structure of the time signature and the durations
of the notes. It is merely a device that helps you understand the
rhythms notated. Unfortunately, LilyPond is not smart enough to insert
beams into your music on her own. You will have to instruct her by
marking the starting and stopping point of the beam with `code([)' and
`code(])' respectively, e.g.

latexcommand(\begin{figure}[h])
  center(
    mudela(fragment,verbatim, center)([c'8 c'] [c'16 c' c' c'] [c'16. c'32 c' c'16.] )
    latexcommand(\caption{Some beams})
    label(mud:beam)
  )
latexcommand(\end{figure})

LilyPond has code that guesses what the pattern should look like, so
that you don't have to specify the beaming for complicated
patterns.footnote(Unfortunately the algorithm used is not foolproof yet:
  code([c8. c32 c32]) will produce incorrect results.)

Again, it is your responsibility to make sure that you end every beam
that you start.

A third spanner is similar to the slur: the tie.  The tie looks like a
slur, but a slur connects whole chords, whereas the tie connects
note heads.  Tied notes should be played as one long note.
In analogy with TeX()'s tie (which  ties together words with a
space), LilyPond's tie is entered as a tilde, `code(~)'.  

The input convention for the tilde is somewhat peculiar when used in
conjunction with chords.  Internally, the extra information that is
represented by the tilde has to be attached to a note (or to a rest,
for that matter).  For this reason, you can't put the tilde between
two chords (as in code( <c' g'> ~ <c' g'>)).  The tilde sign must be
directly after a note of the chords.  It does not matter which
one. The following example demonstrates the use of ties:
mudela(fragment,verbatim,center)(
  c''1 ~ c''4
  <c'1 ~  g' es''> <c'4 g' es''> 
)

sect(Commands)
label(sec:commands)

We have focused on printing notes. Notation contains many other
constructs, constructs that help you with reading those notes.
Examples of such constructs are clefs, time signatures, keys etc.
LilyPond will try to generate these constructs as much as possible,
but not all such hints can be inserted automatically, and you can also
override some of the settings.  This can be done by inserting various
commands between the music.  The general form of these commands is
COMMENT(

)center( em(keyword) sc(arguments) )

em(keyword)s are words that have a special meaning to the parser of
Mudela.  Because the parser must be able to distinguish the keywords
from note names, they have to be preceded by a so-called escape
character, the backslash, `code(\)'.  To separate the arguments from
any notes that might follow the arguments, you have to end your
command with a semicolon.  An added benefit of this construction is
that the commands stand out between your notes, because of the
backslashes.

So the general form actually is `code(\keyword argument argument ... ;)'
Let us review these commands:

description(
dit(code(\clef) var(clefname)) This command sets the current clef for notation,
  i.e., a clef symbol is printed and the notes following this command
  are shifted vertically.  The argument is a string, the name of the
  new clef. The default clef is the treble clef.
  mudela(fragment,verbatim)(
    \clef "bass"; c'4
    \clef "treble"; c'4
    \clef "alto"; c'4    
  )
dit(code(\key) var(pitch) var(type)) This command changes the current
  key signature.  The key signature is printed at the start of every
  line. The var(type) argument is set to code(\major) or code(\minor)
  to get major or minor keys, respectively. Omitting the second
  argument gives major keys. The key of C-minor can thus be specified
  as `code(\key es)' or `code(\key \c minor)'. 
  
dit(code(\keysignature) var(pitchlist))

This command changes the current key signature.  Unlike the
`code(\key)' command, this command can produce arbitrary key
signatures, which can be useful for unconventional keys or modes.  The
key signature is given in the form of a list of notes.  The notes will
be printed in the key signature in the order that they appear on the list.
For example, the key
of C-minor can be specified as `code(\keysignature bes es as)'.  The
command `code(\keysignature fis es bis)' provides a more exotic
example.


dit(code(\time) var(numerator)code(/)var(denominator))
  This command changes the current time signature.  LilyPond uses the
  time signature to
  calculate where to place the bars that start a measure.  These bars
  in turn are the places where a system can be broken into lines.

  The default value for this time signature is common time (4/4).  You
  can also tell this from the  Twinkle ``Twinkle Little
Star'' example in bind(Figure)ref(fig:twinkle1).  This
song actually has a 2/4 time signature, so a metrically more correct
  version  would start with as follows:
  mudela(fragment,center,verbatim)(
    \time 2/4;  c'4 c'  g' g' 
  )


dit(code(\cadenza) var(togglevalue)) When typesetting music without a
regular meter (such as an ad libitum cadenza), no bar lines should be
printed.  In LilyPond you can achieve this by issuing the command
`code(\cadenza 1)': it turns off the automatically
generated bar lines.

You switch them on again with `code(\cadenza 0)', and then a bar line
is printed.  LilyPond will act as if you are again at the start of a
measure.

dit(code(\bar) var(bartype))
  This command lets you print special bar
  lines and repeat symbols.  You can also use it to allow line breaks
  when entering cadenzas.  The argument var(bartype) is a string that
  describes what kind of bar line to print.

mudela(fragment,verbatim)(
    \bar "|:"; c'4 \bar ":|:";    c'4  \bar ":|";  c'4 \bar "||";
    c'4 \bar "empty"; c'4 \bar "|.";
)
  The command `code(\bar "empty")' does not create any visible bar
  line, but it does tells LilyPond to allow a linebreak
  at that position.  The `code(\bar)' command prints the specified
  symbol immediately.  If you give a `code(\bar)' command at the end
  of a measure then
  the specified symbol replaces the automatic bar line; otherwise
  the specified symbol appears in the middle of the measure.   The
    code(\bar) command does not affect metric structure.


  
dit(code(\partial) var(duration)) some music starts with a measure that
isn't fully filled, a so-called upstep.  The code(\partial) command
allows you to make
upsteps. The argument is a duration similar to the duration of a note.
The `code(\partial)' command cannot be used to generate partial
measures in the middle of the music.  
Example:
  mudela(fragment,verbatim)(
    \time 4/4;
    \partial 4;
    [d'8 dis'] e' c''4 e'8 c''4 
  )

  dit(code(\grouping) var(durationslist)) sets the metric structure of the measure.
    Its effect can best be shown by an example:
    mudela(fragment,verbatim)(
        \time 5/16;
        \grouping 16*3 16*2;
        [c'8 c'16 c'8]
        \grouping 16*2 16*3;
        [c'8 c'16 c'8]
        \grouping 16*5 ;
        [c'8 c'16 c'8]
    )

In practice, you won't be needing this command very often: the
grouping is switched automatically when you issue a code(\time)
command.  It is set to a combination of groups
of 2 and 3 beats, with as many groups of
3 as possible (in other words: 4/4 is divided in two times two beats
(2+2), 8/8 in 3+3+2)
)

The commands that are described above aren't really music, but they
can be used in the same places as notes.  This makes the grammar of the
language simpler.  It is possible to put a command into a chord.
For example, the following two snippets of Mudela produce identical output.
verb(
  <c4 e g \time 2/4;>
  \time 2/4; <c4 e g>
)

sect(Notation context)

This section is about translation contexts, a topic of LilyPond that
is somewhat advanced.  You don't have to understand this to use
LilyPond to print simple music.  If you don't want to typeset fancy
polyphonic music or tweak the LilyPond notation engine, you can skip
the next two sections.

In bind(Section)ref(tutorial:more-staffs) it was explained, that there
are more ways to notate a simple chord: as a single voice on a single
staff or in multiple staffs (and we'll soon see, that you can typeset
it as multiple voices on a  staff).  Obviously the concept of staff is not
really something musical.  But what is it

The most simplistic explanation is: a staff is a peculiarity of the
notation system.  In other words, a staff is a graphic device, a
special picture of five lines on which one can print note heads.  To
avoid confusion, we will call this view on the concept of staff
`staff symbol' from now on.

There is more to it than meets the eye and mind.  A staff
contains---besides a staff symbol--- some more components:
itemize(
it()A staff can  have a key signature (printed at the left)
it()A staff can have a time signature (printed at the left)
it()A staff has bar lines
it()A staff has a clef (printed at the left)
)
To explain what a staff really is,   we'll try to print music without
these components.  If these components aren't printed, it is still
possible to print music:
mudela()(\score{
\notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
\paper { 
  linewidth = -1.;
  \translator {
  \StaffContext
  \remove "Time_signature_engraver";
  \remove "Bar_engraver";
  \remove "Staff_symbol_engraver";
  \remove "Clef_engraver";
  \remove "Key_engraver";
  }
 }
})

As you can see, one can still make out the general form of the melody
and the rhythm that is to be played, but the notation is difficult to
read and the musical information is not complete.  The stress pattern
in the notes can't be deduced from this output.  For this, we need a
time signature:

mudela()(
\score {
  \notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
  \paper{
  linewidth = -1.;
\translator{
  \StaffContext
  \remove "Bar_engraver";
  \remove "Staff_symbol_engraver";
  \remove "Clef_engraver";
  \remove "Key_engraver";
  }}
 })

Technically speaking you know where the strong and weak beats are, but
it is difficult to find them quickly.   Bar lines  help you in finding
the location within the measure of the notes:
mudela()(
\score {
  \notes \relative c' {  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
  \paper{
  linewidth = -1.;
\translator{
  \StaffContext
  \remove "Staff_symbol_engraver";
  \remove "Clef_engraver";
  \remove "Key_engraver";}
  }
 }
)

We can remedy part of the difficulties with reading pitches by adding a staff
symbol:

mudela()(\score{
  \notes\relative c' { \time 2/4; g'4 c,4
a'4 f4 e c d2 } \paper {
  linewidth = -1.;
  \translator {
  \StaffContext

  \remove "Clef_engraver";
  \remove "Key_engraver";
  }
 }
})

This makes the output decidedly easier to read, but you still don't
know what the pitches of the notes above are.  So this is still not
enough.  But suppose you see the following notation:
mudela()(\score {
  \notes \relative c' {\clef alto;  \time 2/4; g'4 c,4 a'4 f4 e c d2 }
  \paper {
    linewidth = -1.;
  }
})

Now you know the pitch of the notes: you look at the start of the line
and see a clef, with this clef, you can determine the notated pitches.
You have found the em(context) in which the notation is to be
interpreted!

So the context determines the relationship between a piece of music
and its notation: you, the reader, use context to deduce music from
notation.  Because LilyPond is a notation writer instead of a reader,
context works the other way around for Lily: with context a piece of
music can be converted to notation.  The components of a staff form
context, and context is needed to read and write notation.  This
motivates the following definition.

quote(
A bf(notation context) is  a conversion from music to notation.
)

The example focused mainly on on staffs, but a staff is not the only
type of notation context.  Notation contexts may be nested: you can
print polyphonic music by putting multiple `Voice' contexts in one
`Staff' context.  The arguments of the code(\type) command (Staff,
GrandStaff) were in fact all names of different contexts.
The notions of ``current clef'' and ``current position within the
measure'' are all properties of notation contexts.  Commands like
code(\clef) and code(\cadenza) change these properties.  


The following is a list of the contexts that are supported by
LilyPond:
description(

dit(Voice) The code(Voice) context is a context that corresponds to a
  voice on a staff.  This context handles the conversion of noteheads,
  dynamic signs, stems, beams, super- and subscripts, slurs, ties and rests

dit(Staff) The code(Staff) context handles clefs, bar lines, keys,
  accidentals.  A code(Staff) context can contain multiple code(Voice)
  contexts.

dit(RhythmicStaff) The code(RhythmicStaff) context is like the staff,
  but much simpler: the notes are printed on one line, and pitches are
  ignored.  code(RhythmicStaff) can contain code(Voice) contexts.

dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
  contexts, and it adds a brace to the output at the
  nop(left.)footnote(This is a major deficiency in the current
  implementation.    Currently stems,
  slurs and beams cannot be printed across two staffs.
In reality, a grand staff is  a hybrid of one big staff and two stacked staffs.)
  
  A code(GrandStaff) context can contain multiple
  code(Staff)s. Typically, it will contain two code(Staff)s, one
  treble staff, and one bass staff. The bar lines of the contained
  staffs are connected vertically.

dit(StaffGroup) A code(StaffGroup) context contains code(Staff) or
  code(Lyrics) contexts, and prints a bracket at the left.  The bar
  lines in the participating staffs are connected.

dit(Lyrics) As its name suggests, The code(Lyrics) context deals with
  typesetting lyrics.  This topic will be covered in
  bind(Section)ref(tutorial:lyrics).
  
dit(Score) The code(Score) context is the toplevel context: no context can
  contain a code(Score) context.  The code(Score) context handles the
  administration of time signatures.  It also makes sure that items
  such as clefs, time signatures, and key-signatures are aligned across staffs.
  
  The code(Score) can contain code(Staff), code(StaffGroup), code(Lyrics), code(GrandStaff) and
  code(RhythmicStaff) contexts.

COMMENT(do ChoireStaff)
)


  Later on, in bind(Section)ref(tutorial:engravers) we will
explain how you can create your own contexts.

If you are familiar with structured documents (like HTML, SGML or
LaTeX()), you might see the analogy of a context with a stylesheet: a
stylesheet is neither presentation nor information, but rather a
recipe em(how) a specific piece of information should be presented.
Analogously, a notation context is neither music nor notation, but the
conversion between the two.  The big difference with text is that in
music notation the elements provided by context are essential to
understanding what is notated.


sect(Nested music: more than one staff)
label(tutorial:more-staffs)

Now we explain how to typeset music that runs in multiple staffs.
Consider the following---somewhat unrealistic---example:

mudela(fragment)(
 \type GrandStaff <e'4 {\clef bass; g4^""} >
)

  The music consists of two notes.  Perhaps this is sheet music for a
piano player, and one note is meant to be played with the left hand,
and the other with the right hand.  That music would sound the same if
it were written as a single chord on a single staff, i.e.,
mudela(fragment)(
  <g4 e'4>
)


This is another example where we can see that there can be a difference
between a musical idea, and the way it is expressed in notation.

The Mudela construct for multiple staffs reflects the similarity
between the two examples: to get multiple staffs in Mudela you enter a
chord, with an additional instruction to tell LilyPond that the chord
does not represent notes stacked together, but staffs stacked
together.

If a piece of music is to be interpreted as a staff, then this can be
expressed with the code(\type) construct.  The following input says
``the quarter note with pitch e should be put on a staff.''

verb(
  \type Staff e'4 
)

The same can be done for the other note, i.e.,

verb(
  \type Staff g4 
)

If you want to stack these staffs, you must create a chord of both:

verb(
  < \type Staff e'4
    \type Staff g4 
  >
)

This looks reasonable, but the effect of this input is not what you
might expect (try it!).  When interpreting this chord LilyPond will
start with the first entry, so a (nameless) staff is searched.  Such a
staff is not found, so it is created.  On this staff the code(e) note
is put.  When the second code(\type) entry is read, LilyPond will
start looking for a nameless staff.  The staff that contains the
code(e) is found, and the code(g) is put there as well.

The correct solution is to label both code(\type) constructs with
different names, for example code(trebleStaff) and code(bassStaff).
This makes LilyPond distinguish between them, and create two staffs:

mudela(verbatim,fragment)(
  < \type Staff = trebleStaff e'4
    \type Staff = bassStaff  g4 
  >
)

The names that you choose do not matter just as long as they are
different.  This is almost right, except for the brace at the left and
the clef of the second staff.  The bass clef will be taken care of in
the next section. If you want a brace, then you have to tell LilyPond
that the chord you just formed is to be interpreted as a so-called
grand staff.  This is also done with the code(\type) command.
mudela(verbatim,fragment)(
  \type GrandStaff <
     \type Staff = treblestaff  e'4 
     \type Staff = bassstaff  g4 
  >
)




sect(Polyphonic music (or: Notation context properties))
label(sec:polyphonic)


In the last section we explained that a notation context can have
properties that influence the conversion from music to notation.  A
simple example of such a property is the clef: the type of clef partially
determines the vertical position of note heads in a staff.  Some of
these properties can be modified by commands such as code(\clef) and
code(\time).   But there is more:  notation contexts  also have
properties are settable in a generic fashion.  We will demonstrate
this feature by printing multiple voices on a staff.

In polyphonic (keyboard) music and orchestral scores often more than
one voice is printed on one staff.  We'll explain how to achieve this
effect with LilyPond.  The effect is not unlike the two stacked staffs
from bind(Section)ref(tutorial:more-staffs), except that we don't want
to stack staffs but voices.  Thus,  the general template is the following:
verb(
  \type Staff <
    \type Voice = one  ...
    \type Voice = two  ...
  >
)

On the ellipsis there should be music going from left to right, in
otherr words, there should be sequential music, notes enclosed in
braces.  Let us try the following simple melodies:

mudela(fragment,verbatim)(
\type "Staff" <
  \type "Voice" = "one" { r4 as'4 () as'4 g'4 }
  \type "Voice" = "two" { g'2 f'4 e'4 }
>)

As you can see the result is not quite perfect.  The notes on the last
two beats look like plain chords and not like separate voices.  What
really happened was that the stems of the upper and lower voices were
printed on top of each other.  If you have tried running this example, you will probably
have noticed a complaint  about ``too many
clashing notecolumns''  during the LilyPond run.
This complaint refers to the overlapping stems.

To remedy this, engravers traditionally make the stems of the upper
and lower voice point in different directions: the stems of the lower
voice point down, and the stems of the upper up, as shown in
bind(Figure)ref(tutorial:multi-voice-fig).

Surely the direction of a single stem is a property of the stem as a
graphical object.  But the fact that all of the stems in a voice point
in the same direction is not directly graphical.  Since this is a
property shared by all the stems in the voice, it is logical to
consider this property to be a property of the context code(Voice).
And this is how it's done in LilyPond: the context code(Voice) has an
attribute whose value is the direction to use
for stems.  You can change it to `up'
by issuing the following phrase:footnote(The name code(ydirection) is
no mistake.  The property also controls the up/down directions of
super-/subscripts, slurs, ties, etc.)

verb(
  \property "Voice"."ydirection" = "1"
)

This command should be read as ``change the property called
code(ydirection) within the current code(Voice) context to the value
code(-1).''  For the property code(ydirection) the value code(1) means
`up', and code(-1) means `down'.   The proper way to code the
polyphonic example is given in bind(Figure)ref(tutorial:multi-voice-fig).

latexcommand(\begin{figure}[h])
mudela(fragment,verbatim,center)(
  \type "Staff" <
    \type "Voice" =  "one"  {
      \property Voice.ydirection = "1"
      r4 as'4 () as'4 g'4 }
    \type "Voice" =  "two"  {
      \property Voice.ydirection = "-1"
      g'2 f'4 e'4 }
  >
)
    latexcommand(\caption{multiple voices})
    label(tutorial:multi-voice-fig)
latexcommand(\end{figure})

Other properties can also be set, and they can be within different
contexts.  In general, you can set a property by specifying
code(\property) var(contexttype)code(.)var(propertyname) code(=)
var(value).  Both var(ContextType), var(PropertyName) and var(Value)
should be strings.

The effect of a property is pretty much hardwired into the
implementation (and thus subject to change), so we will not deal with
all the possible properties in detail. Among other characteristics that
can be set are the layout of slurs and beams.  The initialisation file
file(property.ly) explains most properties.

We conclude this section with another example of a context property.
Polyphonic music that has three or four voices can't be printed by
simply changing the directions of the stems for each voice, obviously.
Traditionally, some chords are shifted horizontally to print if this many
voices have to be printed.
LilyPond can also do this, and the property that controls the
horizontal shifting is called code(hshift).  The notes in a
code(Voice) context that has code(hshift) set to a true value (i.e.,
non-zero or non-empty), will be shifted horizontally in the case of a
collision.  The following example demonstrates the effect.

mudela(fragment,verbatim)(
  \type "Staff" <
    \type "Voice" =  "one"  {
      \property Voice.ydirection = "1"
      r4 as'4 () as'4 g'4 }
    \type "Voice" =  "two"  {
      \property Voice.ydirection = "1"
      \property Voice.hshift = 1
      g'2 f'4 e'4 }
    \type "Voice" = "three" {
      \property Voice.ydirection = "-1"
      [d'8 dis'] [d' cis'] [c' b] c'4
    }
  >
)

sect(Lyrics)
label(tutorial:lyrics)

Now for something completely different: Lyrics.  Lyrics are also
considered to be music, although a lyric by itself does not have any
pitch.  Producing lyrics has two aspects. First, you have to enter the
text, i.e., the syllables along with their durations.  
After this, you have to specify how to convert these to graphics.

Lyrics consist of syllables, which are strings together with
durations.  Previously we only entered note names, so for entering
lyrics we have to instruct LilyPond that what we enter are not note
names but words---or rather: strings.  This instruction is the keyword
code(\lyrics).  After entering this keyword you can enter a musical
construct---sequential music, simultaneous music, code(\type)
entries, etc.--- but with syllables in stead of pitches.  For example:
verb( \lyrics { 'got8 me on my knees4, Le-8 lie! })

The effect of code(\lyrics) can be compared with the effect of the
doublequote character, code("), for it also changes the lexical
meaning of spaces and characters.  This mode is another example of a
handy input feature of the language.

Next comes the conversion to notation.  LilyPond can't (yet) figure
out that lyrics need different treatment than notes.  As a result, the
default conversion will try to put the text you entered as note heads
onto a staff, and this will fail.  This default must be overriden with
a code(\type) keyword.  Printing syllables of text in a line is done
by a context called code(Lyrics).  You can select this context with
the code(\type) keyword.  Here is a simple example:

mudela(fragment,verbatim)(
        \type Lyrics \lyrics { 'got8 me on my knees,4 Le-8 lie! })

The result is technically more or less correct, but without a melody it
just doesn't work, so let's add a blob of cream:
mudela(fragment,verbatim)(
  <
    \type Staff  { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
    \type Lyrics \lyrics { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
  >
)

The strings that makes up each syllable in the lyrics block are passed
along to TeX() verbatim, so if you are proficient with TeX() you can
do various nifty things.  Just keep in mind that a syllable either
starts with a letter (a character in the range `code(a)' to `code(z)'
or `code(A)' to `code(Z)'), or it is a string enclosed quotes. It ends
with either a number for the duration, or a space.  A last feature
that should be mentioned is the space-lyric: if you want to enter
a single ``syllable'' that consists of multiple words, i.e., words
separated by  spaces, you should use an
underscore instead of a space.  All these tricks are demonstrated in
the following example:

COMMENT( urg
\type Lyrics \lyrics { 'got_m\textbf{e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
\type Lyrics \lyrics { 'got_m{\bf e}4 on8. m$\cal_Y$16 knees,4 Le-8 lie!4.}
)

mudela(fragment,verbatim)(<
  \type Staff  { c''8. c''16 bes'8. a'16 g'4 f'8 g'4. }
  \type Lyrics \lyrics { 'got_me4 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
>
)

COMMENT(Groen is de kleur van geluk.)
COMMENT(Dat geldt zeker voor Bj"ork)

sect(Toplevel Mudela)

Back in bind(Section)ref(sec:firsttune) we said we would defer
discussion of toplevel constructions (e.g., code(\score)) to a later
moment in time: and now we will look at these constructions.  In
general, Mudela looks like set of nested `blocks'.  The general syntax
for a block is code(\keyword { ... }).

We will now discuss identifiers.  Generally you can define an
identifier by entering code(identifierName = ... ) where there can be
a variety of things on the ellipsis.
COMMENT(
Here is a (partial) list of what you can abbreviate with identifiers
at top-level.
itemize(
it()The code(\score) block
it()The code(\paper) block
it()The code(\midi) block (to be explained in
  bind(Section)ref(tutorial:sound))
it()Music (sequential music, simultaneous music etc.)
it()Durations
it()Strings
it()Translators (to be explained in bind(Section)ref(tutorial:engravers))
it()Integers
it()Reals  
)
)

When you refer
to the abbreviated entity, you must precede code(identifierName)
with a backslash, i.e., code(\identifierName).  For example:
mudela(verbatim)(
  czerny = \notes { [c16 g e g] }
  \score {
    \notes \type GrandStaff <
      { c''2 g''2 }
      { \clef bass; \czerny \czerny \czerny \czerny}
    >
    \paper {
      linewidth = -1.0;
      stem_length = 6.0*\interline;
    }
  }
)



Another interesting feature of this example are the assignments within
the paper block.  Some blocks, such as code(\paper), have a scope of
their own.  In the case of the code(\paper) block, these variables
influence the characteristics of the output.  As is shown, you can
tune quantities like the stemlength, and enter simple expressions.
The purpose of the negative linewidth is to prevent the music from
being justified.  The identifiers that are meaningful are for the
paper block is strongly implementation dependent, so they will not be
listed here.  Moreover, since most of the values are predefined to
sensible defaults, there usually is no need to tune these values.

Recall the properties of a context, that could be set with
code(\property).  It is a very general mechanism to tune the output of
the music, that is neatly separated from the real music.
Unfortunately, it is not convenient to type or read, and the precise
effect of a setting property isn't always apparent from its
definition.  To remedy this, we can use an identifier to capture the
meaning of a code(\property).

mudela(verbatim)(
stemup = \property Voice.ydirection = "1"
stemdown = \property Voice.ydirection = "-1"
shift = \property Voice.hshift = "1"
\score {
  \type "Staff" \notes <
    \type "Voice" =  "one"  {
      \stemup
      r4 as'4 () as'4 g'4 }
    \type "Voice" =  "two"  {
      \stemup
      \shift
      g'2 f'4 e'4 }
    \type "Voice" = "three" {
      \stemdown
      [d'8 dis'] [d' cis'] [c' b] c'4
    }
  >
  \paper{  linewidth = -1.0\pt; }
}
)

Several abbreviations like code(\stemup) are defined in the
standard initialisation file file(property.ly).  Setting or changing
context properties can have a similar effect as the commands that were
discussed in bind(Section)ref(sec:commands).  Don't be fooled by the
similarity in appearance between a declared property-setting entry
and a real command.  Real commands are hardcoded into the language
and they have to be terminated by semicolons.

You can also use identifiers to break up the heavy nesting that can occur
in the code(\score) block.  Another useful application is
parametrisation of the music: if you use identifiers in the
code(\score) block, you can make variations of the music by simply
redefining those identifiers.  One particular application of this is
part extraction: by using identifiers and redefining them, one can
print extracted parts and a full orchestral score from the same
music definition.


sect(Sound output)
label(tutorial:sound)

You get output by combining music with definition a conversion to
output.  Up till now we have only focused on the graphic output of
traditional engraving.  But there is no reason why that should be the
only form of output for music.  LilyPond currently supports one other
conversion: the conversion from abstract music to sound. You can have
LilyPond play the music that you entered.  The format that is used
for this output is MIDI.  

The only information that you need to enter is the
 nop(tempo)footnote(Unfortunately,
this the only thing that can be tuned at this
time.  This is a limitation: the tempo of music can vary throughout
the music.) for the performance.  The syntax for the tempo is
code(\tempo )var(duration) = var(beatsperminute);), for example:
verb(
\score {
   ...music...
   \midi { \tempo 4 = 76; }
}) COMMENT (

) The most useful purpose of this sound output is to prooflisten your
files: typing errors stand out when you listen, especially if they
involve accidentals.  The output was implemented in a very rudimentary
manner, so it is probably not worth listening to for any other reason.


sect(Contexts revisited: engravers)
label(tutorial:engravers)

As was promised, we will now take a dive into the more wizardrous parts
of LilyPond: redefining (notation) contexts.  We previously explained
that a context 
itemize(
it()is a conversion from music to notation,
it()can contain other contexts
it()handles specific notation constructs
)

This characterization almost automatically explains what the definition of a
context should look like:
itemize(
it()It should be part of the ``notation output definition,'' i.e., the
  code(\paper) block
it()
  It should contain a specification of what other contexts may be contained
  in the context we're defining.
it()
  It should contain a list of the notation constructs  to be
  handled.
)

In practice, the context definition
looks like this:
verb(
\translator
{
        \type "Engraver_group_engraver";

        \name "ContextName";

        \accepts "...";
        \accepts "...";
        \accepts "...";



        \consists " ... ";
        \consists " ... ";
        \consists " ... ";

        propertyname = "value";
        propertyname = "value";

} )


The code(\translator) keyword opens the block for translation (or
context) definition.  The code(\type) keyword explains to Lily that
the context should be formed by taking an (empty) instance of
code(Engraver_group_engraver).  The code(Engraver_group_engraver) is a
C++ class from the source code to Lily.  The code(\accepts) entries
explain what kind of contexts this context could contain.  If we were
to define a context for a staff, the definition would typically
contain code(\accepts "Voice";).

The code(\consists) entries specify which notation constructs should
be handled. This needs a little explanation: LilyPond contains the
code for quite a large number of basic building blocks for notation
generation, and each building block handles only one notation
construct.  The name of such a building block is `engraver'.  You can
specify which notation construct a context should handle by specifying
which engravers should be part of the context.  The code(\consists
"Foobar") entry really means ``add an instance of code(Foobar) to the
translation group.''

You can also declare contexts, and reference them.  This is useful in
combination with code(\remove "..."): code(\remove) does the opposite
of code(\consists)

Finally, one can pre-set some properties in a context definition.  A
new context inherits these pre-set properties, when it is created,
e.g., when LilyPond processes the code(\type) construct.

As a practical example, we will show you how to typeset polymetric
music, i.e., music where the meter can differ for each staff.  The
solution is not very complicated: normally all timing information
(time signature, rhythmic grouping) is synchronised across each staff.
In LilyPond this is expressed by having only one registration for
timing information for all staffs.  To be precise, there is only one
code(Timing_engraver), and it is located in the top level context, the
code(Score) context.

All staffs use the information in the global code(Timing_engraver) for
generating bar lines and time signatures.  In polymetric music, this
timing information can be different for every staff, so we should
redefine the code(Staff) context to include and the code(Score)
context to exclude the code(Timing_engraver).

mudela(verbatim)(
polymetricpaper = \paper {
  \translator {
    \ScoreContext
    \remove "Timing_engraver";
  }
  \translator {
    \StaffContext
    defaultClef = bass;

    \consists "Timing_engraver";
  }
}
\score {
  \notes <
    \type Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
    \type Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
  >
  \paper { \polymetricpaper
    linewidth = -1.;
  }
}
)

As you can see, we used the identifier code(polymetricpaper) to break
up the large score block.  More of these context definitions appear in
the standard initialisation file file(engraver.ly).

sect(Urtexts and context selection)
label(tutorial:urtext)

In bind(Section)ref(tutorial:more-staffs), we have shown you how to
make multiple staffs, and explained that you have to label every staff
(or more precisely: different contexts), to make sure that new ones
are created when you need them.  In this section, the real power of
this mechanism will be unveiled.

By naming other contexts that you create, you can reference other
contexts than the current context from within the music.  For example,
from within the music that you enter for staff code(One), one could
enter a small piece of music, and send it to staff code(Two), e.g.,
COMMENT (

) mudela(fragment,verbatim)(
  <
    \type Staff = one { c''4 \type Staff = two { c4 c4 } c''4 }
    \type Staff = two { \clef bass; g,4 g,4 g,4 g,4  }    
  >
)


Another useful application of this feature is making Urtexts.
em(Urtext) is the German word for `original text'.  The Urtext
edition of a piece of music, is an edition that reflects the original
writing of the composer.  Such editions are useful for musicologists,
and performers that want  to perform authentic interpretations.  However,
for mere mortals, the Urtext can be quite hard to read.  It might not
contain fingering and beaming, and typically it is full of footnotes.
Moreover, common interpretations may have emerged---after the composer
died.  For this reason, the music that can be had as Urtext usually is also
available in enhanced and edited editions.

The mechanism of context selection can be used to fabricate an Urtext
and an edited edition from em(one source).  We will use the first few
bars of bind(J.)bind(S.)Bach's lovely Cello suite bind(no.)I to
demonstrate this.  The example makes heavy use of space rests: a space
rest takes up time, like a rest does, but it doesn't print anything.
It can be used as a placeholder, to attach articulation marks to.  It
is entered as a note with the name code(s).

mudela(verbatim)(
  bach =  \notes \relative c { [g16 d' b' a] [b d, b' d,] }
  
  staffStuff = \notes { \clef bass; \time 4/4; s1 \bar "|."; }
  
  slursOne = \notes { s16( s s s s16 s s )s }
  slursTwo = \notes { s16-. s s() s s16() s  s ()s }

  \score{
    { < \type Voice = celloVoice { \bach \bach }
        \type Voice = celloVoice { \slursOne \slursOne }
        \staffStuff
      >
      <
        \type Voice = celloVoice { \bach \bach }
        \type Voice = celloVoice { \slursTwo \slursTwo }
        \staffStuff
      >
    }
    \paper {}
  }
)

The slurs that you define should be put on the music that is defined
by the code(\bach) identifier.  By labeling a code(Voice) context, and
directing both the articulation and the notes to that same code(Voice)
context, the articulation is put over the right notes.


sect(Transposing)
label(tutorial:more-grammar)

COMMENT(In this section, we will complete the grammar for Music that was
sketched earlier. )
One of the things that you can do with music is
em(transposing) it.  If you want to transpose a piece of music, then
you should prefix the keyword code(\transpose) along with the pitch
(relative to the central C) for the transposition.footnote(the
code(\type Staff) is to make sure that no separate staffs are created
for the code(\scale) and code(\transpose cis' \scale) part.)


mudela(verbatim)(
scale = \notes \relative c' { [c8 d e f] }
\score {
  \notes {
    \type Staff { \scale \transpose cis'  \scale }
    }
  \paper { linewidth = -1.0; }
})


sect(Staff switching)

We have seen that contexts can be nested.  This means that they form a
tree.  It is possible to edit this tree: for example, a code(Voice)
context can be taken out of a code(Staff) context, and put into
another.  This has the effect of the voice switching staffs (something
that often happens in keyboard music).  The syntax for this operation
with these particular contexts is code(\translator Staff = newStaffName).

The effect is analogous to the first example in section
ref(tutorial:urtext), but with the code(\translator) construction it
is possible to split the real music and the commands that determine in
which staff the music is printed.  For example:

mudela(verbatim)(

% real music
aVoice = \type Voice = voiceA \notes { c''4 c4 c4 c''4 }
bVoice = \type Voice = voiceB \notes { g,4 g,4 g,4 g,4  }    

% staff switching stuff
switch = \type Voice = voiceA \notes { s4 \translator Staff = staffB s4
                   s4 \translator Staff = staffA s4 }

\score {
  <
    \type Staff = staffA < \aVoice \switch >
    \type Staff = staffB < \bVoice \clef bass; >
  >
  \paper { linewidth = -1.; }
}
)

Don't try to switch staffs when you are in the middle of a slur or
beam, though.  It doesn't work yet.

sect(Hairy durations: triplets)

In the previous section we explained an operation that changes the
pitches of music, transposition.  In this section we will explain an
operation that modifies the duration of the notes that you enter.
When notes are part of a triplet, then the real of duration of the
notes are 2/3 part of what their shape indicates:
mudela(fragment)(
\[/3  c'4 c'4 c'4 \]/1
)

To support this notion, Mudela allows you to modify the duration of a
note by multiplication or division.  A code(c'4) note that would be in  a
triplet is written as code(c'4*2/3).  If you sequence a few of these
notes, you get a triplet.footnote(We added a normal staff in the example to
show the difference.)
mudela(fragment,verbatim)(
<  \type Staff = staffA { c'8*2/3 c'8*2/3 c'8*2/3 c'4}
   \type Staff = staffB { c''8 c''8 c''4 } >)

LilyPond knows that these notes are no normal eighth notes, but the
reader doesn't yet.  To help the reader a beam or a bracket with a `3'
should be printed.  The special beam command `code([2/3)' and the
matching close beam `code(]1/1)' will take care of that, and
they also abbreviate the code(*2/3) part.  If you want brackets in
stead of beams, you can use `code(\[2/3])' and `code(\]1/1)'.
mudela(fragment,verbatim)(
< \type Staff = staffA {
    [2/3 c'8 c'8 c'8 ]1/1
    \[2/3 c'8 c'8 c'8 \]1/1
  }
  \type Staff = staffB { [c''8 c''8 c''8 c''8] }
>)

Other tuplets  can be entered in the same way.
mudela(fragment,verbatim)(
< \type Staff = staffA {
    \time 7/8;
    [7/6 c'8 c'8 c'8 c'8 c'8 c'8 ]1/1
  }
  \type Staff = staffB {
    \time 7/8;
    [c''8 c''8 c''8 c''8 c''8 c''8 c''8] } >
)

For your convenience, code([2/3) can be further abbreviated to code([/3), and
you can abbreviate code(]1/1) on the closing beam marker to code(]/1).

mudela(fragment,verbatim)(
< \type Staff = staffA {
    [/3 c'8 c'8 c'8 ]/1 c'4
  }
  \type Staff = staffB { [c''8 c''8] c''4 } >
)


bf(Important) the construct with code([/3) and
code([/1) is a hack that sets a mode in the parser.  This means that
verb(id = \notes { c8 c8 c8 }
notATriplet =\notes { [2/3 \id ]1/1 })
does not produce a triplet.  It will hopefully
soon be replaced by a construction that mixes more elegantly with the
grammar for Music.


sect(Shortcuts for octaves)
label(sec:relativeoctaves)

Plain Mudela contains a lot of quotes to get the octaves right.  This
need for quotes can be reduced: most of the pitch intervals in
conventional music are small.  Therefore, it makes sense to leave out
the quotes when the interval is small.  We have built a mode that does
exactly this.  It is called the relative mode for octaves.  You can
switch it on by entering code(\relative).  Then LilyPond will
interpret every note as if they mean the note with the same name
closest to the previous.  You have to specify the first pitch because
the first note of a list obviously has no predecessor.  So, you can
enter a scale without using octavation quotes, e.g.,

mudela(fragment,verbatim)(
    \relative c' { c d e f g a b c }
)

For chords, the relative mode works slightly differently.  In a
sequence of chords, the first note of a chord gives the starting point
for the next chord.  We can demonstrate this with our twinkle twinkle example
verb(
  \relative c' {
  c4       c            <c g'>    <c e g>
  <c e a>  <b d a'>     <b2 d g>
  <a4 d f> <bes d f>    <bes c e> <g c e>
  <e a d>  <a, g' cis'> <d2 f d'>
  }
)

LilyPond converts any music with code(\relative) prepended to absolute
music immediately when it is read. Internally it is stored it in
absolute pitches.  Since the tutorial mainly deals with how to specify
musical information, and not how to enter it conveniently, the
tutorial doesn't use it.


sect(Large pieces)
label(tutorial:large-pieces)

In our quest for a clean and powerfull music language, we took the effort
of entering some larger pieces of music as well.  From this we learned
certain things that lead to direct improvements of Mudela, such as the 
relative mode.  We also gained some practial experience, that resulted in a 
compilation of tips that may be of use to you.

Entering a large piece of music will often imply the need to produce a
conductor's score, as well as individual parts for all instruments.  This
can most easily be achieved making use of identifiers and including mudela
files.

subsect(Identifiers)

Briefly introduced before, identifiers are your biggest help in structurising
a large piece of music.  As an example, we'll consider a string quartet.  
In short, it will look like this: verb(
    global = \notes{ }
    violinoOne = \notes \relative c { .. }
    violinoTwo = \notes \relative c { .. }
    viola = \notes \relative c { .. }
    violoncello = \notes \relative c { .. }
)

The code(\global) part contains everything that is global, i.e., the
same, for each instrument.  This may include time signature, key, repeat
signs, different bar types, time signature- and key changes, rehearsal
marks, etc.

For each instrument, you'll have something vaguely resembling verb(
    violinoOneStaff = \type Staff = violinoOne <
        \property Staff.midi_instrument = "violin"
        \property Staff.instrument = "Violino I"
        \property Staff.instr = "Vl. I"
        \global
        \violinoOne
    >
)


[Versions, relative mode,
 barchecks, splitting of files]

subsect(Grouping of staffs)

subsect(Versioning)

sect(Titling)
label(tutorial:titling)

A piece of sheet music isn't complete without proper opening and
closing titles.  LilyPond does not have any real support for setting
text: that is a job best left to TeX().  But you can pass messages to
TeX() from the input file.   You can  write TeX() macros to handle
these messages.
To do this, you add a code(\header) block
to your input file.  The format is quite simple,

verb(
\header{
    "key" =  "value";
    "key" =  "value";
    "key" =  "value";
    % etc.
})

When  the results of the music typesetting are output, the contents of
code(\header) are also up into the TeX() file.  Tools like
code(ly2dvi) can use this information to generate pretty titling for
your input file. Consult the manual page of code(ly2dvi) for more
details.


The code(\header) block should be at toplevel in mudela, and
preferably at the top of the file.  If you have an input file  with
multiple code(\score) blocks, you should add a header to every score,
describing the different sub parts of the music piece, eg.


verb(\header {
        "composer" = "Ludwig Van Bavaria";
        "title" = "Symphonie Megalomane";
    }
    \score{
       ... % some music
       \header { movement = "Mit roher Kraft wild herausfahrend!"; }
      \paper { }
    }
    \score{
       ... % some more music
       \header { movement = "Saut\'e comme un oeuf."; }
      \paper { }
    }
)

If you want you can also put the code(\header) block at the top of the
input file; it will then be put into every output file automatically.
This will make it clear what the file contains as soon as you open it.