@c -*-texinfo-*-
-@c TODO: LilyPond LilyPond LilyPond
+@c TODO:
+@c * more details about running lilypond; error messages,
+@c compiling/viewing (emacs?)
+@c * where to go from First steps+More basics?
@node Tutorial
@chapter Tutorial
-@html
-<!--- @@WEB-TITLE@@=Tutorial --->
-@end html
+
+
+Using LilyPond comes down to encoding music in an input file. After
+entering the music, the program is run on the file producing output
+which can be viewed or printed. In this tutorial, we will show step
+by step how to enter such files, by showing fragments of input and the
+corresponding output. At the end of every section, a paragraph will
+list where to find further information on the topics discussed.
+
+Many people learn programs by trying and fiddling around with the
+program. This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image.
+@ifhtml
+For example, consider the following input:
+@c TODO: intertext fixme
+@lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
+ c'^\markup { \bold \huge { Click on this image! } }
+@end lilypond
+
+@end ifhtml
+By cutting and pasting the full input into a test file, you have a
+starting template for experiments. If you like learning in this way,
+you will probably want to print out or bookmark
+@ifhtml
+the
+@end ifhtml
+@ref{Cheat sheet}, which is a table listing all commands for quick
+reference.
+
+
+This tutorial starts with a short introduction to the LilyPond music
+language. After this first contact, we will show you how to to
+produce printed output, normally using the program @code{ly2dvi}. You
+should then be able to create and print your first sheets of music.
@menu
-* First steps:: Music language of LilyPond
-* Running LilyPond:: Printing music
-* More basics::
+* First steps:: Music language of LilyPond.
+* Running LilyPond:: Printing music.
+* More about pitches and accidentals::
+* Octave entry::
+* Combining music into compound expressions::
+* Adding articulation marks to notes::
+* Combining notes into chords::
* Printing lyrics::
-* A melody with chords ::
-* More stanzas::
-* More movements :: Joining separate pieces of music
-* A piano excerpt:: Piano music
-* Fine tuning a piece::
-* An orchestral score:: Conductor's score and individual parts
-* Integrating text and music:: Integrating text and music
-* End of tutorial:: The end
+* A lead sheet::
+* Listening to output::
+* Titling::
+* Single staff polyphony::
+* Piano staves::
+* Setting variables::
+* Fine tuning layout::
+* Organizing larger pieces::
+* An orchestral part::
+* Integrating text and music:: Integrating text and music.
@end menu
-Operating lilypond is done through text files: to print a piece of
-music, you enter the music in a file. When you run lilypond on that
-file, the program produces another file which contains sheet music that
-you can print or view.
-
-This tutorial starts with a small introduction to the LilyPond music
-language. After this first contact, we will show you how to run
-LilyPond to produce printed output; you should then be able to create
-your first sheets of music. The tutorial continues with more and more
-complex examples.
@node First steps
@section First steps
-We start off by showing how very simple music is entered in
-LilyPond: you get a note simply by typing its note name, from
-@code{a} through @code{g}. So if you enter
-@quotation
+We start off by showing how very simple music is entered in LilyPond:
+you get a note simply by typing its note name, from @samp{a}
+through @samp{g}. So if you enter
+
@example
c d e f g a b
@end example
-@end quotation
+
+@noindent
then the result looks like this:
-@quotation
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\transpose c'' { c d e f g a b }
-@end lilypond
-@end quotation
-@separate
-We will continue with this format: first we show a snippet of input,
-then the resulting output.
+@c ?
+@c \transpose c c' { c d e f g a b }
+@c @lily pond[notime]
+@c \property Score.timing = ##f
+@lilypond[notime, relative=2]
+c d e f g a b
+@end lilypond
-The length of a note is specified by adding a number, ``@code{1}'' for a
-whole note, ``@code{2}'' for a half note, and so on:
+The length of a note is specified by adding a number, @samp{1} for a
+@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
-@quotation
@example
a1 a2 a4 a16 a32
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
+@lilypond[notime]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
\property Staff.autoBeaming = ##f
-%\property Staff.Clef = \turnOff
-\transpose c'' { a1 a2 a4 a16 a32 }
-s16_" "
+\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
@end lilypond
-@end quotation
-@separate
-If you don't specify a duration, the previous one is used:
-@quotation
+If you do not specify a @rglos{duration}, the previous one is used:
+
@example
a4 a a2 a
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
+@lilypond[notime]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-%\property Staff.Clef = \turnOff
-\transpose c'' { a a a2 a }
-s16_" "
+\transpose c c' { a a a2 a s16_" " }
@end lilypond
-@end quotation
-@separate
-A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
-(@texiflat{}) by adding ``@code{es}''. As you would expect, a
-double-sharp or double-flat is made by adding ``@code{isis}'' or
-``@code{eses}'':
+Rests are entered just like notes, but with the name ``@code{r}'':
+
+@cindex rests
@quotation
@example
-cis1 ees fisis aeses
+r2 r4 r8 r16
@end example
@lilypond[fragment]
\property Score.timing = ##f
+\property Staff.Clef = \turnOff
\property Staff.TimeSignature = \turnOff
-\transpose c'' { cis1 ees fisis aeses }
+r2 r4 r8 r16
s16_" "
@end lilypond
@end quotation
@separate
-Add a dot ``@code{.}'' after the duration to get a dotted note:
-@quotation
+
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
+
@example
a2. a4 a8. a16
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
+@lilypond[notime]
\property Score.timing = ##f
-\property Staff.TimeSignature \set #'transparent = ##t
-%\property Staff.Clef = \turnOff
-\transpose c'' { a2. a4 a8. a16 }
-s16_" "
+\transpose c c' { a2. a4 a8. a16 s16_" " }
@end lilypond
-@end quotation
-@separate
-The meter (or time signature) can be set with the @code{\time} command:
-@quotation
+The @rglos{meter} (or @rglos{time signature}) can be set with the
+@code{\time} command:
+
@example
\time 3/4
\time 6/8
@end example
@c a clef here may lead to confusion
-@lilypond[fragment]
+@lilypond
\property Staff.Clef \set #'transparent = ##t
\time 3/4
s4_" "
\time 4/4
s16_" "
@end lilypond
-@end quotation
-@separate
-The clef can be set using the ``@code{\clef}'' command:
+
+The @rglos{clef} can be set using the @code{\clef} command:
@c what is more common name treble or violin?
@c in Dutch, its violin.
-@c in English its definately treble.
-@quotation
+@c in English its definitely treble.
@example
\clef treble
\clef bass
\clef tenor
@end example
-@lilypond[fragment]
+@lilypond[notime]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
\clef violin
s4_" "
\clef bass
\clef tenor
s16_" "
@end lilypond
-@end quotation
-@separate
-@c From these commands and notes, a piece of music can be formed. A piece
-@c of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
-@c rephrased:
-With these commands you can now write a piece of music. The next step
-is to enclose your music inside ``@code{\notes @{ .. @}}''.
-This lets LilyPond know that music (and not lyrics, for example) follows:
+Notes and commands like @code{\clef} and @code{\time} , are enclosed
+in @code{\notes @{@dots{}@}}. This indicates that music (as opposed
+to @rglos{lyrics}) follows:
-@quotation
@example
\notes @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
@}
@end example
-@end quotation
-@separate
-
Now the piece of music is almost ready to be printed. The final step is to
combine the music with a printing command.
-The printing command is the so-called ``@code{\paper}'' block. Later on
-you will see that the @code{\paper} block is used to customize
-printing specifics. The music and the @code{\paper} block are combined by
-enclosing them in ``@code{\score @{ ... @}}''. This is what a full
-LilyPond source file looks like:
+The printing command is the so-called @code{\paper} block. The
+@code{\paper} block is used to customize printing specifics, but we
+accept the defaults for now. The music and the @code{\paper} block
+are combined by enclosing them in @code{\score @{ ... @}}. The
+following is a complete and valid input file.
-@quotation
@example
\score @{
\notes @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
@}
\paper @{ @}
@}
@end example
-@lilypond
+@lilypond[noindent]
\score {
\notes {
\time 3/4
\clef bass
c2 e4 g2.
- f4 e d c2.
+ f4 e d c2 r4
+ }
+ \paper {
+ linewidth = 55 * \staffspace
}
- \paper { linewidth = 60 * \staffspace }
}
@end lilypond
-@end quotation
-@separate
+
+During the rest of the tutorial, we will often leave out @code{\score}
+and @code{\paper}, for clarity. However, both must be present when
+feeding the file to LilyPond.
+
+More elaborate information on entering pitches and durations is in
+@ref{Pitches} and @ref{Durations}. Clefs are fully explained in
+@ref{Clef}. Time signatures and other timing commands are described
+in @ref{Time signature}.
@node Running LilyPond
@section Running LilyPond
In the last section we explained what kind of things you could enter
-in a lilypond file. In this section we explain how to run LilyPond
-and how view or print the output. If you have not used LilyPond
-before, want to test your setup of LilyPond, or want to run an example
-file yourself, read this section. Most of the instructions that follow
-are for running LilyPond on Unix-like systems. Some additional
-instructions for running LilyPond on Windows are given at the end of
-this section.
-
-Begin by opening a terminal window and starting a text editor.
-For example, you could open an xterm and execute @code{joe}. In your
-text editor, enter the following input and save the file as
+in a LilyPond file. In this section we explain what commands to run
+and how to view or print the output. If you have not used LilyPond
+before, want to test your setup, or want to run an example file
+yourself, read this section. The instructions that follow are for
+Unix-like systems. Some additional instructions for Microsoft Windows
+are given at the end of this section.
+
+Begin by opening a terminal window and starting a text editor. For
+example, you could open an xterm and execute
+@code{joe}.@footnote{There are macro files for VIM addicts, and there
+is a @code{LilyPond-mode} for Emacs addicts. If it has not been
+installed already, then refer to the file @file{INSTALL.txt}}. In
+your text editor, enter the following input and save the file as
@file{test.ly}:
@quotation
LilyPond is the program that computes the sheet music. All other
things, such as adding titles, page breaking and other page layout,
are done by a small wrapper program called
-@code{ly2dvi}. @code{ly2dvi} calls lilypond to render the music, and
+@code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
then adds the titling and page layout instructions. To process
-@file{test.ly} with ly2dvi, proceed as follows:
+@file{test.ly} with @code{ly2dvi}, proceed as follows:
@quotation
@example
-ly2dvi -P test.ly
+ly2dvi -p test.ly
@end example
@end quotation
-You will see the following on your screen:
+You will see something resembling:
@quotation
@example
-GNU LilyPond 1.6.0
+GNU LilyPond 1.8.0
Now processing: `/home/fred/ly/test.ly'
Parsing...
Interpreting music...[1]
@emph{ ... more interesting stuff ... }
-PS output to `test.ps'...
+PDF output to `test.pdf'...
DVI output to `test.dvi'...
@end example
@end quotation
@cindex Viewing music
@cindex xdvi
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
-You can view the PS file using the program ghostview. If a version of
-ghostview is installed on your system, one of these commands will
-produce a window with some music notation on your screen:
-@c eeek
+The result of the ly2dvi is the file @file{test.pdf}.@footnote{For
+@TeX{} afficionados, there is also a @file{test.dvi} file. It can be
+viewed with @code{xdvi}. The DVI uses a lot of PostScript specials,
+which do not show up in the magnifying glass. The specials also mean
+that the DVI file cannot be processed with @code{dvilj}. Use
+@code{dvips} for printing.
+@cindex dvips
+@cindex dvilj
+@cindex DVI driver
+} One of the following commands should put the PDF on your
+screen:
@quotation
@example
- gv test.ps
- ghostview test.ps
- ggv test.ps
- kghostview test.ps
+ gv test.pdf
+ ghostview test.pdf
+ ggv test.pdf
+ kghostview test.pdf
+ xpdf test.pdf
+ gpdf test.pdf
+ acroread test.pdf
+ gsview32 test.pdf
@end example
@end quotation
If the music on your screen looks good, you can print it by clicking
-File/Print inside ghostview.
-
-The DVI file (@file{test.dvi}) contains the same sheet music in a
-different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker. You can run @code{xdvi test.dvi} or
-@code{kdvi test.dvi} to view the DVI file. In Xdvi, the mouse buttons
-activate magnifying glasses. Unfortunately, variable symbols (such as
-beams and slurs) are not displayed in the magnifying glasses.
+File/Print inside your viewing program.
-If your DVI viewer does not have a "Print" button, you can print the
-file by executing @code{lpr test.ps}.
-
-@c volgende alinea schrappen?
-
-If your system does not support printing PostScript files, then you
-can install GhostScript, a PostScript emulator. Refer to
-GhostScript's website at @uref{http://www.ghostscript.com}.
-
-@cindex GhostScript
+@cindex Ghostscript
@cindex @code{lpr}
@cindex Printing output
@cindex PostScript
@cindex PDF
-A final option is to use the popular PDF format. You can get a PDF
-file by running @code{ly2dvi --pdf test.ly}. With @code{--pdf}
-you will get DVI, PS and PDF files. Viewers for PS files also
-accept PDF files, but there are also many other applications for
-viewing PDF files.
-
-If you are familiar with @TeX{}, be warned: do not use other
-DVI drivers like @code{dvilj}. The @TeX{} coming out of LilyPond
-uses embedded PostScript code and will not render correctly if
-you use anything other than @code{dvips}.
-
-@cindex dvips
-@cindex dvilj
-@cindex DVI driver
-
-@unnumberedsubsec Windows users
-Windows users can start the terminal by clicking on the LilyPond or
-Cygwin icons. You can use any text editor (such as Notepad) to edit
-the LilyPond file. Viewing the PS file can be done with:
-@quotation
-@example
-@code{gsview32 test.ps}
-@end example
-@end quotation
-You can also print from the command line by executing:
-@quotation
-@example
-@code{gsview32 /s test.ps}
-@end example
-@end quotation
-
-
-@strong{SUMMARY}
-
-To run LilyPond, input a text file, then run the command @code{ly2dvi} on
-that file. The resulting files are either DVI or PostScript, and can
-be viewed with @code{xdvi} (unix) and ghostview (unix and windows)
-respectively. The following table summarizes the constructs that were
-discussed in the previous two sections.
-
-@multitable @columnfractions .3 .3 .4
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-@item @code{1 2 8 16}
-@tab durations
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c1 c2 c8 c16
-@end lilypond
-
-@item @code{. ..}
-@tab augmentation dots
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c4. c4..
-@end lilypond
-
-@item @code{c d e f g a b }
-@tab scale
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c d e f g a b
-@end lilypond
-
-@item @code{\clef treble \clef bass }
-@tab clefs
-@tab
-@lilypond[fragment]
-\property Staff.TimeSignature \set #'transparent = ##t
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-@end lilypond
-
-@item @code{\time 3/4 \time 4/4 }
-@tab time signature
-@tab
-@lilypond[fragment]
-\property Staff.Clef \set #'transparent = ##t
-\time 3/4
-s4_" "
-\time 4/4
-s16_" "
-@end lilypond
-
-@end multitable
+On Windows, the same procedure should work, the terminal is started by
+clicking on the LilyPond or Cygwin icon. Any text editor (such as
+NotePad, Emacs or Vim) may be used to edit the LilyPond file.
-@node More basics
-@section More basics
-
-We continue with the introduction of the remaining musical constructs.
-Normal rests are entered just like notes, but use the name
-``@code{r}'':
-
-@quotation
-@example
-r2 r4 r8 r16
-@end example
+To view the PDF file, try the following:
+@itemize
+@item
+If your system has a PDF viewer installed, open
+@file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
+@file{test.pdf}.
+@item
+If you prefer the keyboard, you can also try the list of commands
+shown before. If none work, go to
+@uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
+@end itemize
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
-@end lilypond
-@end quotation
-@separate
+The commands for formatting and printing music on all platforms are
+detailed in @ref{Invoking LilyPond}.
-@c Tim wants to move this quotes example just before the: quotes-don't-work
-@c score, but we'd need to remove quotes from the other two (key and
-@c tie) examples...
+@node More about pitches and accidentals
+@section More about pitches and accidentals
-@c better to have this just before the `octaves are bad' snipped
-@c but we'd need to remove the ', from \key and tie
-To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a ``low quote'' @code{,}
-(a comma). Middle C is @code{c'}:
+A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
+@rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect,
+a @rglos{double sharp} or @rglos{double flat} is made by adding
+@samp{isis} or @samp{eses}:@footnote{This syntax derived from note
+naming conventions in Nordic and Germanic languages, like German and
+Dutch.}
-@quotation
@example
-c'4 c'' c''' \clef bass c c,
+cis1 ees fisis aeses
@end example
-@lilypond[fragment]
+@lilypond[notime]
\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-c'4 c'' c''' \clef bass c c,
+\transpose c c' { cis1 ees fisis aeses s16_" " }
@end lilypond
-@end quotation
-@separate
-A tie is created by entering a tilde ``@code{~}'' between the notes to
-be tied. A tie between two notes means that the second note must not be
-played separately; it just makes the first note sound longer:
-
-@quotation
-@lilypond[fragment,verbatim]
-g'4 ~ g' a'2 ~ a'4
-@end lilypond
-@end quotation
-@separate
+
+@cindex key signature, setting
-The key signature is set with the command ``@code{\key}'':
+The key signature is set with the command ``@code{\key}'', followed by
+a pitch and @code{\major} or @code{\minor}:
@quotation
@example
\key d \major
-g'1
+g1
\key c \minor
-g'
+g
@end example
@lilypond[fragment]
@end quotation
-@c bit on the long/complex/scary taste
-@c cheating a bit: two lines makes for a friendlier look
-This example shows notes, ties, octave marks, and rests in action.
+@cindex tie
+A tie is created by adding a tilde ``@code{~}'' to the first note
+being tied:
+@quotation
+@lilypond[fragment,verbatim,relative 2]
+g4-~ g a2-~ a4
+@end lilypond
+@end quotation
+@separate
+
+This example shows the key signature, accidentals and ties in action:
@quotation
@example
\score @{
\notes @{
\time 4/4
- \key d \minor
+ \key g \minor
\clef violin
- r4 r8 d''8 cis''4 e''
- d''8 a'4. ~ a' b'8
- cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
- cis''2 r2
+ r4 r8 a8 gis4 b
+ g8 d4.-~ d' e'8
+ fis4 fis8 fis8 eis4 a8 gis-~
+ gis2 r2
@}
\paper @{ @}
@}
@lilypond
\score {
- \notes {
+ \notes { \transpose c c' {
\time 4/4
+ \key g \minor
\clef violin
- \key d \minor
- r4 r8 d''8 cis''4 e''
- d''8 a'4. ~ a' b'8
- cis''4 cis''8 cis'' bis'4 d''8 cis'' ~
- cis''2 r2
- }
- \paper { linewidth = 50*\staffspace }
+ r4 r8 a8 gis4 b
+ g8 d4.-~ d e8
+ fis4 fis8 fis8 eis4 a8 gis-~
+ gis2 r2
+ }}
+ \paper { linewidth = #(* 50 staffspace) }
}
@end lilypond
@end quotation
+@cindex accidentals
+
+There are some interesting points to note in this example. Bar lines
+and beams are drawn automatically. Line breaks are calculated
+automatically; it does not matter where the lines breaks are in the
+source file. Finally, the order of time, key and clef changes is not
+relevant: in the printout, these are ordered according to standard
+notation conventions.
+
+Accidentals (sharps and flats) do not have to be marked explicitly:
+you just enter the pitch of the note, and an accidental is printed
+only when necessary. The flip side of this mechanism, is that you have
+to mark notes as sharp or flat, even when they do not get accidentals.
+For example, in this example:
+@lilypond[fragment]
+\clef bass
+\property Staff.TimeSignature = #'()
+\key cis \major
+cis dis eis fis gis ais bis
+@end lilypond
+no note gets an explicit accidental, but still you enter
+@example
+\clef bass
+\key cis \major
+cis dis eis fis gis ais bis
+@end example
+
+Adding all alterations explicitly might require some more effort when
+typing, but the advantage is that transposing is easier. It also makes
+it possible to use different conventions for when to print
+accidentals.
+
+@cindex beams, by hand
+Beams are drawn automatically, but if you do not like where they are
+put, they can be entered by hand. Mark the first note to be beamed
+with @code{[} and the last one with @code{]}:
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+a8[ ais] d[ es r d]
+@end lilypond
+@end quotation
+@separate
+
+Rests are described in full detail in @ref{Rests}.
+
+The notation manual discusses ties in @ref{Ties}.
+
+
+@node Octave entry
+@section Octave entry
+
+
+@c Tim wants to move this quotes example just before the: quotes-do not-work
+@c score, but we'd need to remove quotes from the other two (key and
+@c tie) examples...
+
+@c better to have this just before the `octaves are bad' snipped
+@c but we'd need to remove the ', from \key and tie
+To raise a note by an octave, add a high quote @code{'} (apostrophe) to
+the note name, to lower a note one octave, add a ``low quote'' @code{,}
+(a comma). Middle C is @code{c'}:
+
+@quotation
+@example
+c'4 c'' c''' \clef bass c c,
+@end example
+
+@lilypond[fragment]
+\property Score.timing = ##f
+\property Staff.TimeSignature = \turnOff
+c'4 c'' c''' \clef bass c c,
+@end lilypond
+@end quotation
+@separate
-@c accidentals...
-There are some interesting points to note in this example.
-Accidentals (sharps and flats) don't have to be marked explicitly: you
-just enter the note name, and LilyPond determines whether or not to
-print an accidental. Bar lines and beams are drawn automatically.
-LilyPond calculates line breaks for you; it doesn't matter where you
-make new lines in the source file. Finally, the order of time, key and
-clef changes is not relevant: lilypond will use standard notation
-conventions for ordering these items.
-
-The example also indicates that a piece of music written in a high
-register needs lots of quotes. This makes the input less readable,
-and is therefore also a potential source of errors.
-
-The solution is to use ``relative octave'' mode. In practice, this is
-the most convenient way to copy existing music. To use relative mode,
-add @code{\relative} before the piece of music. You must also give a
-note from which relative starts, in this case @code{c''}. If you don't
-use octavation quotes (ie don't add ' or , after a note), relative mode
-chooses the note that is closest to the previous one. Since most music
-has small intervals, you can write quite a lot in relative mode without
-using octavation quotes.
-@c don't use commas or quotes in this sentence
-For example: @code{c f} goes up; @code{c g} goes down:
+An example of the use of quotes is in the following Mozart fragment:
+@lilypond[singleline,fragment,verbatim]
+ \key a \major
+ \time 6/8
+ cis''8. d''16 cis''8 e''4 e''8
+ b'8. cis''16 b'8 d''4 d''8
+@end lilypond
+
+This example shows that music in a high register needs lots of quotes.
+This makes the input less readable, and it is a source of errors. The
+solution is to use ``relative octave'' mode. In practice, this is the
+most convenient way to copy existing music. To use relative mode, add
+@code{\relative} before the piece of music. You must also give a note
+from which relative starts, in this case @code{c''}. If you do not
+use octavation quotes (i.e. do not add ' or , after a note), relative
+mode chooses the note that is closest to the previous one.
+For example, @code{c f} goes up while @code{c g} goes down:
@quotation
@example
@separate
+Since most music has small intervals, in relative mode pieces can be
+written almost without using octavation quotes. In relative mode, the
+Mozart example is entered as
+@c
+@lilypond[singleline,fragment,verbatim]
+\relative c'' {
+ \key a \major
+ \time 6/8
+ cis8. d16 cis8 e4 e8
+ b8. cis16 b8 d4 d8
+}
+@end lilypond
+
+
@c needed better, maybe even redundant explanation
@c added another example below.
@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-You can make larger intervals by adding octavation quotes. Note that
-quotes or commas do not determine the absolute height of a note;
-the height of a note is relative to the previous one.
-@c don't use commas or quotes in this sentence
+Larger intervals are made by adding octavation quotes. Quotes or
+commas do not determine the absolute height of a note; the height of a
+note is relative to the previous one.
+@c do not use commas or quotes in this sentence
For example: @code{c f,} goes down; @code{f, f} are both the same;
-@code{c c'} are the same; and @code{c g'} goes up:
+@code{c' c} are the same; and @code{c g'} goes up:
@quotation
@example
@separate
-Here's an example of the difference between relative mode and
+Here is an example of the difference between relative mode and
``normal'' (non-relative) mode:
@quotation
@end quotation
@separate
-@strong{SUMMARY}
-
-The following table summarizes the syntax learned so far in this section.
-@multitable @columnfractions .3 .3 .4
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-@item @code{r4 r8}
-@tab rest
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-r4 r8
-@end lilypond
-
-
-@item @code{~}
-@tab tie
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-d ~ d
-@end lilypond
-@item @code{\key es \major }
-@tab key signature
-@tab
-@lilypond[fragment]
-\property Staff.TimeSignature \set #'transparent = ##t
-\clef treble
-\key es \major
-s4
-@end lilypond
-@item @code{'}
-@tab raise octave
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a a'
-@end lilypond
-@item @code{,}
-@tab lower octave
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c c,
-@end lilypond
-@end multitable
+@node Combining music into compound expressions
+@section Combining music into compound expressions
-A slur is drawn across many notes, and indicates bound articulation
-(legato). The starting note and ending note are marked with a
-``@code{(}'' and a ``@code{)}'' respectively:
+To print more than one staff, each piece of music that makes up a
+staff is marked by adding @code{\context Staff} before it. These
+@code{Staff}'s are then grouped inside @code{\simultaneous @{} and
+@code{@}}, as is demonstrated here:
@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4( )c16( cis d e c cis d )e( )d4
+@lilypond[fragment,verbatim]
+\simultaneous {
+ \context Staff = staffA { \clef violin c'' }
+ \context Staff = staffB { \clef bass c }
+}
@end lilypond
@end quotation
-@separate
-If you need two slurs at the same time (one for articulation, one for
-phrasing), you can also make a phrasing slur with @code{\(} and
-@code{\)}.
-
-@c lousy example
-@c ? --hwn
-@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
-@c chromatic thing pasted in front. (admittedly the original doesn't
-@c have a phrasing slur. The problem is that we don't want the slur
-@c and the Phrasing slur to collide. We're trying to make a good
-@c impression here.
-
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8(\( ais b ) c cis2 b'2 a4 cis, \) c
-@end lilypond
-@end quotation
-@separate
-
-Beams are drawn automatically, but if you don't like the choices, you
-can enter beams by hand. Surround the notes to be grouped with @code{[}
-and @code{]}:
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-[a8 ais] [d es r d]
-@end lilypond
-@end quotation
-@separate
-To print more than one staff, each piece of music that makes up a staff
-is marked by adding @code{\context Staff} before it. These
-@code{Staff}'s can be grouped inside @code{<} and @code{>}, as is
-demonstrated here:
+In this example, @code{\simultaneous } indicates that both music
+fragments happen at the same time, and must be printed stacked
+vertically. The notation @code{< .. >} can also be used as a
+shorthand for @code{\simultaneous @{ .. @}}.
-@quotation
-@lilypond[fragment,verbatim]
-<
- \context Staff = staffA { \clef violin c'' }
- \context Staff = staffB { \clef bass c }
->
-@end lilypond
-@end quotation
+@code{\context} introduces a ``notation context''. To understand this
+concept, imagine that you are performing a piece of music. When you
+perform the music, you combine the symbols printed at a certain point
+with contextual information. For example, without knowing the current
+clef, and the accidentals in the last measure, it would be impossible
+to determine the pitch of a note. In other words, this information
+forms context that helps you decipher a score. LilyPond produces
+notation from music, so in effect, it does the inverse of reading
+scores. Therefore, it also needs to keep track of contextual
+information. This information is maintained in ``notation contexts.''
+There are several types of contexts, e.g. @code{Staff}, @code{Voice}
+and @code{Score}, but also @code{Lyrics} and
+@code{ChordNames}. Prepending @code{\context} to a chunk of music
+indicates what kind of context to use for interpreting it.
-In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves. It doesn't matter what names you give, as long
-as each staff has a unique name.
+By specifying different names (in this case @code{staffA} and
+@code{staffB}), two different contexts are created, leading to two
+staves. It does not matter which names they are given, as long as they
+are different. If they get the same name, the chunks of music are
+assumed to belong on the same staff, and will be printed like that.
@separate
-We can typeset a melody with two staves now:
+We can now typeset a melody with two staves:
@quotation
@lilypond[verbatim,singleline]
< \context Staff = staffA {
\time 3/4
\clef violin
- \relative c'' { e2 ( d4 c2 b4 [a8 a] [b b] [g g] )a2. }
+ \relative c'' {
+ e2( d4 c2 b4 a8[ a]
+ b[ b] g[ g] a2.) }
}
\context Staff = staffB {
\clef bass
@end lilypond
@end quotation
-Notice that the time signature is specified in one melody staff only
-(the top staff), but is printed on both. LilyPond knows that the time
-signature should be the same for all staves.
+The example shows how small chunks of music, for example, the notes
+@code{c2}, @code{e4}, etc. of the second staff, are combined to form a
+larger chunk by enclosing it in braces. Again, a larger chunk is
+formed by prefix @code{\context Staff} to it, and that chunk is
+combined with @code{< >}. This mechanism is similar with mathematical
+formulas: in a formula, a so-called expression is formed by combining
+simpler expressions into larger expressions. For example,
-@separate
-
-Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c->
-@end lilypond
-@end quotation
-@separate
+ 1
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
-c-\ff c-\mf
-@end lilypond
+ 1 + 2
+
+ (1 + 2) * 3
+
+ ((1 + 2) * 3) / (4 * 5)
@end quotation
-@separate
+@cindex expression
+@cindex music expression
+is a sequence of expressions, where each expression is contained in
+the next one. The simplest expressions are numbers and operators
+(like +, * and /). Parentheses are used to group expressions. In
+LilyPond input, a similar mechanism is used. Here, the simplest
+expressions are notes and rests. By enclosing expressions in @code{<
+>} and @code{@{ @}}, more complex music is formed. The @code{\context}
+also forms new expressions; prepending it to a music expression yields
+a new expression.
+
+Like mathematical expressions, music expressions can be nested
+arbitrarily deep, e.g.
+@lilypond[verbatim,relative 1]
+ { c <c e>
+ < { e f } { c <b d> }
+ >
+ }
+@end lilypond
-Crescendi are started with the commands @code{\<} and @code{\>}. The
-command @code{\!} finishes a crescendo on the following note.
-@quotation
-@lilypond[verbatim,relative 1]
-c2\< \!c2-\ff \>c2 \!c2
-@end lilypond
-@end quotation
-@separate
-Chords can be made by surrounding notes with @code{<} and @code{>}:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <c e g> <c f a>
-@end lilypond
-@end quotation
-@separate
+@cindex indent
+When spreading expressions over multiple lines, it is customary to use
+an indent that indicates the nesting level. Formatting music like this
+eases reading, and helps you insert the right amount of closing
+braces at the end of an expression. For example,
+@example
+\score @{
+ \notes <
+ @{
+ @dots{}
+ @}
+ @{
+ @dots{}
+ @}
+ >
+@}
+@end example
+
-@ignore
-@c te diepzinnig?
-@c hmm, te losjes, iig
-In general, @code{ < @var{stuff} > } is used when @var{stuff} all
-happens at the same time, like in chords, or (like in the two-staff
-example above) in a bunch of stacked staves.
-@end ignore
-You can combine beams and ties with chords. Notice that
-beam and tie markings must be placed outside the chord markers:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
-@end lilypond
-@end quotation
-When you want to combine chords with slurs and dynamics, technical
-detail crops up: you have type these commands next to the notes, which
-means that they have to be inside the @code{< >}. Don't get confused
-by the chord @code{< >} and the dynamic @code{\< \>}!
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
+@cindex articulation
+@cindex accents
+@cindex staccato
+Common accents can be added to a note using a dash (`@code{-}') and a
+single character:
@quotation
-@example
-r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
-@end example
-@lilypond[relative 0, fragment]
-\slurUp
-r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
+@lilypond[verbatim,relative 1]
+c-. c-- c-> c-^ c-+ c-_
@end lilypond
@end quotation
@separate
-@c this example is a bit too strongly worded -- there's nothing wrong
-@c with starting a piece with a chord; you just have to be careful when
-@c you do so. I've rephrased this example below.
-@c There is one golden rule that you should keep in mind when writing
-@c LilyPond input:
-@c @quotation
-@c @strong{DO NOT START A PIECE WITH A CHORD}
-@c @end quotation
-@c Of course, it is a allowed, but the result might not be what you expect:
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(`@code{-}') and the digit to be printed:
+@c
+@lilypond[verbatim,relative 1]
+ c-3 e-5 b-2 a-1
+@end lilypond
-@c rephrased "don't start with a chord"
-There is one caution when using chords: if you use a chord at the very
-beginning of the piece, LilyPond might not understand what you want:
+Dynamic signs are made by adding the markings to the note:
@quotation
-@lilypond[verbatim,singleline]
-\score { \notes <c'2 e'2> }
+@lilypond[verbatim,relative 1]
+c-\ff c-\mf
@end lilypond
@end quotation
@separate
-If you have a piece that begins with a chord, you must explicitly
-state that the notes of the chord are to be put on the same staff, in
-the same voice. This is done by specifying @code{\context Staff} or
-@code{\context Voice} for the notes:
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+Crescendi and decrescendi are started with the commands @code{\<} and
+@code{\>}. The command @code{\!} finishes a crescendo on the note it
+is attached to:
@quotation
-@lilypond[verbatim,singleline]
-\score { \notes \context Voice <c'2 e'2> }
+@lilypond[verbatim,relative 1]
+c2-\< c2-\!-\ff c2-\> c2-\!
@end lilypond
@end quotation
@separate
-@strong{SUMMARY}
-
-@multitable @columnfractions .3 .3 .4
-
-@item @b{Syntax}
-@tab @b{Description}
-@tab @b{Example}
-
-
-@item @code{( )}
-@tab slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c( d )e
-@end lilypond
-
-
-@item @code{\( \)}
-@tab phrasing slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-c\( c() d \)e
-@end lilypond
-
-
-@item @code{[ ]}
-@tab beam
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-[a8 b]
-@end lilypond
-
-
-@item @code{< \context Staff ... >}
-@tab more staffs
-@tab
-@lilypond[fragment]
-< \context Staff = SA { c'1 }
- \context Staff = SB { c'1 } >
-@end lilypond
-
-
-@item @code{-> -.}
-@tab articulations
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-> c-.
-@end lilypond
-
-
-@item @code{-\mf -\sfz}
-@tab dynamics
-@tab
-@lilypond[fragment, relative 1]
-\property Staff.TimeSignature = \turnOff
-\property Staff.Clef = \turnOff
-c-\mf c-\sfz
-@end lilypond
+@cindex slur
-@item @code{\< \!}
-@tab crescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a\< a \!a
-@end lilypond
+A slur is drawn across many notes, and indicates bound articulation
+(legato). The starting note and ending note are marked with a
+``@code{(}'' and a ``@code{)}'' respectively:
-@item @code{\> \!}
-@tab decrescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.autoBeaming = ##f
-\property Staff.Clef = \turnOff
-a\> a \!a
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+d4( c16)( cis d e c cis d e)( d4)
@end lilypond
-
-
-@item @code{< >}
-@tab chord
-@tab
-@lilypond[fragment, relative 1]
-\context Voice <c e>
+@end quotation
+@separate
+@cindex slurs versus ties
+A slur is different from a tie. A tie simply makes the first note
+sound longer, and can only be used on pairs of notes with the same
+pitch. Slurs indicate the articulations of notes, and can be used on
+larger groups of notes. Slurs and ties are also nested in practice:
+@lilypond[fragment, relative=1]
+c2-~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@end multitable
-
-Now you know the basic ingredients of a music file, so this is the right
-moment to try your at hand at doing it yourself: try typing some
-simple examples, and experiment a little.
-
-When you're comfortable with the basics, you might want to read
-the rest of this chapter. It continues in tutorial-style, but it
-is much more in-depth, dealing with more advanced topics such as
-lyrics, chords, orchestral scores and parts, fine tuning of output,
-polyphonic music, and integrating text and music.
-
-
-
-
-
-@node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
-
-In this section we shall explain how to typeset the following
-fragment of The Free Software Song:
+@cindex phrasing slurs
+If you need two slurs at the same time (one for articulation, one for
+phrasing), you can also make a phrasing slur with @code{\(} and
+@code{\)}.
-@lilypond[singleline]
-\score { \notes { \addlyrics
- \notes \relative c' {
- \time 7/4
- d'2 c4 b16 ( a g a b a b ) c a2
- b2 c4 b8 ( a16 g ) a4 g2 }
- \context Lyrics \lyrics {
- Join us now __ and
- share the soft -- ware; }
-}
-\paper { linewidth = -1. }
-}
+@quotation
+@lilypond[fragment,relative 1, verbatim]
+a8(-\( ais b c) cis2 b'2 a4 cis, c-\)
@end lilypond
+@end quotation
-@cindex lyric mode
-@cindex @code{\lyrics}
-
-
-To print lyrics, you must enter them, and then instruct lilypond to
-handle the lyrics by printing them.
-You can enter lyrics in a special input mode of LilyPond. This mode is
-called Lyrics mode, and it is introduced by the keyword @code{\lyrics}.
-The purpose of this mode is that you can enter lyrics as plain text,
-punctuation and accents without any hassle.
-
-Syllables are entered like notes, with pitches replaced by text. For
-example, @code{Twin- kle twin- kle} enters four syllables. Note that
-the hyphen has no special meaning for lyrics, and does not introduce
-special symbols.
-
-Spaces can be introduced into a lyric either by using quotes:
-@code{"He could"4 not4} or by using an underscore without quotes:
-@code{He_could4 not4}. All unquoted underscores are converted to
-spaces.
-
-These are the lyrics for the free software song:
-
-@example
- \lyrics @{
- Join us now __ and
- share the soft -- ware; @}
-@end example
-
-As you can see, extender lines are entered as @code{__}. This will
-create an extender, a line that extends over the entire duration of
-the lyric. This line will run all the way to the start of the next
-lyric, so you may want to shorten it by using a blank lyric (using
-@code{_}).
-
-
-If you can use have hyphens at the end of a syllable, i.e.
-@example
- soft- ware
-@end example
-but then the hyphen will be attached to the to the end of the first
-syllable.
-
-If you want them centered between syllables you can use the special
-`@code{-}@code{-}' lyric as a separate word between syllables. The
-hyphen will have variable length depending on the space between
-syllables. It will be centered between the syllables.
-
-Normally, the notes that you enter are transformed into note heads.
-Note heads alone make no sense, they need surrounding information: a key
-signature, a clef, staff lines, etc. They need @emph{context}. In
-LilyPond, these symbols are created by objects called `interpretation
-contexts'. Interpretation contexts exist for generating notation
-(`notation context') and for generating sound (`performance
-context'). These objects only exist during a run of LilyPond.
-
-When LilyPond interprets music, it will create a Staff context.
-We don't want that default here, because we want lyric. The
-command
-@example
- \context Lyrics
-@end example
-explicitly creates an interpretation context of
-@code{Lyrics} type to interpret the song text that we entered.
-
-The melody of the song doesn't offer anything new:
-@example
- \notes \relative c' @{
- \time 7/4
- d'2 c4 b16 ( a g a b a b ) c a2
- b2 c4 b8 ( a16 g ) a4 g2 @}
-@end example
-
-Both can be combined with the @code{\addlyrics}:
-@example
-\addlyrics
- \notes \relative c' @dots{}
- \context Lyrics \lyrics @dots{}
-@end example
-
-The lyrics are also music expressions, similar to notes. What happens
-here, is that each syllable of the lyrics is put under the a note of
-the melody.
-The complete file is listed here:
-
-@example
-\score @{ \notes @{ \addlyrics
- \notes \relative c' @{
- \time 7/4
- d'2 c4 b16 ( a g a b a b ) c a2
- b2 c4 b8 ( a16 g ) a4 g2 @}
- \context Lyrics \lyrics @{
- Join us now __ and
- share the soft -- ware; @}
-@}
-\paper @{ linewidth = -1. @}
-@}
-@end example
-
-
-
-@node A melody with chords
-@section A melody with chords
-
-In this section we show how to typeset a melody with chord
-accompaniment. This file is included as @file{input/tutorial/flowing.ly}.
-
-@example
-\include "paper16.ly"
-melody = \notes \relative c' @{
- \partial 8
- \key c \minor
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-@}
-
-accompaniment =\chords @{
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min @}
-
-\score @{
- \simultaneous @{
- %\accompaniment
- \context ChordNames \accompaniment
- \context Staff = mel @{
- \melody
- @}
-
- @}
- \midi @{ \tempo 4=72 @}
- \paper @{ linewidth = 10.0\cm @}
-@}
-@end example
-
-
-The result would look this.
-
-@lilypond[center]
-\include "paper16.ly"
-melody = \notes \relative c' {
- \partial 8
- \key c \minor
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-}
+More information on fingering, articulation, slurs, phrasing slurs,
+and dynamics can be found in @ref{Fingering instructions},
+@ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
+respectively.
-accompaniment =\chords {
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min }
+@node Combining notes into chords
+@section Combining notes into chords
-\score {
- \simultaneous {
- %\accompaniment
- \context ChordNames \accompaniment
-
- \context Staff = mel {
- \property Staff.autoBeaming = ##f
- \melody
- }
- }
- \midi { \tempo 4=72 }
- \paper { linewidth = 10.0\cm }
-}
+@cindex chords
+Chords can be made by
+surrounding pitches with @code{<<} and @code{>}>:
+@quotation
+@lilypond[relative 0, fragment,verbatim]
+r4 <<c e g>>4 <<c f a>>8
@end lilypond
-
-Again, we will dissect the file line by line.
-
-@separate
-@example
-
- \include "paper16.ly"
-
-@end example
-Smaller size for inclusion in a book.
+@end quotation
@separate
-@example
- melody = \notes \relative c' @{
-
-@end example
-The structure of the file will be the same as the previous one, a
-@code{\score} block with music in it. To keep things readable, we will
-give names to the different parts of music, and use the names to
-construct the music within the score block.
-@separate
-@example
- \partial 8
-@end example
+You can combine beams and ties with chords. Beam and tie markings
+must be placed outside the chord markers:
+@quotation
+@lilypond[relative 0, fragment,verbatim]
+r4 <<c e g>>8[ <<c f a>>]-~ <<c f a>>
+@end lilypond
+@end quotation
-@cindex @code{\partial}
-@cindex anacrusis
-The piece starts with an anacrusis of one eighth.
-@separate
+@quotation
@example
- \key c \minor
-@end example
-The key is C minor: we have three flats.
-
-@separate
-@example
-
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-
-@end example
-
-@cindex manual beaming
-@cindex automatic beaming, turning off
-We use explicit beaming. Since this is a song, we turn automatic
-beams off, and use explicit beaming where needed.
-@separate
-@example
-
- @}
-
-@end example
-This ends the definition of @code{melody}.
-
-@separate
-@example
-
- text = \lyrics @{
-
-@end example
-@cindex lyrics
-@cindex identifier assignment
-@cindex syllables, entering
-
-@separate
-@example
-
- accompaniment =\chords @{
-
+r4 <<c e g>>8-\>( <<c e g>> <<c e g>> <<c f a>>8-\!)
@end example
-@cindex chords
-@cindex mode, chords
-We'll put chords over the music. To enter them, there is a special mode
-analogous to @code{\lyrics} and @code{\notes} mode, where you can give
-the names of the chords you want, instead of listing the notes
-comprising the chord.
-@separate
-@example
-
- r8
-
-@end example
-There is no accompaniment during the anacrusis.
-@separate
-@example
-
- c2:3-
-
-@end example
-
-@cindex tonic
-@cindex chord modifier
-@cindex modifier, chord
-This is a c minor chord, lasting half a note. Chord are entered by
-entering the tonic. Then notes can be changed. In this case, a small third
-is used. The cod for this is @code{3-}.
-
-@separate
-@example
-f:3-.7
-@end example
-Similarly, @code{7} modifies (adds) a seventh, which is small by
-default to create the @code{f a c es} chord. Multiple modifiers must be
-separated by dots.
-@separate
-@example
-
- d:min es4 c8:min r8
-
-@end example
-Some modifiers have predefined names, e.g. @code{min} is the same as
-@code{3-}, so @code{d-min} is a minor @code{d} chord.
-@separate
-@example
-
- c2:min f:min7 g:7^3.5 c:min @}
-
-@end example
-@cindex named modifier
-
-A named modifier @code{min} and a normal modifier @code{7} do not have
-to be separated by a dot. Tones from a chord are removed with chord
-subtractions. Subtractions are started with a caret, and they are
-also separated by dots. In this example, @code{g:7^3.5} produces a
-minor seventh. The brace ends the sequential music.
-@separate
-@example
-
- \score @{
- \simultaneous @{
-
-@end example
-We assemble the music in the @code{\score} block. Melody, lyrics and
-accompaniment have to sound at the same time, so they should be
-@code{\simultaneous}.
-@cindex @code{\simultaneous}
-@separate
-@example
-
- %\accompaniment
-
-@end example
-Chord mode generates notes grouped in @code{\simultaneous} music. If
-you remove the comment sign, you can see the chords in normal
-notation: they will be printed as note heads on a separate
-staff. To print them as chords names, they have to be interpreted as
-being chords, not notes. This is done with the following command:
-@separate
-@example
-
- \context ChordNames \accompaniment
-
-@end example
-@cindex context
-@cindex interpretation context
-@cindex notation context
-
-
-Normally, the notes that you enter are transformed into note heads.
-Note heads alone make no sense, they need surrounding information: a key
-signature, a clef, staff lines, etc. They need @emph{context}. In
-LilyPond, these symbols are created by objects called `interpretation
-contexts'. Interpretation contexts exist for generating notation
-(`notation context') and for generating sound (`performance
-context'). These objects only exist during a run of LilyPond.
-
-When LilyPond interprets music, it will create a Staff context. If
-the @code{%} sign in the previous line were removed, you could see
-that mechanism in action.
-
-We don't want that default here, because we want chord names. The
-command above explicitly creates an interpretation context of
-@code{ChordNames} type to interpret the music @code{\accompaniment}.
-
-@separate
-@example
-
- \context Staff = mel @{
-
-@end example
-
-We place the melody on a staff called @code{mel}. We give it a name to
-differentiate it from the one that would contain note heads for the
-chords, if you would remove the comment before the ``note heads''
-version of the accompaniment. By giving this staff a name, it is
-forced to be different.
-@separate
-@example
-
- \property Staff.autoBeaming = ##f
-
-@end example
-@cindex \property
-@cindex context variables
-@cindex setting context variables
-An interpretation context has variables, called properties, that tune
-its behavior. One of the variables is @code{autoBeaming}. Setting
-this @code{Staff}'s property to @code{##f}, which is the boolean value
-@var{false}, turns the automatic beaming mechanism off for the current
-staff.
-
-
-@separate
-@example
-
- \melody
- @}
-
-@end example
-Finally, we put the melody on the current staff. Note that the
-@code{\property} directives and @code{\melody} are grouped in sequential
-music, so the property settings are done before the melody is
-processed.
-
-@separate
-@example
-
- \midi @{ \tempo 4=72@}
-
-@end example
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and recording digital instruments. So a MIDI file is like a
-tape recording of an instrument. The @code{\midi} block makes the
-music go to a MIDI file, so you can listen to the music you entered. It
-is great for checking the music. Whenever you hear something weird, you
-probably hear a typing error.
-
-Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
-also specifies an output method. You can specify the tempo using the
-@code{\tempo} command, in this case the tempo of quarter notes is set to
-72 beats per minute.
-@separate
-@example
-
- \paper @{ linewidth = 10.0\cm @}
-
-@end example
-We also want notation output. The linewidth is short so the piece
-will be set in two lines.
-
-@node More stanzas
-@section More stanzas
-
-
-@cindex phrasing
-
-If you have multiple stanzas printed underneath each other, the vertical
-groups of syllables should be aligned around punctuation. LilyPond can
-do this if you tell it which lyric lines belong to which melody.
-We show how you can do this by showing how you could print a frivolous
-fragment of a fictional Sesame Street duet.
-
-@lilypond[singleline,verbatim]
-\score {
-\addlyrics
- \notes \relative c'' \context Voice = duet { \time 3/4
- g2 e4 a2 f4 g2. }
- \lyrics \context Lyrics <
- \context LyricsVoice = "duet-1" {
- \property LyricsVoice . stanza = "Bert"
- Hi, my name is bert. }
- \context LyricsVoice = "duet-2" {
- \property LyricsVoice . stanza = "Ernie"
- Ooooo, ch\'e -- ri, je t'aime. }
- >
-}
-@end lilypond
-
-To this end, give the Voice context an identity, and set the
-LyricsVoice to a name starting with that identity followed by a dash.
-In the following example, the Voice identity is @code{duet},
-@example
-\context Voice = duet @{
- \time 3/4
- g2 e4 a2 f4 g2. @}
-@end example
-and the
-identities of the LyricsVoices are @code{duet-1} and @code{duet-2}.
-@example
- \context LyricsVoice = "duet-1" @{
- Hi, my name is bert. @}
- \context LyricsVoice = "duet-2" @{
- Ooooo, ch\'e -- ri, je t'aime. @}
-@end example
-
-We add the names of the singers. This can be done by setting
-@code{LyricsVoice.Stanza} (for the first system) and
-@code{LyricsVoice.stz} for the following systems. Notice how you must
-surround dots with spaces in @code{\lyrics} mode.
-
-@example
- \property LyricsVoice . stanza = "Bert"
- @dots{}
- \property LyricsVoice . stanza = "Ernie"
-@end example
-
-The convention for naming @code{LyricsVoice} and @code{Voice} must
-also be used to get melismata on rests correct.
-
-
-
-@node More movements
-@section More movements
-
-LilyPond only handles formatting sheet music. It doesn't concern
-itself with producing titles. This is the jobs of a simple wrapper
-program called ly2dvi. @code{ly2dvi} calls LilyPond to do the
-sheet music formatting. Then it produces titles, and ties together all
-inputs into a single @file{dvi} file. In this section, we show some of
-the options for titling. We will show how you can produce a file
-that looks like this:
-
-@center @strong{Two miniatures}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@var{Up}
-@end flushleft
-@lilypond
- \score {
- \notes { c'4 d'4 }
- \paper { linewidth = -1.0 }
- }
-@end lilypond
-@flushright
-Opus 2.
-@end flushright
-@flushleft
-@var{Down}
-@end flushleft
-@lilypond
- \score {
- \notes { d'4 c'4 }
- \paper { linewidth = -1.0 }
- }
-@end lilypond
-
-For example, consider the following file (@file{miniatures.ly})
-
-@example
-\version "1.5.60"
-\header @{
- title = "Two miniatures"
- composer = "F. Bar Baz"
- tagline = "small is beautiful" @}
-
-\paper @{ linewidth = -1.0 @}
-
-%@{
-
-Mental note: discuss Schenkerian analysis of these key pieces.
-
-%@}
-
-
-\score @{
- \notes @{ c'4 d'4 @}
- \header @{
- opus = "Opus 1."
- piece = "Up" @}
-@}
-\score @{
- \notes @{ d'4 c'4 @}
- \header @{
- opus = "Opus 2."
- piece = "Down" @}
-@}
-@end example
-
-The information for the global titling is in a so-called header block.
-The information in this block is not used by
-LilyPond, but it is passed into the output. @file{ly2dvi} uses this
-information to print titles above the music.
-@cindex assignments
-@cindex identifier assignment
-the @code{\header} block contains assignments. In each assignment, a
-variable is set to a value. The header block for this file looks like
-this
-@cindex @code{\header}
-@example
- \header @{
- title = "Two miniatures"
- composer = "F. Bar Baz"
- tagline = "small is beautiful"
- @}
-@end example
-
-When you process a file with ly2dvi, a signature line is printed at
-the bottom of the last page. This signature is produced from the
-@code{tagline} field of @code{\header}. The default "Lily was here,
-@var{version number}" is convenient for us programmers. Archived
-the layout of different versions can be compared using archived
-print-outs (that include a version number).
-
-@cindex Lily was here
-@cindex signature line
-@cindex tag line
-
-Many people find the default tagline (``Lily was here'') too droll.
-If that is the case, assign something else to @code{tagline}, as shown
-above.
-
-@separate
-@example
- \paper @{
- linewidth = -1.0 @}
-@end example
-
-A paper block at top level, i.e. not in a @code{\score} block sets the
-default page layout. The following @code{\score} blocks don't have
-@code{\paper} sections, so the settings of this block are substituted:
-
-The variable @code{linewidth} normally sets the length of the systems
-on the page. However, a negative value has a special meaning. If
-@code{linewidth} is less than 0, no line breaks are inserted into the
-score, and the spacing is set to natural length: a short phrase takes
-up little space, a longer phrase more space.
-
-@example
-%@{
-
-Mental note: discuss Schenkerian analysis of these key pieces.
-
-%@}
-@end example
-
-Mental notes to yourself can be put into comments. There are two types
-of comments. Line comments are introduced by @code{%}, and block
-comments are delimited by @code{%@{} and @code{%@}}.
-
-@separate
-@example
- \score @{
- \notes @{ c'4 d'4 @}
-@end example
-
-In previous examples, notes were specified in relative octaves,
-i.e. each note was put in the octave that is closest to its
-predecessor. Besides relative, there is also absolute octave
-specification, which you get when you don't specify @code{\relative}. In
-this input mode, the central C is denoted by @code{c'}. Going down, you
-get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
-@code{c'''} etc.
-
-When you're copying music from existing sheet music, relative octaves
-are probably the easiest to use: it's less typing work and errors are
-easily spotted. However, if you write LilyPond input directly, either by
-hand (i.e. composing) or by computer, absolute octaves may be easier to use.
-
-
-@separate
-@example
- \header @{
-@end example
-
-The @code{\header} is normally at the top of the file, where it sets
-values for the rest of the file. If you want to typeset different pieces
-from one file (for example, if there are multiple movements, or if
-you're making an exercise book), you can put different @code{\score}
-blocks into the input file. ly2dvi will assemble all LilyPond output
-files into a big document. The contents of \header blocks specified
-within each score, are used for the titling of each movement.
-@separate
-@example
- opus = "Opus 1."
- piece = "Up" @}
-@end example
-For example, the Opus number is put at the right, and the piece string
-will be at the left.
-
-
-
-@example
-\version "1.5.60"
-\header @{
- title = "Two miniatures"
- composer = "F. Bar Baz"
- tagline = "small is beautiful" @}
-
-\paper @{ linewidth = -1.0 @}
-
-\score @{
- \notes @{ c'4 d'4 @}
- \header @{
- opus = "Opus 1."
- piece = "Up" @}
-@}
-\score @{
- \notes @{ d'4 c'4 @}
- \header @{
- opus = "Opus 2."
- piece = "Down" @}
-@}
-@end example
-
-
-@separate
-@example
-\version "1.6.0"
-@end example
-Lilypond and its language are still under development, and
-occasionally, details of the syntax are changed. This fragment
-indicates for which version the input file was written. When you
-compile this file, the version number will be checked, and you will
-get a warning when the file is too old. This version number is also
-used by the @code{convert-ly} program (See @ref{Older
-LilyPond versions}), which is used to update the file to the latest
-lily version.
-
-
-@node A piano excerpt
-@section A piano excerpt
-
-Our fourth subject is a piece of piano music. The fragment in the
-input file is a piano reduction of the G major Sinfonia by Giovanni
-Battista Sammartini. It was composed around 1740. It's in the source
-package under the name @file{input/tutorial/sammartini.ly}.
-
-@lilypondfile[smallverbatim]{sammartini.ly}
-
-As you can see, this example features multiple voices on one staff. To
-make room for those voices, their notes have to be stemmed in opposite
-directions.
-
-LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
-with some other commonly used formatting instructions, but to explain how
-it works, we wrote our own here. Of course, you should use predefined
-identifiers like these if possible: then you will be affected less by
-the implementation changes we occasionally make.
-
-@separate
-@example
-viola = \notes \relative c' \context Voice = viola @{
-@end example
-In this example, you can see multiple parts on a staff. Each part is
-associated with one notation context. This notation context handles
-stems and dynamics (among others). The type name of this context is
-@code{Voice}. For each part we have to make sure that there is
-precisely one @code{Voice} context, so we give it a unique name
-(`@code{viola}').
-
-@separate
-@example
-<c4-\arpeggio g' c>
-@end example
-The delimiters @code{<} and @code{>} are shorthands for
-@code{\simultaneous @{} and @code{@}}. The expression enclosed in
-@code{<} and @code{>} is a chord.
-
-@cindex arpeggio
-
-@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
-the chord.
-
-@separate
-@example
- \voiceTwo
-@end example
-
-We want the viola to have stems down, and have all the other
-characteristics of a second voice. This is enforced using the
-@code{\voiceTwo} command: it inserts instructions that makes stem,
-ties, slurs, etc. go down.
-
-
-
-@separate
-@example
- g'8. b,16
-@end example
-Relative octaves work a little differently with chords. The starting
-point for the note following a chord is the first note of the chord. So
-the @code{g} gets an octave up quote: it is a fifth above the starting
-note of the previous chord (the central C).
-
-@separate
-@example
-s1 s2. r4
-@end example
-@code{s} is a spacer rest. It does not print anything, but it does have
-the duration of a rest. It is useful for filling up voices that
-temporarily don't play. In this case, the viola doesn't come until one
-and a half measure later.
-
-@separate
-@example
-oboes = \notes \relative c'' \context Voice = oboe @{
-@end example
-Now comes a part for two oboes. They play homophonically, so we
-print the notes as one voice that makes chords. Again, we insure that
-these notes are indeed processed by precisely one context with
-@code{\context}.
-@separate
-@example
-\voiceOne s4 g8. b,16 c8 r <e'8. g> <f16 a>
-@end example
-
-The oboes should have stems up, so they should have stems up, to keep
-them from interfering with the staff-jumping bass figure.
-
-@separate
-@example
-\grace <e8( g> < d4 )f> <c2 e>
-@end example
-@cindex @code{\grace}
-@cindex ornaments
-@cindex grace notes
-@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord. A slur is introduced starting from the @code{\grace}
-ending on the following chord.
-
-@separate
-@example
-\times 2/3
-@end example
-@cindex tuplet
-@cindex triplets
-Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the piece
-of music is multiplied by the fraction. Triplets make notes occupy 2/3
-of their notated duration, so in this case the fraction is 2/3.
-@separate
-@example
-@{ <d8 f> <e g> <f a> @}
-@end example
-The piece of music to be `tripletted' is sequential music containing
-three chords.
-
-@separate
-@example
-<
-@end example
-At this point, the homophonic music splits into two rhythmically
-different parts. We can't use a sequence of chords to enter this, so
-we make a `chord' of sequences to do it. We start with the upper
-voice, which continues with upward stems:
-@separate
-@example
- @{ \times 2/3 @{ a8 g c @} c2 @}
-@end example
-
-@separate
-@example
-\\
-@end example
-The easiest way to enter multiple voices is demonstrated
-here. Separate the components of the voice (single notes or entire
-sequences) with @code{\\} in a simultaneous music expression. The
-@code{\\} separators split first voice, second voice, third voice, and
-so on.
-
-As far as relative mode is concerned, the previous note is the
-@code{c'''2} of the upper voice, so we have to go an octave down for
-the @code{f}.
-@separate
-@example
-
- f,8 e e2
-@} >
-@end example
-This ends the two-part section.
-@separate
-@example
-\stemBoth
-\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
-@end example
-@cindex trill
-@cindex stemBoth
-
-@code{\stemBoth} ends the forced stem directions. From here, stems are
-positioned as if it were single part music.
-
-The bass has a little hoom-pah melody to demonstrate parts switching
-between staves. Since it is repetitive, we use repeats:
-@separate
-@example
-hoomPah = \repeat unfold 8
-@end example
-@cindex unfolded @code{\repeat}
-The unfolded repeat prints the notes in its argument as if they were
-written out in full eight times.
-@separate
-@example
-\notes \transpose c' @{
-@end example
-@cindex transposing
-@cindex relative mode and transposing
-
-Transposing can be done with @code{\transpose}, which takes two arguments.
-The first specifies what central C should be transposed to. The second
-is the to-be-transposed music. As you can see, in this case, the
-transposition has no effect, as central C stays at central C.
-
-The purpose of this no-op is to protect it from being interpreted as
-relative notes. Relative mode can not be used together with
-transposition, so @code{\relative} will leave the contents of
-@code{\hoomPah} alone. We can use it without having to worry about
-getting the motive in a wrong octave.
-@separate
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-@cindex @code{\translator}
-
-@example
- \translator Staff = down
- \stemUp
- c8
- \translator Staff = up
- \stemDown
- c'8 @}
-@end example
-Voices can switch between staves. Here you see two staff switching
-commands. The first one moves to the lower staff, the second one to
-the lower one. If you set stem directions explicitly (using the
-identifiers @code{\stemUp} and @code{\stemDown}.
-
-@separate
-@example
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\autochange Staff \hoomPah \context Voice
-@end example
-
-@separate
-@example
- \translator Staff = down
-@end example
-@cindex staff switch
-@cindex cross staff voice
-We want the remaining part of this melody on the lower staff, so we do a
-manual staff switch here.
-
-
-@separate
-@example
-\context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
-@end example
-@cindex tie
-@cindex @code{~}
-After skipping some lines, we see @code{~}. This mark makes ties. Note
-that ties and slurs are different things. A tie can only connect two
-note heads of the same pitch, whereas a slur can connect many chords
-with one curve.
-
-@separate
-@example
-\context PianoStaff
-@end example
- A special context is needed to get cross staff beaming right. This
-context is called @code{PianoStaff}.
-@separate
-@example
-\context Staff = bottom < \time 2/2 \clef bass
-@end example
-The bottom staff must have a different clef.
-@separate
-@example
-indent = 0.0
-@end example
-To make some more room on the line, the first (in this case the only)
-line is not indented. The line still looks very cramped, but that is due
-to the page layout of this document.
-
-
-@ignore
-[TODO:
-
-* font-size, multi-stanza.
-
-* Simple part combining in a Hymn
-@end ignore
-
-
-@node Fine tuning a piece
-@section Fine tuning a piece
-
-In this section, we show some ways to fine tune the final output of a
-piece. We do so using a single measure of a moderately complex piano
-piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
-tuned and the untuned are in the @file{input/tutorial/}).
-
-The code for the untuned example shows us some new things.
-
-@lilypondfile[verbatim]{brahms-original.ly}
-
-
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex crescendo
-@cindex @code{\<}
-@cindex @code{\!}
-
-The crescendo is ended at the half note by the escaped exclamation
-mark @code{\!}.
-
-Hairpin dynamics can be indicated using @code{\>} to start a
-decrescendo, and @code{\!} to end one. The crescendo is started using
-@code{\<} and also ended using @code{\!}. Absolute dynamics can be
-entered using @code{\p}, @code{\mf}, etc. All these commands apply to
-the complete chord where they are entered, but for syntactical
-reasons, they must be attached to one of the notes of the chord.
-
-@cindex fingering instructions
-
-Fingering indications are entered simply using @code{-@var{N}}, where
-@var{N} is a digit.
+@lilypond[relative 0, fragment]
+\slurUp
+r4 <<c e g>>8-\>( <<c e g>> <<c e g>> <<c f a>>8-\!)
+@end lilypond
+@end quotation
+@separate
-Now that we have the basic piece of music entered, we want to fine
-tune it, so we get something that resembles the original printed
-edition by Schott/Universal Edition:
-@lilypondfile{brahms-tweaked.ly}
-@cindex tuning grob behavior
+@menu
+* Basic rhythmical commands::
+* Commenting input files::
+@end menu
-The basic process that we follow is that we override defaults in the
-printing system. We do this by setting variables in so-called grobs.
-Printed symbols are internally represented by Graphical Objects
-(Grobs). Each grob is described by a bunch of settings. Every
-setting is a variable: it has a name, and you can assign a value to
-the variable. These setting determine the fonts, offsets, sub-routines
-to be called on the grob, etc. The initial values of these settings
-are set in the Scheme file @file{scm/grob-description.scm}.
+@node Basic rhythmical commands
+@subsection Basic rhythmical commands
+
+@cindex pickup
+@cindex anacruse
+@cindex upstep
+@cindex partial measure
+A pickup (or upstep) is entered with the keyword @code{\partial}. It
+is followed by a duration: @code{\partial 4} is a quarter note upstep
+and @code{\partial 8} an eighth note:
+@lilypond[relative 1,verbatim,fragment]
+ \partial 8
+ f8 c2 d e
+@end lilypond
-@cindex slur attachments
+@cindex tuplets
+@cindex triplets
+Tuplets are made with the @code{\times} keyword. It takes two
+arguments: a fraction and a piece of music. The duration of the piece
+of music is multiplied by the fraction. Triplets make notes occupy
+2/3 of their notated duration, so a triplet has 2/3 as its fraction:
+@c
+@lilypond[relative 0,verbatim,fragment]
+ \times 2/3 { f8 g a }
+ \times 2/3 { c r c }
+@end lilypond
-We start with the slur: the slur in the upper part, running from the F
-sharp to the A, runs from stem to stem in the printed edition, while
-ours starts from the note head at the left. The following property
-setting forces all slurs to run from stem to stem (and not from or to
-note head)
+@cindex grace notes
+@cindex accacciatura
+Grace notes are also made by prefixing a note, or a set of notes with
+a keyword. In this case, the keyword is @code{\grace}:
+@lilypond[relative 1, verbatim,fragment]
+ c4 \grace b16( c4)
+ \grace { d16( e } d4)
+@end lilypond
-@example
- \property Voice.Slur \set #'attachment = #'(stem . stem)
-@end example
+@noindent
+More information on grace notes, tuplets and upsteps are in @ref{Grace
+notes}, @ref{Tuplets} and @ref{Partial measures}.
-More precisely, this command extends the definition of the @code{Slur}
-object in the current @code{Voice}. The variable @code{attachment} is
-set to the pair of symbols @code{'(stem . stem)}.
-
-Although this is useful information, it is not very helpful: the
-lilypond backend supports approximately 240 variables like
-@code{attachment}, each with their own meaning and own type
-(eg. number, symbol, list, etc). Besides slur, LilyPond has 80
-different types of Grobs, that may be created in 14 different context
-types besides Voice.
-
-@cindex internal documentation
-@cindex finding grobs
-@cindex grob descriptiosn
-
-The interesting information is how you can figure out which properties
-to tune for your own scores. To discover this, you must have a copy of
-the internals document. This is a set of HTML pages, which should be
-included if you run a binary distribution@footnote{You can also
-compile them by executing @code{make -C Documentation/user/
-out/lilypond-internals.html} in the source package.}. This document is
-also available on the web: go to the lilypond website, click
-``Documentation: other'' on the side bar, click
-``lilypond-internals'', under information for users.
-
-You might want to bookmark either the HTML files on disk, or the one
-on the web. One word of caution is in place here: the internals
-documentation is generated from the definitions that lily uses. For
-that reason, it is strongly tied to the version of LilyPond that you
-use. Before you proceed, please make sure that you are using the
-documentation that corresponds to the LilyPond version that you use.
-
-Suppose that you wanted to tune the behavior of the slur. The first
-step is to get some general information on slurs in lilypond. Turn to
-the index, and look up ``slur''. The section on slurs says
-@quotation
-The grob for this object is @internalsref{Slur}, generally in
-@internalsref{Voice} context.
-@end quotation
-So the grob for this object is called @code{Slur}, and slurs are
-created in the @code{Voice} context. If you are reading this tutorial
-in the HTML version, then you can simply click Slur, otherwise, you
-must look it up the internal documentation: click ``grob overview'' ,
-and select ``slur'' (the list is alphabetical.)
-
-Now you get a list of all the properties that the slur object
-supports, along with their default values. Among the properties we
-find the @code{attachment} property with its default setting.
-The property documentation explains that the following setting will
-produce the desired effect:
-@example
- \property Voice.Slur \set #'attachment = #'(stem . stem)
-@end example
-If you ran the previous example, you have unknowingly already used
-this kind of command. The @file{ly/property-init.ly} contains the
-definition of @code{\stemUp}
-@example
- stemUp = \property Voice.Stem \set #'direction = #1
-@end example
+@node Commenting input files
+@subsection Commenting input files
+@cindex comments
+@cindex line comment
+@cindex block comment
+Comments are pieces of the input that are ignored. There are two
+types of comments. A line comments is introduced by @code{%}: after
+that, the rest of that line is ignored. Block comments span larger
+sections of input. Anything that is enclosed in @code{%@{} and
+@code{%@}} is ignored too. The following fragment shows possible uses
+for comments:
-We also want to move around the fingering `3'. In the printed edition
-it is not above the stem, but a little lower, slightly left of the
-stem. From the user manual, we find that the associated grob is called
-@code{Fingering}, but how do we know if we should use @code{Voice} or
-@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
-also deduce this information from the internals documentation: if you
-visit the documentation of @code{Fingering}, you will notice
@example
-Fingering grobs are created by: Fingering_engraver
-@end example
-
-
+ % notes for twinkle twinkle follow:
+ c4 c g' g a a
+
+ %@{
+
+ This line, and the notes below
+ are ignored, since they are in a
+ block comment.
-Clicking @code{Fingering_engraver} will show you the documentation of
-the module responsible for interpreting the fingering instructions and
-translating them to a @code{Fingering} grob. Such a module is called
-an @emph{engraver}. The documentation of the @code{Fingering_engraver}
-says,
-@example
-Fingering_engraver is part of contexts: Voice and TabVoice
-@end example
-so tuning the settings for Fingering should be done using either
-@example
- \property Voice.Fingering \set @dots{}
-@end example
-or
-@example
- \property TabVoice.Fingering \set @dots{}
+ g g f f e e d d c2
+ %@}
@end example
-Since the @code{TabVoice} is only used for tab notation, we see that
-the first guess @code{Voice} was indeed correct.
-@cindex setting grob properties
-@cindex @code{extra-offset}
-For shifting the fingering, we use the grob property
-@code{extra-offset}. The following command manually adds an offset to
-the object. We move it a little to the left, and 1.8 staff space
-downwards.
-@example
- \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
-@end example
-The @code{extra-offset} is a low-level feature: it moves around
-objects in the printout; the formatting engine is completely oblivious
-to these offsets. The unit of these offsets are staff-spaces.
-@cindex reverting grob properties
-@cindex undoing grob properties
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
-We only want to offset a single grob, so after the F-sharp, we must
-undo the setting. The technical term is to revert the grob property.
+@cindex Lyrics
+@cindex Songs
+Lyrics are entered by separating each syllable with a space, and
+surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
@example
- \property Voice.Fingering \revert #'extra-offset
+ \lyrics @{ I want to break free @}
@end example
-@cindex property types
-@cindex translator properties
-@cindex grob properties
-@cindex music properties
-
-
-There is three different types of variables in LilyPond, something
-which is confusing at first (and for some, it stays like that).
-Variables such as @code{extra-offset} and @code{attachment} are called
-grob properties. They are something different from the translator
-properties, like @code{autoBeaming}. Finally, music expressions are
-internally also stored using properties, so-called music
-properties. You will encounter the latter type if you run Scheme
-functions on music using @code{\apply}.
-
-The second fingering instruction should be moved up a little, to avoid
-a collision with the slur. This could be achieved with
-@code{extra-offset}, but in this case, a simpler mechanism also
-works. We insert an empty text between the 5 and the note. The empty
-text pushes the fingering instruction away:
+Like notes, lyrics are also a form of music, but they must not be
+printed on a staff, which is the default way to print music. To print
+them as lyrics, they must be marked with @code{ \context Lyrics}:
@example
- a^" "^#'(finger "5")
+ \context Lyrics \lyrics @{ I want to break free @}
@end example
+The melody for this song is as follows:
-Lilypond tries to put fingering instructions closer to the notes as
-text instructions. To insert an empty text (@code{^" "}) between the
-finger and the note, we have disguised the fingering instruction as a
-text: @code{(finger "5")}.
-
-Normally, one would specify dynamics in a single voice, and start and
-end dynamics (such as @b{f} and @b{p}) will be aligned with
-hairpins. In this case, we want the decrescendo to be in a different
-place from the piano sign. We achieve this by putting the dynamic
-markings in different voices. The crescendo should be above the upper
-staff. This can be forced by the precooked command
-@example
- \dynamicsUp
-@end example
+@lilypond[fragment,relative=1]
+ \partial 8
+ c8
+ \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
+@end lilypond
-However, if you do that, the decrescendo will be too close to the
-upper voice, and collide with the stems. Looking at the manual for
-dynamics, we notice that ``Vertical positioning of these symbols is
-handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
-to the documentation of @code{DynamicLineSpanner}, we find that the
-@code{DynamicLineSpanner} supports several so-called
-`interfaces'. This grob not only puts dynamic objects next to the
-staff (@code{side-position-interface}), but it also groups dynamic
-objects (@code{axis-group-interface}), is considered a dynamic sign
-itself (@code{dynamic-interface}) and is a grob: it has the
-@code{grob-interface}, with all the variables that come with it.
-
-For the moment, we are interested in the side positioning:
-@quotation
- side-position-interface
+The lyrics can be set to these notes, combining both with the
+@code{\addlyrics} keyword:
+@example
+ \addlyrics
+ \notes @{ @dots{} @}
+ \context Lyrics @dots{}
+@end example
+
+The final result is
+@lilypond[verbatim,linewidth=6.0cm]
+\score {
+ \notes {
+ \addlyrics
+ \relative c' {
+ \partial 8
+ c8
+ \times 2/3 { f g g } \times 2/3 { g4( a2) }
+ }
+ \context Lyrics \lyrics { I want to break free }
+ }
+ \paper{ }
+}
+@end lilypond
- Position a victim object (this one) next to other objects (the
- support). In this case, the direction signifies where to put the
- victim object relative to the support (left or right, up or down?)
-@end quotation
-Between the grob and its support (in this case: the notes in the voice
-going down), there should be more space. This space is controlled by
-@code{padding}, so we increase it.
+@cindex melisma
+@cindex extender line
+@c synonyms?
+This melody ends on a @rglos{melisma}, a single syllable (``free'')
+sung to more than one note. This is indicated with a @emph{extender
+line}. It is entered as two underscores, i.e.
@example
- \property Voice.DynamicLineSpanner \override #'padding = #5.0
-@end example
-
-This command is almost like the command for setting slur attachments,
-but subtly different in its details. Grob properties can be
-manipulated with two commands: @code{\override} extends the grob
-variables with a setting, and @code{\revert} releases this
-setting. This has a certain theoretical appeal: the operations are
-simple and symmetric. For practical use, it can be cumbersome. Both
-commands act like parentheses: you should carefully balance the use of
-@code{\override} and @code{\revert}. The @code{\set} command is more
-friendly: it first does a @code{\revert} followed by @code{\override}.
-
-Finally, Brahms uses music notation is a slightly unorthodox way. Ties
-usually happen only within one voice. In this piece, the composer
-gladly produces ties that jump voices. We deal with this by faking
-these ties: whenever we need such a tie, we insert a notehead in a
-different voice, and blank the stem. This is done in the following
-snippet of code.
+ \lyrics @{ I want to break free __ @}
+@end example
+@lilypond[]
+\score {
+ \notes {
+ \addlyrics
+ \relative c' {
+ \partial 8
+ c8
+ \times 2/3 { f g g } \times 2/3 { g4( a2) }
+
+ %% ugh, this is to deal with bugs in the extender implementation
+ \hideNotes
+ c32
+ }
+ \context Lyrics \lyrics { I want to break free __ }
+ }
+ \paper{ linewidth = 9.0 \cm }
+}
+@end lilypond
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables:
@example
- \property Voice.Stem \set #'transparent = ##t
- d'
- \property Voice.Stem \revert #'transparent
+ Twin -- kle twin -- kle
@end example
+@lilypond[singleline]
+\score {
+ \addlyrics \notes \relative f' { \time 2/4
+ f4 f c' c' }
+ \context Lyrics \lyrics { Twin -- kle twin -- kle
+ }
+\paper { linewidth = 6.0 \cm }
+ }
+
+@end lilypond
-Finally, the last tie is forced up using @code{\tieUp}.
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
-@node An orchestral score
-@section An orchestral score
-@menu
-* The full score::
-* Extracting an individual part::
-@end menu
+@node A lead sheet
+@section A lead sheet
+@cindex Lead sheets
+@cindex chords
+@cindex chord names
+
+In popular music, it is common to denote accompaniment as chord-names.
+Using them in LilyPond has two parts, just like lyrics: entering the
+chords (with @code{\chords}), and printing them (with @code{\context
+ChordNames}).
+
+Chord names are entered by starting chords mode (with @code{\chords}).
+In chords mode, you can enter chords with a letter (indicating the
+root of the chord), and a durations following that:
+@c
+@lilypond[verbatim]
+ \chords { c2 f4. g8 }
+@end lilypond
-Our last two examples show a way to setup the music for an orchestral
-score. When typesetting a piece for several instruments, you'll want to
-create a conductor's full score, alongside several individual parts.
+@noindent
+The result of @code{\chords} is a list of chords, and is equivalent
+to entering chords with @code{<<@dots{}>>}.
-LilyPond is well suited for this task. We will declare the music for
-each instrument individually, giving the music of each instrument its
-own name. These pieces of music are then combined in different
-@code{\score} blocks to produce different combinations of the score.
+Other chords can be created by adding modifiers, after a colon. The
+following example shows a few common modifiers:
+@c
+@lilypond[verbatim]
+ \chords { c2 f4:m g4:maj7 gis1:dim7 }
+@end lilypond
-This orchestral score example consists of three input files. In the
-first file, @file{os-music.ly}, we define the music for all
-instruments. This file will be used both for producing the score and
-the separate parts. Other files reference this file by doing
-@code{\include "os-music.ly"}.
+Printing chords is done by adding @code{\context ChordNames}
+before the chords thus entered:
+@c
+@lilypond[verbatim]
+ \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+@end lilypond
-If you were to run LilyPond on this file, no printable output would be
-produced.
+@cindex lead sheet
+When put together, chord names, lyrics and a melody form
+a lead sheet, for example,
@example
-% os-music.ly
-\header @{
- title = "Zo, goed lieverd?"
- subtitle = "How's, this babe?"
- composer = "JCN"
- opus = "1"
- piece = "Laid back"
-@}
-global = @{
- \time 2/4
- \skip 2*4 \bar "|."
-@}
-Key = \notes \key as \major
-flautoI = \notes\relative c'' @{
- f8 g f g f g f g
- bes as bes as bes as bes as
-@}
-flautoII = \notes\relative c'' @{
- as8 bes as bes R1 d4 ~ d
-@}
-tromboI = \notes\relative c'' @{
- c4. c8 c8 c4. es4 r as, r
-@}
-tromboII = \notes\relative c'' @{
- as4. as8 as8 as4. R1*1/2 as4 es'
-@}
-timpani = \notes\relative c, @{
- \times 2/3 @{ f4 f f @}
- \times 4/5 @{ as8 as as as as @}
- R1
-@}
-corno = \notes\relative c' @{
- bes4 d f, bes d f, bes d
+\score @{
+ <
+ \context ChordNames \chords @{ @emph{chords} @}
+ \addlyrics
+ \notes @emph{the melody}
+ \context Lyrics \lyrics @{ @emph{the text} @}
+ >
+ \paper @{ @}
@}
@end example
+@lilypond[]
+\score {
+ <
+ \context ChordNames \chords { r8 c2:sus4 f }
+ \addlyrics
+ \notes \relative c' {
+ \partial 8
+ c8
+ \times 2/3 { f g g } \times 2/3 { g4( a2) } }
+ \context Lyrics \lyrics { I want to break free __ }
+ >
+ \paper{ raggedright = ##t }
+}
+@end lilypond
-We will not go through the input line by line, but only indicate and
-explain the new elements.
+A complete list of modifiers, and other options for layout are in the
+reference manual section @ref{Chords}.
-@separate
-@example
-global = @{
- \time 2/4
- \skip 2*4 \bar "|.";
+@node Listening to output
+@section Listening to output
+
+@cindex sound
+@cindex MIDI
+
+MIDI (Musical Instrument Digital Interface) is a standard for
+connecting and recording digital instruments. A MIDI file is like a
+tape recording of a MIDI instrument. The @code{\midi} block makes the
+music go to a MIDI file, so you can listen to the music you entered.
+It is great for checking the music: octaves that are off, or
+accidentals that were mistyped, stand out very much when listening to
+the musical transcription.
+
+@code{\midi} can be used in similarly to @code{\paper @{ @}}, for
+example,
+@example
+\score @{
+ @var{..music..}
+ \midi @{ \tempo 4=72 @}
+ \paper @{ @}
@}
-@end example
+@end example
-Declare setting to be used globally. The @code{\skip} command produces
-no output, but moves forward in time: in this case, the duration of a
-half note (@code{2}), and that four times (@code{*4}). This brings us
-to the end of the piece, and we can set the end bar.
+Here, the tempo is specified using the @code{\tempo} command. In this
+case the tempo of quarter notes is set to 72 beats per minute. More
+information on auditory output is in the @ref{Sound} section in the
+notation manual.
-@separate
-@example
-Key = \notes \key as \major
+
+
+@node Titling
+@section Titling
+
+Bibliographic information is entered in a separate block, the
+@code{\header} block. The name of the piece, its composer, etc. are
+entered as assignment, within @code{\header @{ @dots{} @}}. For
+example,
+@example
+ \header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+ @}
+
+ \score @{ @dots{} @}
@end example
-Declare the key signature of the piece and assign it to the identifier
-@var{Key}. Later on, we'll use @code{\Key} for all staves except those
-for transposing instruments.
-@node The full score
-@subsection The full score
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex ly2dvi
-The second file, @file{input/tutorial/os-score.ly} reads the definitions of the first
-(@file{input/tutorial/os-music.ly}), and defines the @code{\score} block for the full
-conductor's score.
+When the file is processed by @code{ly2dvi}, the title and composer
+specified are printed above the music. The `tagline' is a short line
+printed at bottom of the last page, which normally says ``Lily was
+here, version @dots{}''. In the example above, it is replaced by the
+line ``small is beautiful''.
+Normally, the @code{\header} is put at the top of the file. However,
+for a document that contains multiple pieces (e.g. a etude book, or
+part with multiple movements), then the header can be put into the
+@code{\score} block as follows; in this case, the name of each piece
+will be printed before each movement:
-@example
-% os-score.ly
-\include "os-music.ly"
-\include "paper13.ly"
-#(set! point-and-click line-column-location)
-#(define text-flat '((font-relative-size . -2)
- (music "accidentals--1")))
+@cindex Lily was here
+@cindex signature line
+@cindex tag line
-\score @{
- <
- \global
- \property Score.BarNumber \override #'padding = #3
- \context StaffGroup = woodwind <
- \context Staff = flauti <
- \property Staff.midiInstrument = #"flute"
- \property Staff.instrument = "2 Flauti"
- \property Staff.instr = "Fl."
- \Key
- \context Voice=one @{ \voiceOne \flautoI @}
- \context Voice=two @{ \voiceTwo \flautoII @}
- >
- >
- \context StaffGroup = timpani <
- \context Staff = timpani <
- \property Staff.midiInstrument = #"timpani"
- \property Staff.instrument = #'(lines "Timpani" "(C-G)")
- \property Staff.instr = #"Timp."
- \clef bass
- \Key
- \timpani
- >
- >
- \context StaffGroup = brass <
- \context Staff = trombe <
- \property Staff.midiInstrument = #"trumpet"
- \property Staff.instrument = #`(lines "2 Trombe" "(C)")
- \property Staff.instr = #`(lines "Tbe." "(C)")
- \Key
- \context Voice=one \partcombine Voice
- \context Thread=one \tromboI
- \context Thread=two \tromboII
- >
- \context Staff = corni <
- \property Staff.midiInstrument = #"french horn"
- \property Staff.instrument = #`(lines "Corno"
- (columns "(E" ,text-flat ")"))
- \property Staff.instr = #`(lines "Cor."
- (columns "(E" ,text-flat ")"))
- \property Staff.transposing = #3
- \notes \key bes \major
- \context Voice=one \corno
- >
- >
- >
- \paper @{
- indent = 15 * \staffspace
- linewidth = 60 * \staffspace
- textheight = 90 * \staffspace
- \translator@{
- \HaraKiriStaffContext
- @}
+@example
+ \header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+ @}
+
+ \score @{ @dots{}
+ \header @{ piece = "Adagio" @}
@}
- \midi @{
- \tempo 4 = 75
+ \score @{ @dots{}
+ \header @{ piece = "Menuetto" @}
@}
-@}
@end example
-@center @strong{Zo, goed lieverd?}
-@sp 1
-@center How's, this babe?
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@sc{Laid back}
-@end flushleft
+More information on titling can be found in @ref{Invoking ly2dvi}.
-@lilypondfile{os-score.ly}
-@separate
+@node Single staff polyphony
+@section Single staff polyphony
+
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
+
+When different melodic lines are combined on a single staff, these are
+printed as polyphonic voices: each voice has its own stems, slurs
+and beams, and the top voice has the stems up, while the bottom voice
+has stems down.
+
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{ .. @}}), and combining those simultaneously, separating the
+voices with @code{\\}:
+
@example
-\include "os-music.ly"
+ < @{ a4 g2 f4-~ f4 @} \\
+ @{ r4 g4 f2 f4 @} >
@end example
-First, we need to include the music definitions we made in
-@file{os-music.ly}.
+@lilypond[relative 1]
+\context Staff < { a4 g2 f4-~ f4 } \\
+ { r4 g4 f2 f4 } >
+@end lilypond
-@separate
+For polyphonic music typesetting, spacer rests can also be convenient: these
+are rests that do not print. It is useful for filling up voices that
+temporarily do not play:
@example
-#(set! point-and-click line-column-location)
+ < @{ a4 g2 f4-~ f4 @} \\
+ @{ s4 g4 f2 f4 @} >
@end example
+@lilypond[relative 1]
+\context Staff < { a4 g2 f4-~ f4 } \\
+ { s4 g4 f2 f4 } >
+@end lilypond
-This piece of Scheme code sets the Scheme variable
-@code{point-and-click} to the value @var{line-column-location} (which
-itself is a Scheme procedure).
+Again, these expressions can be nested arbitrarily:
-Editing input files can be complicated if you're working with large
-files: if you're digitizing existing music, you have to synchronize
-the .ly file, the sheet music on your lap and the sheet music on the
-screen. The point-and-click mechanism makes it easy to find the
-origin of an error in the LY file: when you view the file with Xdvi
-and click on a note, your editor will jump to the spot where that note
-was entered. For more information, see @ref{Point and click}.
+@lilypond[fragment]
+<
+ \context Staff = staffA
+ \relative c''
+ < { a4 g2 f4-~ f4 } \\
+ { s4 g4 f2 f4 } >
+ \context Staff = staffB
+ < { \clef bass <<c g>>1 } \\
+ { f4 d e2 }
+ >
+>
+@end lilypond
-@separate
-@example
-#(define text-flat '((font-relative-size . -2)
- (music "accidentals--1")))
-@end example
+More features of polyphonic typesetting are in the notation manual
+in @ref{Polyphony}.
-When naming the tuning of the french horn, we'll need a piece of text
-with a flat sign. LilyPond has a mechanism for font selection and
-kerning called Scheme markup text (See @ref{Text markup}). The flat
-sign is taken from the music font, and its name is @code{accidentals--1}
-(The natural sign is called @code{accidentals-0}). The default font is
-too big for text, so we select a relative size of @code{-2}.
+@node Piano staves
+@section Piano staves
-@separate
-@example
- <
- \global
-@end example
-Of course, all staves are simultaneous and use the same global settings.
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\translator}
-@separate
+Piano music is always typeset in two staves connected by a brace.
+Printing such a staff is done similar to the polyphonic example in
+@ref{Combining music into compound expressions}:
@example
- \property Score.BarNumber \override #'padding = #3
+ < \context Staff = up @{ @dots{} @}
+ \context Staff = down @{ @dots{} @}
+ >
@end example
-LilyPond prints bar numbers at the start of each line, but
-unfortunately, they end up a bit too close to the staff in this
-example. A bar number internally is a Grob called @var{BarNumber}.
-BarNumber Grobs can be manipulated through their
-@var{side-position-interface}. One of the properties of a
-@var{side-position-interface} that can be tweaked is the
-@var{padding}: the amount of extra space that is put between this Grob
-and other Grobs. We set the padding to three staff spaces.
-
-You can find information on all these kind of properties in LilyPond's
-automatically generated documentation in
-@ifnottex
-@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
-@end ifnottex
-@iftex
-the online documentation.
-@end iftex
-
-@separate
+but now this entire expression must be interpreted as a
+@code{PianoStaff}:
@example
- \context StaffGroup = woodwind <
- \context Staff = flauti <
+ \context PianoStaff < \context Staff @dots{} >
@end example
-A new notation context: the @code{StaffGroup}. @code{StaffGroup} can
-hold one or more @code{Staff}'s, and will print a big bracket at the
-left of the score. Start a new staff group for the woodwind section
-(just the flutes in this case). Immediately after that, we start the
-staff for the two flutes, that also play simultaneously.
-@separate
-@example
- \property Staff.midiInstrument = #"flute"
-@end example
-Specify the instrument for MIDI output (see @ref{MIDI instrument
-names}).
+Here is a full-fledged example:
-@separate
-@example
- \property Staff.instrument = "2 Flauti"
- \property Staff.instr = "Fl."
-@end example
-And define the instrument names to be printed in the margin,
-@code{instrument} for the first line of the score, @code{instr} for the
-rest of the score.
+@lilypond[relative 0,fragment]
+\context PianoStaff
+ < \context Staff = up { \time 2/4
+ c4 c g' g }
+ \context Staff = down {
+ \clef bass c,, c' e c }
+ >
+@end lilypond
-@separate
-@example
- \Key
-@end example
-The flutes play in the default key.
+More information on formatting piano music is in @ref{Piano music}.
-@separate
+@node Setting variables
+@section Setting variables
+
+When the music is converted from notes to print, it is interpreted
+from left-to-right order, similar to what happens when we read
+music. During this step, context-sensitive information, such as the
+accidentals to print, and where barlines must be placed, are stored in
+variables. These variables are called @emph{translation properties}.
+The properties can also be manipulated from input files. Consider this input:
@example
- \context Voice=one @{ \voiceOne \flautoI @}
- \context Voice=two @{ \voiceTwo \flautoII @}
-@end example
-Last come the actual flute parts. Remember that we're still in
-simultaneous mode. We name both voices differently, so that LilyPond
-will actually create two Voice contexts. The flute parts are simple, so
-we specify manually which voice is which: @code{\voiceOne} forces the
-direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
-directions down.
+\property Staff.autoBeaming = ##f
+@end example
+It sets the property named @code{autoBeaming} in the current staff to
+@code{##f}, which means `false'. This property controls whether beams
+are printed automatically:
+@lilypond[relative 1,fragment,verbatim]
+ c8 c c c
+ \property Staff.autoBeaming = ##f
+ c8 c c c
+@end lilypond
-@separate
+@noindent
+LilyPond includes a built-in programming language, namely, a dialect
+of Scheme. The argument to @code{\property}, @code{##f}, is an
+expression in that language. The first hash-mark signals that a piece
+of Scheme code follows. The second hash character is part of the
+boolean value true (@code{#t}). Values of other types may be
+entered as follows:
+@itemize @bullet
+@item a string, enclosed in double quotes, for example,
@example
- >
- >
+ \property Staff.instrument = #"French Horn"
@end example
-Close the flutes staff and woodwind staff group.
-
-@separate
+@item a boolean: either @code{#t} or @code{#f}, for true and false
+respectively, e.g.
@example
- \property Staff.instrument = #'(lines "Timpani" "(C-G)")
+ \property Voice.autoBeaming = ##f
+ \property Score.skipBars = ##t
@end example
-The timpani staff only shows a new piece of scheme markup, it sets two
-lines of text.
-@separate
+@item a number, such as
@example
- \context Voice=one \partcombine Voice
- \context Thread=one \tromboI
- \context Thread=two \tromboII
+ \property Score.currentBarNumber = #20
@end example
-You have seen the notation contexts Staff and Voice, but here's a new
-one: Thread. One or more Threads can be part of a Voice. The Thread
-takes care of note heads and rests, the Voice combine note heads onto a
-stem.
-
-For the trumpets we use the automatic part combiner (see @ref{Automatic
-part combining}) to combine the two simultaneous trumpet parts onto the
-trumpet staff. Each trumpet gets its own Thread context, which must be
-named @code{one} and @code{two}). The part combiner makes these two
-threads share a Voice when they're similar, and splits the threads up
-when they're different.
-@separate
+@item a symbol, which is introduced by a quote character, as in
@example
- \property Staff.instrument = #`(lines "Corno"
- (columns "(E" ,text-flat ")"))
+ \property Staff.crescendoSpanner = #'dashed-line
@end example
-The french horn has the most complex scheme markup name, made up of two
-lines of text. The second line has three elements (columns), the @code{(E},
-the flat sign @code{text-flat} that we defined before and a final @code{")"}.
-Note that we use a backquote instead of an ordinary quote at the
-beginning of the Scheme expression to be able to access the
-@code{text-flat} identifier, `unquoting' it with a @code{,}.
-@separate
+@item a pair, which is also introduced by a quote character, like in
+the following statements, which set properties to the pairs (-7.5, 6)
+and (3, 4) respectively:
+
@example
- \property Staff.transposing = #3
+ \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
+ \property Staff.timeSignatureFraction = #'(3 . 4)
@end example
-The french horn is to be tuned in E-flat, so we tell the MIDI backend to
-transpose this staff by three steps.
-Note how we can choose different tuning for entering, printing and
-playing, using @code{\transpose} and the MIDI Staff property
-@var{transposing}.
-@separate
+@end itemize
+
+There are many different properties, and not all of them are listed in
+this manual. However, the internal documentation lists them all in the
+@internalsref{All translation properties}, and most properties
+are demonstrated in one of the
+@ifhtml
+@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
+@end ifhtml
+@ifnothtml
+tips-and-tricks
+@end ifnothtml
+examples.
+
+
+@node Fine tuning layout
+@section Fine tuning layout
+
+Sometimes it is necessary to change music layout by hand. When music
+is formatted, layout objects are created for each symbol. For
+example, every clef and every note head is represented by a layout
+object. These layout objects also carry variables, which we call
+@emph{layout properties}. By changing these variables from their
+values, we can alter the look of a formatted score:
+
+@lilypond[verbatim,relative 0]
+ c4
+ \property Voice.Stem \override #'thickness = #3.0
+ c4 c4 c4
+@end lilypond
+
+@noindent
+In the example shown here, the layout property @code{thickness} (a
+symbol) is set to 3 in the @code{Stem} layout objects of the current
+Voice. As a result, the notes following @code{\property} have thicker
+stems.
+
+In most cases of manual overrides, only a single object must be
+changed. This can be achieved by prefixing @code{\once} to the
+@code{\property} statement, i.e.
+
@example
- \notes \key bes \major
+ \once \property Voice.Stem \set #'thickness = #3.0
@end example
-Therefore, it has a different key.
-@separate
+@lilypond[relative 0]
+ c4
+ \once \property Voice.Stem \set #'thickness = #3.0
+ c4 c4 c4
+@end lilypond
+
+@noindent
+Some overrides are so common that predefined commands are provided as
+a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
+commands are described in
+@ifhtml
+the
+@end ifhtml
+@ref{Notation manual}, under the sections for slurs and stems
+respectively.
+
+The exact tuning possibilities for each type of layout object are
+documented in the internal documentation of the respective
+object. However, many layout objects share properties, which can be
+used to apply generic tweaks. We mention a couple of these:
+
+@itemize @bullet
+@item The @code{extra-offset} property, which
+@cindex @code{extra-offset}
+has a pair of numbers as value, moves around objects in the printout.
+The first number controls left-right movement; a positive number will
+move the object to the right. The second number controls up-down
+movement; a positive number will move it higher. The unit of these
+offsets are staff-spaces. The @code{extra-offset} property is a
+low-level feature: the formatting engine is completely oblivious to
+these offsets.
+
+In the following example example, the second fingering is moved a
+little to the left, and 1.8 staff space downwards:
+
+@cindex setting object properties
+
+@lilypond[relative 1,verbatim]
+\stemUp
+f-5
+\once \property Voice.Fingering
+ \set #'extra-offset = #'(-0.3 . -1.8)
+f-5
+@end lilypond
+
+@item
+Setting the @code{transparent} property will make an object be printed
+in `invisible ink': the object is not printed, but all its other
+behavior is retained. The object still takes space, it takes part in
+collisions, and slurs, ties and beams can be attached to it.
+
+@cindex transparent objects
+@cindex removing objects
+@cindex invisible objects
+The following example demonstrates how to connect different voices
+using ties. Normally ties only happen between notes of the same
+voice. By introducing a tie in a different voice, and blanking a stem
+in that voice, the tie appears to cross voices:
+
+@lilypond[fragment,relative 1,verbatim]
+\context Staff < {
+ \once \property Voice.Stem \set #'transparent = ##t
+ b8~ b8
+ } \\ {
+ b[ g8]
+ } >
+@end lilypond
+
+@item
+The @code{padding} property for objects with
+@cindex @code{padding}
+@code{side-position-interface} can be set to increase distance between
+symbols that are printed above or below notes. We only give an
+example; a more elaborate explanation is in @ref{Constructing a
+tweak}:
+
+@lilypond[relative 1]
+ c2-\fermata
+ \property Voice.Script \set #'padding = #3
+ b2-\fermata
+@end lilypond
+
+@end itemize
+
+More specific overrides are also possible. The notation manual
+discusses in depth how to figure out these statements for yourself, in
+@ref{Tuning output}.
+
+@node Organizing larger pieces
+@section Organizing larger pieces
+
+When all of the elements discussed earlier are combined to produce
+larger files, the @code{\score} blocks get a lot bigger, because the
+music expressions are longer, and, in the case of polyphonic and/or
+orchestral pieces, more deeply nested.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions.
+An identifier is assigned as follows:
@example
- indent = 15 * \staffspace
- linewidth = 60 * \staffspace
+ namedMusic = \notes @{ @dots{}
@end example
-We specify a big indent for the first line and a small linewidth for this
-tutorial.
-@separate
+The contents of the music expression @code{namedMusic}, can be used
+later by preceding the name with a backslash, i.e. @code{\namedMusic}.
+In the next example, a two note motive is repeated thrice by using
+variable substitution:
+
+@lilypond[singleline,verbatim]
+seufzer = \notes {
+ dis'8 e'8
+}
+\score { \notes {
+ \seufzer \seufzer \seufzer
+} }
+@end lilypond
-Usually, LilyPond's predefined setup of notation contexts (Thread,
-Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
-want a different type of Staff context.
+The name of an identifier should only have alphabetic characters only,
+and no numbers, underscores or dashes. The assignment should be
+outside of the @code{\score} block.
+It is possible to use variables for many other types of objects in the
+input. For example,
+@example
+ width = 4.5\cm
+ name = "Wendy"
+ aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables:
@example
- \translator@{
- \HaraKiriStaffContext
+ \score @{
+ \notes @{ c4^\name @}
+ \paper @{
+ \aFivePaper
+ linewidth = \width
@}
+ @}
@end example
-In orchestral scores, it often happens that one instrument has only
-rests during one line of the score. The @code{HaraKiriStaffContext} can
-be used as a regular @code{StaffContext} drop-in and will take care of
-the automatic removing of empty staves.
+More information on the possible uses of identifiers is in the
+technical manual, in @ref{Scheme datatypes}.
+
-@node Extracting an individual part
-@subsection Extracting an individual part
+@node An orchestral part
+@section An orchestral part
-The third file, @file{os-flute-2.ly} also reads the definitions of the
-first (@file{os-music.ly}), and defines the @code{\score} block for the
-second flute part.
+In orchestral music, all notes are printed twice: both in a part for
+the musicians, and in a full score for the conductor. Identifiers can
+be used to avoid double work: the music is entered once, and stored in
+variable. The contents of that variable is then used to generate
+both the part and the score.
+It is convenient to define the notes in a special file, for example,
+suppose that the @file{horn-music.ly} contains the following part of a
+horn/bassoon duo.
@example
-\include "os-music.ly"
-\include "paper16.ly"
+hornNotes = \notes \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
+Then, an individual part is made by putting the following in a file:
+@example
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
\score @{
- \context Staff <
- \property Score.skipBars = ##t
- \property Staff.midiInstrument = #"flute"
- \global
- \Key
- \flautoII
- >
- \header @{
- instrument = "Flauto II"
- @}
- \paper @{
- linewidth = 80 * \staffspace
- textheight = 200 * \staffspace
- @}
- \midi @{
- \tempo 4 = 75
- @}
+ \notes \transpose c' f \hornNotes
@}
@end example
+The @code{\include} command substitutes the contents of the file at
+this position in the file, so that @code{hornNotes} is defined
+afterwards. The code @code{\transpose f c'} indicates that the
+argument, being @code{\hornNotes}, should be transposed by a fifth
+downwards: sounding @code{f} is denoted by notated @code{c'}, which
+corresponds with tuning of a normal French Horn in F. The
+transposition can be seen in the following output:
-@center @strong{Zo, goed lieverd?}
-@sp 1
-@center How's, this babe?
-@center @emph{Flauto II}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@sc{Laid back}
-@end flushleft
-@lilypondfile{os-flute-2.ly}
-
-
-Because we separated the music definitions from the @code{\score}
-instantiations, we can easily define a second score with the music of
-the second flute. This then is the part for the second flute player.
-Of course, we make separate parts for all individual instruments.
+@lilypond[singleline]
+\score {
+ \notes \transpose f c' \notes \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+}
+}
+@end lilypond
-@separate
+In ensemble pieces, one of the voices often does not play for many
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital R, and followed by a duration (1
+for a whole note, 2 for a half note, etc.) By multiplying the
+duration, longer rests can be constructed. For example, the next rest
+takes 3 measures in 2/4 time:
@example
- \flautoII
+ R2*3
@end example
-In this individual part the second flute has a whole staff for itself,
-so we don't want to force stem or tie directions.
-@separate
+When printing the part, the following @code{skipBars} property must be
+set to false, to prevent the rest from being expanded in three one bar
+rests:
@example
- \header @{
- instrument = "Flauto II"
- @}
+ \property Score.skipBars = ##t
@end example
-The @code{\header} definitions were also read from @file{os-music.ly},
-but we need to set the instrument for this particular score.
+Prepending the rest and the property setting above, leads to the
+following result:
-@separate
+@lilypond[singleline]
+\score {\notes { \transpose f c' \relative c { \time 2/4
+\property Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d } }}
+@end lilypond
+
+The score is made by combining all of the music in a @code{\score}
+block, assuming that the other voice is in @code{bassoonNotes}, in the
+file @file{bassoon-music.ly}:
@example
- \property Score.skipBars = ##t
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+\score @{
+ \simultaneous @{
+ \context Staff = hornStaff \hornNotes
+ \context Staff = bsnStaff \bassoonNotes
+ @} @}
@end example
-In the conductor's full score, all bars with rests are printed, but for
-the individual parts, we want to contract pieces of consecutive empty
-bars. LilyPond will do this if Score's @var{skipBars} property to
-true.
+
+This would lead to the simple score depicted below:
+
+@lilypond[singleline]
+\score {
+ \notes \relative c \simultaneous {
+ \context Staff = hornStaff { \time 2/4
+ R2*3
+ r4 f8 a cis4 f e d }
+ \context Staff = fagStaff { \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f }
+ } }
+@end lilypond
+
+More in-depth information on preparing parts and scores is in the
+notation manual, in @ref{Orchestral music}.
@node Integrating text and music
@section Integrating text and music
-Sometimes, you might want to use music examples in a text that you are
-writing. For example, if you are writing a musicological treatise, a
-songbook, or (like us) the LilyPond manual. You can make such texts by
-hand, simply by importing a PostScript figure into your wordprocessor.
-However, there is a also an automated procedure:
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, music in
-If you use HTML, La@TeX{} or texinfo, you can mix text and LilyPond
-code. A script called @code{lilypond-book} will extract the music
+Sometimes you might want to use music examples in a text that you are
+writing (for example, a musicological treatise, a songbook, or (like us)
+the LilyPond manual). You can make such texts by hand, simply by
+importing a PostScript figure into your word processor. However,
+there is an automated procedure to reduce the amount of work.
+
+If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
+code. A script called @code{lilypond-book} will extract the music
fragments, run LilyPond on them, and put back the resulting notation.
-This utility program is described fully in the chapter @ref{Insert
-music snippets into your texts using lilypond-book}. Here we show a
-small example. Since the example also contains explanatory text, we
-won't comment on the contents.
+This program is fully described in @ref{lilypond-book manual}. Here
+we show a small example; since the example contains also explanatory
+text, we will not comment it further:
@example
\documentclass[a4paper]@{article@}
c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
@} @}
\end@{lilypond@}
+
Notice that the music line length matches the margin settings of the
document.
c'4
\end@{lilypond@}
-In the example you see here, a number of things happened: a
+In the example you see here, two things happened: a
\verb+\score+ block was added, and the line width was set to natural
-length. You can specify many more options using \LaTeX style options
-in brackets:
+length. You can specify options by putting them in brackets:
-\begin[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]@{lilypond@}
- c'4 f bes es
+\begin[26pt,verbatim]@{lilypond@}
+ c'4 f16
\end@{lilypond@}
-\texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
-the default music size, \texttt@{fragment@} adds a score block,
-\texttt@{relative@} uses relative mode for the fragment, and
-\texttt@{intertext@} specifies what to print between the
-\texttt@{verbatim@} code and the music.
-
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
-
-\lilypondfile[printfilename]@{sammartini.ly@}
+If you want to include large examples into the text, it is more
+convenient to put it in a separate file:
-The \texttt@{printfilename@} option adds the file name to the output.
+\lilypondfile@{screech-boink.ly@}
\end@{document@}
@end example
-Under Unix, you can view the results as follows.
+Under Unix, you can view the results as follows:
@example
$ cd input/tutorial
+$ mkdir -p out/
$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.3.146
+lilypond-book (GNU LilyPond) 1.7.23
Reading `input/tutorial/lilbook.tex'
-Reading `input/tutorial/sammartini.ly'
+Reading `input/screech-boink6.ly'
@var{lots of stuff deleted}
Writing `out/lilbook.latex'
$ cd out
$ xdvi lilbook
@end example
-Notice the @code{outdir} option to lilypond-book. Running lilypond-book
-and running latex creates a lot of temporary files, and you wouldn't want
-those to clutter up your working directory. Hence, we have them created
-in a separate subdirectory.
+Running lilypond-book and running latex creates a lot of temporary
+files, and you would not want those to clutter up your working
+directory. The @code{outdir} option to lilypond-book creates the
+temporary files in a separate subdirectory @file{out}.
-The result more or less looks like this:
+The result looks more or less like this:
@separate
In a lilypond-book document, you can freely mix music and text. For
example:
@lilypond
- \score { \notes \relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
- } }
+\score {
+ \notes \relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+ }
+ \paper {
+ raggedright = ##t
+ }
+}
@end lilypond
+
Notice that the music line length matches the margin settings of the
document.
c'4
@end lilypond
-In the example you see here, a number of things happened: a
-@code{\score} block was added, and the line width was set to natural
-length. You can specify many more options using La@TeX{} style options
-in brackets:
+In the example you see here, two things happened: a
+@code{score} block was added, and the line width was set to natural
+length. You can specify options by putting them in brackets:
-@lilypond[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]
- c'4 f bes es
+@lilypond[26pt,verbatim]
+ c'4 f16
@end lilypond
-@code{verbatim} also shows the LilyPond code, @code{11pt} selects
-the default music size, @code{fragment} adds a score block,
-@code{relative} uses relative mode for the fragment, and
-@code{intertext} specifies what to print between the
-@code{verbatim} code and the music.
-
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
-
-@lilypondfile[printfilename]{sammartini.ly}
-
-The @code{printfilename} option adds the file name to the output.
-@node End of tutorial
-@section End of tutorial
-
-This is the end of the tutorial. If you came up till here, and
-have understood everything, then you're now an accomplished lilypond
-hacker. From here, you can try fiddling with input
-files, coming back to the reference manual for information.
-Also don't forget to check out the
-@ifhtml
-@uref{../../templates/out-www/templates.html,templates},
-@uref{../../test/out-www/test.html,example} and
-@uref{../../regression/out-www/regression.html,feature test}
-snippets.
-@end ifhtml
-@ifnothtml
-templates, example and feature test snippets.
-@end ifnothtml
-If you want to see real action lilypond, then head over to
-@uref{http://www.mutopiaproject.org}, which has many examples of
-classical music typeset by LilyPond.
-
+If you want to include large examples into the text, it is more
+convenient to put it in a separate file:
+@lilypondfile{screech-boink.ly}