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

mailto(gnu-music-discuss@gnu.org)
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

pipethrough(date) sucks.

paragraphs have too much space.

)

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 -- Using LilyPond to typeset music)
      (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)
  
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).  This document is a gentle introduction to that
language, which is called Mudela, an abbreviation for Music Definition
Language.

We will demonstrate the working of Mudela by presenting  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 a convoluted version
of one of the menuets in bind(J.)bind(S.)Bach's em(Clavierbuchlein).

mudela(verbatim)(
% lines preceded by a percent are comments.
\include "paper16.ly"
\score {
    \notes                      
    \relative c'' {             
            \key g;
            \time 3/4;          

        \repeat "semi" 2 {
            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.  |
        }

        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-.
        g4 fis e |
        fis a,  r8 cis8
        d2.-\fermata
        \bar "|.";
    }
    \paper {
       linewidth = 14.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 code(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, issue the command code(xdvi menuet).  Now that we
are familiar with the procedure to view the output, we will analyse
the input itself, line by line.

verb(% lines preceded by a percent are comments.)COMMENT(

)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(\input "paper16.ly")

By default, LilyPond will use definitions for a staff of 20
nop(point)footnote(A point is the standard measure of length for
printing.  One point is 1/72.27 inch.)

high.  If you want smaller output (e.g., 16 point), you have to import
the settings for that size.  You can do this by including a file.
code(\include "file") is replaced by the contents of code(file).
LilyPond will inspect the standard search to look for the requested 
file.COMMENT(

)verb(\score {
) COMMENT( 

) 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               
) COMMENT( 

)This makes LilyPond ready for accepting notes.
verb(
    \relative c''
)COMMENT(

) 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 (`code(')') 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 extra octave.  Because the first note obviously has no predecessor,
you have to give the (absolute) pitch of the note to start with.
COMMENT(

)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.  Although
this command comes after the code(\time) command, in the
output, the key comes before the time signature: LilyPond knows about
music typesetting conventions.
verb(
        \repeat 2 {
) COMMENT(

) This command tells LilyPond that the enclosed piece of music must
be played twice.
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 
designates the duration of the note (it is a quarter note). COMMENT(

)verb(
        a b
)COMMENT(

)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.  You would then enter
code(a8 b8)) COMMENT(

)verb(
          d4 g, g |
) COMMENT(

) Three more notes:  The code(|) is a ``barcheck''.  When processing the
music, LilyPond will check  that barchecks are found at the start of
a bar.  This can help you track down notes you forgot to enter. 
verb(
        e'4 c8 d e fis
) COMMENT(

) So far, no notes were chromatically 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.
verb(
        c4 d8( )c b a( )b4 c8 b a g |
) COMMENT(

) The next line shows something new: In mudela, one enters a slur by
marking the beginning and ending note of the slur with an opening and
closing parenthesis respectively.  In the line shown above this is
done for two slurs.  Note that parentheses (slur markers) are between
the notes.  As you can see, parentheses do not have to nest.
verb(
        a4 b8 a g fis g2.  |
) COMMENT(

) A duration that is to be augmented with a duration dot, is notated
with a duration number followed by periods, as many as you want
augmentation dots.
verb(
        }
) COMMENT(

) The end of the repeated music.  LilyPond will typset a repeat bar.
verb(
     cis'4 b8 cis a4 |
) COMMENT(

) 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 one without.  COMMENT(

)verb( a8-. b-. cis-. d-. e-. fis-. % try some super and subscripts.)COMMENT(

)There is more to music than  pitches and rhythms.  An important
aspect is articulation.  You can enter articulation signs either in an
abbreviated form, by a dash and the the character for the
articulation to use,  e.g. code(-.) for staccato as shown above.
COMMENT(

)verb(
        fis a,  r8 cis8
) COMMENT(

)
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
) COMMENT(

) All articulations have 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) names that description and is therefore called an
em(identifier).

verb(
        }
) COMMENT(

)
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(
        }
)COMMENT(

)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, instead
of symbols and positions.  Second, the format tries to be
em(context-free): a note will sound the same regardless of the current
time signature, the key nop(etc.)

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

As you can see, the most interesting part 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 {  }
})COMMENT(

) we will leave out the the repetitive details for now and only 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 { \type "Score_engraver";
                            \name "Score";
                            \consists "Note_heads_engraver";
                            \consists "Stem_engraver";
                            \consists "Rhythmic_column_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 (sunken apostrophes) should be added, e.g., the C in the
``contra octave'' is expressed as code(c,,).

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' nop(suffix.)  footnote(Variations on this
convention are used in a number of germanic languages, notably Dutch,
German, Swedish, and Norwegian.) 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})

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

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. 

subsect(Where the chords have no names)
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  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'>
  }
)

There is one thing to note, in sequences of chords, the (relative)
pitch of a is taken with reference to the first note of the previous
chord.

You can nest simultaneous and sequential music in any way you want,
e.g., COMMENT(

)mudela(verbatim,fragment,center)(
        < { g''4 g''4 }
          { c'8 <c' e'> c' <c' e'> } >
)COMMENT(

)
As you can see, LilyPond has  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).

[Chords and relative mode]

subsect(Chords with names)

In the previous section we have been talking more about `stacked notes'
rather than `chords'.
If you need to enter a lot of chords that have proper names, you can use 
the code(\chords) mode as an alternative:
COMMENT(
)mudela(verbatim,fragment,center)(
    \chords\transpose c''{ c1 d e }
) 
COMMENT( URG?
    \chords\relative c''{ c1 d e }
)

subsect(Names with chords)

A more common problem is the typesetting of chord names.  LilyPond has
a special kind of staff for this, the code(ChordNames) staff.  
The code(ChordNames) staff accepts music like a normal staff, 
but typesets only the name of each chord:
COMMENT(

)mudela(verbatim,center)(
\score{
  \context ChordNames {
    \chords
      { c1 d-min e-maj5+.9 }
    \notes\relative c
      { <c1 es g> }
  }
  \paper{
    linewidth=-1.0;
  }
}
) Because the ChordNames staff accepts normal music, it can be transposed,
and you may enter it any way you like, either as chords or as notes.

sect(Adding nuances: articulation and dynamics)

Music can have articulation, dynamics (louder and softer), etc.  These
aspecs have notation, so LilyPond can print those.  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. COMMENT(

)mudela(fragment,verbatim)(
  c''4-\staccato
  c''4-\tenuto )COMMENT(

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

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

)Text and digits for fingering can be entered in the same manner: add a
dash and the text or digit to be printed:
COMMENT(

)mudela(fragment,verbatim)(c''4-1 g''4-5 c''-"Sul tasto" )
COMMENT(Currently, the meaning of the
syntax `note-dash-digit/articulation/text' is  ``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.)COMMENT(

)mudela(verbatim,fragment)(
  c4 \ff c4 \fp c4 c4 \ppp c4 c4 \sfz
)COMMENT(
UGH

)

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

Music typesetting does not use fixed symbols only.  A lot of symbols
are variable: they 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.  These are the spanners that are entered like
this:

description(
dit(Slur)
 The slur has the opening parenthesis as 
start marker is.  The stopping marker is the closing parenthesis.
For example:
mudela(fragment,center,verbatim)( c'4( )c'4 )

The slur is 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 
)

dit(Beam)

The starting marker for the beam is the opening bracket, the ending
marker is the closing bracket.  The brackets have to be em(around) the
beamed notes.  footnote(Strictly speaking, a beam is not a musical
concept: beaming doesn't change the meaning of music, it only
clarifies the rhythmic structure.  One might argue that beams should
not be present in a music representation language.  Unfortunately,
LilyPond is not smart enough to insert beams into music on its own.

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

mudela(fragment,verbatim)(
[c'8 c'] [c'16 c' c' c'] [c'16. c'32 c' c'16.]
)

The brackets themselves have no duration, so they are grammatically
equivalent to the barcheck.

dit(Tie) LilyPond's tie is entered as a tilde, `code(~)', in analogy
 with TeX()'s tie (which ties together words with a space), The tie is
 similar to the slur: it looks like a slur, but a slur connects whole
 chords, whereas the tie connects note heads.  

The following example demonstrates the use of ties:
mudela(fragment,verbatim,center)(
  c''1 ~ c''4
  <c'2.  g' es''> ~ <c'4 g' es''> 
)

Since the tie is thought to be inbetween the notes, it has no
duration, and is grammatically equivalent to the barcheck.

dit(Hairpins)
Crescendi and decrescendi can be printed in hairpin style.  The
starting marker for the crescendo is code(\<), and for the decrescendo
code(\>).  Both have code(\!) as the ending marker.
mudela(fragment, verbatim)(
   \relative c'' { c4 \< \! c4 \> \! c2
      < c1
        { s4 \< \! s4 \> \! s2 } > }
)
This example shows a trick: by attaching the markings to space rests
that run parallel to the whole note, you can have dynamic markings
within a note. 

)

It is your job to make sure that each spanner that you start, also
ends.  If it doesn't, then Bad Things are likely to happen. If you end
spanners that are not started, LilyPond will warn you about illegal
ending markers.

sect(Commands)
label(sec:commands)

Music notation constructs with no duration, like clefs and key
signatures, can be entered by inserting various
commands between the music.  The general form of these commands is
COMMENT(

)center(code(\keyword argument argument ... ;))COMMENT(

)These are the commands that are currently supported in alfabetic order:
description(
dit(code(\bar) var(bartype))
  This command makes LilyPond 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.
COMMENT(

)mudela(fragment,verbatim)(
    \bar "|:"; c'4 \bar ":|:";    c'4  \bar ":|";  c'4 \bar "||";
    c'4 \bar "empty"; c'4 \bar "|.";
)COMMENT(

)The command `code(\bar "empty")' does not create any visible bar
  line, but it tells LilyPond to allow a linebreak at that position.
  The `code(\bar)' command prints the specified symbol where you enter
  it.  If you give a `code(\bar)' command at the end of a measure then
  the specified symbol replaces the automatic bar line.
  
  The code(\bar) command does not affect metric structure.

dit(code(\cadenza) var(togglevalue)) This command toggles the
automatic printing of barlines.  `code(\cadenza 1)' turns off the
automatically generated bar lines.  They are switched on again with
`code(\cadenza 0)'. Then a bar line is printed, and LilyPond will act
as if you are again at the start of a measure.


This is useful when typesetting music without a meter (such as an ad
 libitum cadenza).

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 an integer. Useful values are
  available as the predefined identifiers code(\major) and
  code(\minor).  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.
  The default value for this time signature is common time (4/4).

dit(code(\partial) var(duration))
  This command allows you to make
  upsteps at the start of a piece.
  The var(duration) argument has the same form as 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 
  )
)

The commands described above do not music that you could hear, but
within the language, they are "Music": they are grammatically
equivalent to notes, so they can appear in the same places as notes.

sect(Notation context)

COMMENT(This section is about translation contexts, a topic of LilyPond that
is  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 then?

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

But 
there is more to a staff than  the symbol.  A staff
contains---besides a staff symbol---  more components:
COMMENT(

)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)
) COMMENT(

)
To explain what a staff really is, we'll try to print music without
these components.   Without those, 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";
  }
 }
})COMMENT(

) As you can see, you 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.  Moreover, 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";
  }}
 }) COMMENT(

)Technically speaking you can find out where the strong and weak beats are, but
it is difficult to find them quickly.   Bar lines  help you in finding
the location  of the notes within the measure:
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";
  }
 }
})COMMENT(

)
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.;
  }
})COMMENT(

) Now you know the pitch of the notes: you look at the start of the line
and see a clef, and 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 writes notation, context works the
other way around for LilyPond: with context a piece of music can be
converted to notation.

We see that a staff forms context, and that context is needed to
convert between notation and music.  In LilyPond we turn around this
reasoning: LilyPond has a notion of notation context, and the staff is
an example of a notation context.  In fact, the arguments of the
code(\context) command (Staff, GrandStaff) were all names of different
contexts.  A notation context is a conversion between music and
notation.

We make one final observation before listing the standard notation
contexts: a score can contain many staffs and a staff can contain many
voices.  This suggests that notation contexts are objects that can
contain other notation contexts.

The following
 is a list in alfabetic order of the contexts that are supported by
LilyPond.  Each notation context is characterised by its name, the
notation elements it creates, and the contexts that it can contain.
description(


dit(GrandStaff) A code(GrandStaff) context contains code(Staff)
  contexts, and it adds a brace to the output at the
  nop(left.)footnote(The GrandStaff is limited, LilyPond can not do
  cross staff beaming and slurring.)

  A code(GrandStaff) context can contain 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(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
  in columns across staffs.
  
  The code(Score) can contain code(Staff), code(StaffGroup),
  code(Lyrics), code(GrandStaff) and code(RhythmicStaff) 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(Staff) The code(Staff) context handles clefs, bar lines, keys,
  accidentals.  A code(Staff) context can contain code(Voice)
  contexts.

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

COMMENT(do ChoireStaff)
)


If you are familiar with structured documents, 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.  The big difference with
stylesheets is that in music notation the elements provided by context
are essential to understanding what is notated.

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, and this
explains why they are fundamentally different from musical expressions
like notes and rests.

A notation context is not a primitive element of LilyPond: in
bind(Section)ref(tutorial:engravers) it will be explained how you can
form your own notation contexts.

sect(Nested music: multiple staffs)
label(tutorial:more-staffs)

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

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

In this example the music consists of two notes.  The above would
sound the same if it were written as a single chord on a single staff,
i.e., COMMENT(

)mudela(fragment)(
        <g4 e'4>
)COMMENT(

) 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(\context) construct.  The following input says
``the quarter note with pitch e should be put on a staff.''

verb(
  \context Staff e'4 
)COMMENT(

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

verb(
  \context Staff g4 
) COMMENT(

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

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

This looks reasonable, but the effect of this input is not what you
might expect:
mudela(fragment)(
  < \context Staff e'4
    \context Staff g4 
  >
)COMMENT(

) Since there are no names specified for the desired staffs, LilyPond
thinks your wishes are fullfilled by putting the code(g) on the same
staff as the code(e).  The correct solution is to label both staffs
with different names, for example code(trebleStaff) and
code(bassStaff).  This makes LilyPond distinguish between them, and
create two staffs:

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

) The names that you choose do not matter  as long as they are
different.  This is almost right, except for the brace at the left and
the clef of the second staff.  If you want a brace, then you have to
tell LilyPond that the chord you  formed is to be interpreted as a
so-called grand staff.  This is also done with the code(\context)
command.  The bass clef is made with a clef command:  COMMENT(

) mudela(verbatim,fragment)(
  \context GrandStaff <
        \context Staff = treblestaff e'4
        \context Staff = bassstaff { \clef "bass"; g4 }
  >)COMMENT(

)

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

In the section on notation contexts 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 a clef helps 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 notation contexts can have other
properties, that are settable in
a generic fashion.  We will demonstrate this feature by printing
multiple voices on a staff.

Printing more than one voice on a staff is like printing multiple
staffs stacked together.  This suggests that the template to follow is
this:COMMENT(

)verb(
  \context Staff <
    \context Voice = one  ...
    \context Voice = two  ...
  >
) COMMENT(

) On the ellipsis there should be music going from left to right, in
other words, notes enclosed in braces.  Let us try the following counterpoint:COMMENT(

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

As you can see the result is not  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.

To remedy this, engravers traditionally make 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, this property is a
property of the context code(Voice).  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:
verb(
  \property "Voice"."verticalDirection" = "1"
)

This command should be read as ``change the property called
code(verticalDirection) within the current code(Voice) context to the value
code(-1).''  For the property code(verticalDirection) the value code(1) means
`up', and code(-1) means `down'. So, 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)(
  \context "Staff" <
    \context "Voice" =  "one"  {
      \property Voice.verticalDirection = "1"
      r4 as'4 () as'4 g'4 }
    \context "Voice" =  "two"  {
      \property Voice.verticalDirection = "-1"
      g'2 f'4 e'4 }
  >
)
    latexcommand(\caption{Multiple voices})
    label(tutorial:multi-voice-fig)
latexcommand(\end{figure})

As you can see, this property also controls the directions of slurs.

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) and the reference manual contain explanations
of all properties.

sect(Lyrics)
label(tutorial:lyrics)

Since a lyrics can have durations  like notes, we consider them to
be music too.  Entering lyrics in mudela 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.  For entering lyrics we have to instruct LilyPond that what
we enter are not note names but strings.  This instruction is the
keyword code(\lyrics).  After entering this keyword you can enter a
musical construct---sequential music, simultaneous music, code(\context)
entries, etc.--- but with syllables instead of pitches.  For example:
COMMENT(

)verb(\lyrics { 'got8 me on my knees4, Le-8 lie! })COMMENT(

) 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 overridden
with a code(\context) keyword.  Printing syllables of text in a line is
done by a context called code(Lyrics).  You can select this context
with the code(\context) keyword.  Here is a simple example with output:
COMMENT(

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

)The result is technically correct, but it needs a melody to make it
perfor0mable: COMMENT(

)mudela(fragment,verbatim)(
  <
    \context Staff  { 
      \property Voice.beamAuto = "0" % no beams in melody
      c''8. c''16 bes'8. a'16 g'4 f'8 g'4. 
    }
    \context Lyrics \lyrics { 'got8. me16 on8. my16 knees,4 Le-8 lie!4. }
  >
) COMMENT(

) 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.   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
double quotes. It ends with either a number for the duration, or a space.
These tricks are demonstrated in the following example:
COMMENT(

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

)mudela(fragment,verbatim)(<
  \context Staff  { 
    \property Voice.beamAuto = "0" % no beams in melody
    c''8. c''16 bes'8. a'16 g'4 f'8 g'4. 
  }
  \context Lyrics \lyrics { 'got8 me8 on8. m$\cal_Y$16 "3s,"4 Le-8 lie!4.}
>
)COMMENT(


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

sect(Toplevel Mudela)

Back in bind(Section)ref(sec:firsttune) we said we would ignore
toplevel constructions (e.g., code(\score)) until a later moment.
Now we will look at these constructions.


Mudela allows you to name constructs of the language.  This is done by
using an em(identifier). 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 \context GrandStaff <
      { c''2 g''2 }
      { \clef bass; \czerny \czerny \czerny \czerny}
    >
    \paper {
      linewidth = -1.0;
    }
  }
)

You can also see identifiers in action within the code(\paper) block:
the value code(-1.0) is assigned to code(linewidth).  Within the
code(\paper) block, identifiers are not used as abbreviation only:
assigning to some  identifiers can influence the output: in this case,
the music line is printed at natural width.  

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.verticalDirection = "1"
stemdown = \property Voice.verticalDirection = "-1"
shift = \property Voice.hshift = "1"
\score {
  \context "Staff" \notes <
    \context "Voice" =  "one"  { \stemup r4 as'4 () as'4 g'4 }
    \context "Voice" =  "two"  { \stemup \shift g'2 f'4 e'4 }
    \context "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 like code(\clef) or code(\bar).  Real commands are
hardcoded into the language and they have to be terminated by
semicolons.

sect(Sound output)
label(tutorial:sound)

You get output by combining music with definition a conversion to
output.  LilyPond currently supports one other conversion besides
notation: 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 result is not very pretty, but it is useful
for prooflistening your files: typing errors stand out when you
listen, especially if they involve accidentals.

The only information that you need to enter is the
tempo (Unfortunately, at this time, this the only thing that can be
tuned.).  The syntax for the tempo is code(\tempo )var(duration) =
var(beatsperminute);, for example: COMMENT(

)verb(
\score {
   ...music...
   \midi { \tempo 4 = 76; }
}) COMMENT(

)

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()has a name
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 define a name
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.
)

LilyPond can create notation for a large number of symbols.  This code
is split up into basic building blocks. Each building block is called
an em(engraver), and an engraver generally handles only one notation
construct: the code(Clef_engraver) takes care of the clefs, the
code(Time_signature_engraver) takes care of printing time signatures,
etc.

A notation context is formed by a group of engravers.  A special class
in LilyPond---the code(Engraver_group_engraver)---allows engravers to
cooperate in a group, thus forming a notation context.  A variant of
this grouping object is the code(Line_group_engraver_group), which
puts the output of all the engravers (clefs, bars, etc) into a
compound object, so that these symbols can be treated as a whole.

The following definition shows a simplified Staff context: COMMENT(

)verb(
\translator
{
        \context "Line_group_engraver_group";
        \name Staff ;

        \consists "Bar_engraver";
        \consists "Clef_engraver";
        \consists "Key_engraver";
        \consists "Local_key_engraver";
        \consists "Time_signature_engraver";
        \consists "Staff_symbol_engraver";

        defaultClef = treble;
          
        \accepts "Voice";
}) COMMENT(

) This context, named Staff, puts its graphic objects into a compound
object (a so-called ``Line group'').  At Staff level, bars, clefs,
keys, accidentals, time signatures and the staff symbol are handled.
A staff can contain a Voice context.  You can also preset properties
of contexts: for instance, the clef that is printed upon starting a
Staff, is the treble clef.



As a practical example, we will show 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.  This
is done by having only one administration for timing information: in
the default configuration there is only one code(Timing_engraver), in
the code(Score) context.

All staffs use the information in the code(Timing_engraver) for
generating bar lines and time signatures.  So, we can have different
timing for every staff, by moving the code(Timing_engraver) into the
 Staff context.

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


mudela(verbatim)(
  \score {
   \notes <
     \context Staff = one { \time 2/4; c'4 c'4 c'4 c'4 c'4 c'4 }
     \context Staff = two { \time 3/4; c'4 c'4 c'4 c'4 c'4 c'4 }
   >
   \paper { 
     linewidth = -1.;
     \translator {
       \ScoreContext
       \remove "Timing_engraver";
     }
     \translator {
       \StaffContext
       \consists "Timing_engraver";
     }
  }
}
)

The context definitions provided as a default are 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)(
  <
    \context Staff = one { c''4 \context Staff = two { c4 c4 } c''4 }
    \context Staff = two { \clef bass; g,4 g,4 g,4 g,4  }    
  >
)



The mechanism of context selection can be used to fabricate an
nop(Urtext)footnote(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 
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.  ) and an edited edition from em(one source).  We
will use the first few bars of bind(J.)bind(S.)Bach's first Cello
suite to demonstrate this.  The example makes heavy use of space
rests; here they are used as a placeholder to attach articulation
marks to.  

mudela(verbatim)(
  bach =  \notes \relative c { g16 d' b' a b d, b' d, }
  bachBeams = \notes { [s4] [s4] }
  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{

    
    { < 
        \context Voice = celloVoice { \bach \bach}
        \context Voice = celloVoice < { \slursOne \slursOne }
              { \bachBeams \bachBeams } >       
        \staffStuff
      >
      <
        \context Voice = celloVoice { \bach \bach }
        \context Voice = celloVoice < { \slursTwo \slursTwo }
              { \bachBeams \bachBeams } >
        \staffStuff
      >
    }
    \paper { linewidth = -1.;}
  }
)

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)


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 it
with the keyword code(\transpose) along with the pitch (relative to
the central C, i.e., code(c')) for the transposition.footnote(the
code(\context 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 {
    \context 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 = \context Voice = voiceA \notes { c''4 c4 c4 c''4 }
bVoice = \context Voice = voiceB \notes { g,4 g,4 g,4 g,4  }    

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

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

If you want to switch staffs you are in the middle of a slur or a
beam, you should take special precautions.  In the paper block,
you must tell how far the staffs will be apart:
mudela(verbatim,center)(
\score{
  \context GrandStaff <
    \context Staff=one \notes{ s2 }
    \context Staff=two \notes\relative c{
      \time 4/8;
      \clef "bass";
      \stemup [c8( e
        \translator Staff=one \stemup 
      g )c]
    }
  >
  \paper {
    linewidth=-1.0;
    % slur damping gets confused
    slur_slope_damping = 100.0;
    \translator{
      % we're using a grand staff
      \GrandStaffContext  
      minVerticalAlign = 3.0*\staffheight;
      maxVerticalAlign = 3.0*\staffheight;
    }
  }
}
)
as LilyPond cannot determine the interstaff distance.

sect(Tuplets)

The notes in a triplet take 2/3 of their notated duration.  The syntax
for triplet in LilyPond reflects this.  To make a triplet, you enter
COMMENT(

)mudela(verbatim,fragment,center)(
        \context Voice \times 2/3 { c''4 c''4 c''4 }
)COMMENT(

)Since tuplet brackets are printed by the Voice context, a Voice
context must exist before code(\times) is interpreted.  To ensure this,
a context is instantiated explicitly with code(\context Voice).  You
don't need this, if a Voice context is already instantiated, like in
the following example:
COMMENT(

)mudela(fragment,verbatim,center)(
        c''4 \times 2/3 { c''4 c''4 c''4 } c''4
)COMMENT(

)

Of course, you can also use different ratios, and use beamed notes or
rests:
COMMENT( BROKEN

lilypond: score-element.cc:134: class Paper_def * Score_element::paper() const: Assertion `pscore_l_' failed.

mudela(fragment)(
        \context Voice \times 4/5 { [c''8 c''16 c''16] r8 [g'8 g'8] }
)
)
If you make a tuplet of  beamed notes, where the beam is as wide as
the bracket, the bracket is omitted.

sect(Repeats)

A repeated piece of music can consist of two parts: one part to be 
repeated, and optionally, a list of alternative endings:
COMMENT(
)mudela(verbatim,fragment,center)(
    \relative c'{
        \time 2/4;
        g' a
        \repeat 2 { b c }
        \alternative { 
            { d c } { d e }
        }
        f g
    }
) The number code(repeat-count) defines how many times the piece should be 
played.  You may leave out the code(\alternative) part.  There must not 
be more alternative endings than the code(repeat-count).

A less intuitive form may be needed for lyrics, when there are
a couple alternatives, but nothing is repeated.  The code(\repeat) command
must be present, but it may specify an empty music list:
COMMENT(
)mudela(verbatim,fragment,center)(
    \context Lyrics \lyrics {
        \repeat 2 { }
        \alternative < 
            { Let's not sing 
              this twice } 
            { Rather sing 
              this in- stead } 
        > 
    }
)