@c -*-texinfo-*-
+@c This file is part of lilypond.tely
@c TODO:
-@c * LilyPond Lilypond lilypond (sometimes: the program)
@c * more details about running lilypond; error messages,
@c compiling/viewing (emacs?)
-@c * where to go from First steps+More basics?
+@c * where to go from First steps+More basics?
+
+@c Your first LilyPond score in 10 minutes?
@node Tutorial
@chapter Tutorial
-@html
-<!--- @@WEB-TITLE@@=Tutorial --->
-@end html
+This tutorial starts with a short introduction to the LilyPond music
+language. After this first contact we will show you how to produce
+printed output. Then you will be able to create and print your own
+sheets of music.
+
+@ifhtml
+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.
+Try it on this image
+
+@lilypond[fragment,quote,raggedright,relative=2]
+c-\markup { \bold \huge { Click here. } }
+@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.
@menu
-* First steps:: Music language of LilyPond
-* Running LilyPond:: Printing music
-* More basics::
+* First steps::
+* Running LilyPond::
+* More about pitches::
+* Entering ties::
+* Automatic and manual beams::
+* Octave entry::
+* Music expressions explained::
+* More staves::
+* Adding articulation marks to notes::
+* Combining notes into chords::
+* Basic rhythmical commands::
+* Commenting input files::
* Printing lyrics::
* A lead sheet::
* Listening to output::
-* More movements :: Joining separate pieces of music
-* Organising larger pieces::
-* 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
+* Adding titles::
+* Single staff polyphony::
+* Piano staves::
+* Organizing larger pieces::
+* An orchestral part::
+* Integrating text and music::
@end menu
-Operating is done through text files: To print a piece of music, you
-enter the music in a file. When LilyPond is run (normally using the
-program @code{ly2dvi}) on that file, another file containing formatted
-sheet music, is produced. That file may be printed or viewed.
-
-This tutorial starts with a small introduction to the LilyPond music
-language. After this first contact, we will show which commands to
-run to produce printed output, so 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 @htmlref{note name}, from @samp{a}
-through @samp{g}. So if you enter
+The first example demonstrates how to enter the most elementary piece
+of music, a scale. A note can be entered by typing its name, from
+@samp{a} through @samp{g}. So, if you enter
@example
c d e f g a b
@end example
@noindent
-then the result looks like this:
+the result looks like this
-@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]
+@lilypond[fragment,quote,notime,relative=1]
c d e f g a b
@end lilypond
-We will continue with this format: First we show a snippet of input,
-then the resulting output.
-
-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:
+The duration of a note is specified by a number after the note name.
+@samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
+@samp{4} for a @rglos{quarter note} and so on
@example
a1 a2 a4 a16 a32
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
+@c FIXME: have NOTIME also remove Score.timing?
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+\set Staff.autoBeaming = ##f
+{ a1 a2 a4 a16 a32 s16_" " }
@end lilypond
-If you do not specify a @rglos{duration}, the previous one is used:
+If you do not specify a @rglos{duration}, the duration last entered is
+used for the next notes. The duration of the first note in input
+defaults to a quarter
@example
-a4 a a2 a
+a a8 a a2 a
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a a a2 a s16_" " }
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a a8 a a2 a s16_" " }
@end lilypond
-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}
+Rests are entered just like notes, but with the name @samp{r}
+
+@cindex rests
@example
-cis1 ees fisis aeses
+r2 r4 r8 r16
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+r2 r4 r8 r16 s16_" "
@end lilypond
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}
@example
a2. a4 a8. a16
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a2. a4 a8. a16 s16_" " }
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a2. a4 a8. a16 s16_" " }
@end lilypond
-Entering pitches and durations is fully explained in @ref{Pitches} and
-@ref{Durations}.
-
-
The @rglos{meter} (or @rglos{time signature}) can be set with the
-@code{\time} command:
+@code{\time} command
@example
\time 3/4
\time 4/4
@end example
-@c a clef here may lead to confusion
-@lilypond
-\property Staff.Clef \set #'transparent = ##t
+@c A clef here may lead to confusion, remove it.
+@lilypond[fragment,quote]
+\override Staff.Clef #'transparent = ##t
\time 3/4
s4_" "
\time 6/8
s16_" "
@end lilypond
-Time signatures and other timing commands are described in @ref{Time
-signature}.
-
-
-The @rglos{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 definitely treble.
+@c in Dutch, it is violin.
+@c in English it is definitely treble.
@example
\clef treble
\clef bass
\clef tenor
@end example
-@lilypond[notime]
-\property Score.timing = ##f
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
\clef violin
s4_" "
\clef bass
s16_" "
@end lilypond
-Clefs are fully explained in @ref{Clef}.
-
-
-When you enter these commands in a file, you must to enclose them in
-@code{\notes @{@dots{}@}}. This lets LilyPond know that music (as
-opposed to @rglos{lyrics}) follows:
+@ignore
+To recognize names like @samp{c} and @samp{d} as pitches, they have to
+be entered inside a so-called @code{\notes} block. This block is
+formed by enclosing notes and commands are enclosed in curly braces
+@code{@{@tie{}@dots{}@tie{}@}} and adding the keyword @code{\notes} before
+the opening brace
@example
-\notes @{
+@{
\time 3/4
\clef bass
c2 e4 g2.
- f4 e d c2.
+ f4 e d c2 r4
@}
@end example
-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 source file looks like:
+Now the piece of music is almost ready to be printed. Enclose
+the @code{\notes} block in a @code{\score} block
@example
\score @{
\time 3/4
\clef bass
c2 e4 g2.
- f4 e d c2.
+ f4 e d c2 r4
@}
- \paper @{ @}
@}
@end example
-@lilypond[noindent]
-\score {
- \notes {
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- \paper {
- linewidth = 55 * \staffspace
- }
+@noindent
+and the music will be converted to printable output.
+@end ignore
+
+Remember to enclose the notes and commands in curly braces
+@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
+
+@lilypond[fragment,quote,noindent,linewidth=55\staffspace]
+{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
}
@end lilypond
+For more elaborate information on
+
+@quotation
+@table @asis
+@item Entering pitches and durations
+see
+@ref{Pitches}, and @ref{Durations}.
+@item Clefs
+see @ref{Clef}.
+@item Rests
+see @ref{Rests}.
+@item Time signatures and other timing commands
+see @ref{Time signature}.
+@end table
+@end quotation
+
@node Running LilyPond
@section Running LilyPond
+@c FIXME: let's not be so casual about Emacs and VIM, but rather
+@c instruct (how) to use them; let advanced user figure-out what
+@c commands to type?
+
+@c
+@c We don't have enough space to explain either VIM
+@c or Emacs non-advanced users, and I fear that both editors will only
+@c confuse newbies. I vote for keeping the material in footnotes.
+@c
+@c --hwn
+
In the last section we explained what kind of things you could enter
-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 MS 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
-@file{test.ly}:
+in a LilyPond file. In this section we will 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, refer to
+@c FIXME lousy reference.
+the file @file{INSTALL.txt}.} In your text editor, enter the following
+input and save the file as @file{test.ly}
-@quotation
@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
+@{ c'4 e' g' @}
@end example
-@end quotation
-@cindex ly2dvi
-
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal)
-
-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
-then adds the titling and page layout instructions. To process
-@file{test.ly} with @code{ly2dvi}, proceed as follows:
+@noindent
+To process @file{test.ly}, proceed as follows
-@quotation
@example
-ly2dvi -p test.ly
+lilypond test.ly
@end example
-@end quotation
-You will see the following on your screen:
+@noindent
+You will see something resembling
-@quotation
@example
-GNU LilyPond 1.7.16
-Now processing: `/home/fred/ly/test.ly'
+lilypond (GNU LilyPond) 2.2.0
+Running lilypond...
+Now processing `/home/fred/ly/test.ly'
Parsing...
Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PDF output to `test.pdf'...
+@emph{... more interesting stuff ... }
DVI output to `test.dvi'...
+PDF output to `test.pdf'...
+PS output to `test.ps'...
@end example
-@end quotation
+
@cindex DVI file
@cindex Viewing music
@cindex xdvi
-
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can
-print or view. For example, viewing PDF can be done with 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
-@quotation
-@example
- gv test.pdf
- ghostview test.pdf
- ggv test.pdf
- kghostview test.pdf
- xpdf test.pdf
- gpdf 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}
-@c KDVI doesn't grok the PS specials.
-@c or
-@c @code{kdvi test.dvi}
-@c
-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.
-
-
-@cindex Ghostscript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-@cindex PDF
-
-If you are familiar with @TeX{}, be warned: do not use other DVI
-drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code
-and will not render correctly with other DVI drivers besides
-@code{dvips}.
-
+@noindent
+The result is the file @file{test.pdf}@footnote{For @TeX{}
+aficionados: 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
+} which you can print or with the standard facilities of your
+operating system.@footnote{If your system does not have any tools
+installed, you can try @uref{Ghostscript,
+http://www.cs.wisc.edu/~ghost/}, a freely available package for
+viewing and printing PDF and PostScript files.}
+On Windows, start up a text-editor@footnote{Any simple or
+programmer-oriented editor will do, for example Notepad. Do not use a
+word processor, its formatting codes will confuse LilyPond.} and enter
-Various commands for formatting and printing music are detailed in
-@ref{Invoking LilyPond}.
-
-
-@unnumberedsubsec Windows users
-
-Windows users can start the terminal 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. When Cygwin's @code{XFree86} X11
-window system is installed along with @code{tetex-x11} and
-@code{ghostscript-x11} packages, then the @code{dvi} output may be
-viewed with @code{xdvi test.dvi} as described above. If you have
-installed a PostScript/PDF viewer, such as @code{GSView} from
-@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
-with:
-@quotation
-@example
-@code{gsview32 test.pdf}
-@end example
-@end quotation
-Printing may be done by executing
-@quotation
-@example
-@code{gsview32 /s test.pdf}
-@end example
-@end quotation
-
-
-@node More basics
-@section More basics
-
-We continue with the introduction of more musical constructs. Normal
-rests are entered just like notes with the name ``@code{r}'':
-
-@quotation
@example
-r2 r4 r8 r16
+@{ c'4 e' g' @}
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
-@end lilypond
-@end quotation
-@separate
-
-Rests are described in full detail in @ref{Rests}.
+Save it on the desktop as @file{test.ly} and make sure that it is not
+called @file{test.ly.TXT}. Double clicking @file{test.ly} will process
+the file and show the resulting PDF file.
-@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...
+@node More about pitches
+@section More about pitches
-@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{}) pitch is made by adding @samp{is} to
+the name, a @rglos{flat} (@texiflat{}) pitch 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]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-c'4 c'' c''' \clef bass c c,
-@end lilypond
-@end quotation
-@separate
-
-A tie is created by adding a tilde ``@code{~}'' to the first note
-being tied.
-@quotation
-@lilypond[fragment,verbatim]
-g'4-~ g' a'2-~ a'4
-@end lilypond
-@end quotation
-@separate
-A tie is different from a slur. 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-)
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
@end lilypond
-The notation manual discusses ties in @ref{Ties}.
+@cindex key signature, setting
+The key signature is set with the command @code{\key}, followed by
+a pitch and @code{\major} or @code{\minor}
-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]
-\property Staff.TimeSignature = \turnOff
+@lilypond[fragment,quote,notime,fragment]
\key d \major
g'1
\key c \minor
g'
@end lilypond
-@end quotation
+@noindent
+Key signatures together with the pitches (including alterations) are
+used to determine when to print accidentals. This is a
+feature that often causes confusion to newcomers, so let us explain it
+in more detail.
-@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.
+LilyPond makes a sharp distinction between musical content and
+layout. The alteration (flat, natural or sharp) of a note is part of
+the pitch, and is therefore musical content. Whether an accidental (a
+flat, natural or sharp @emph{sign}) is printed in front of the
+corresponding note is a question of layout. Layout is something that
+follows rules, so accidentals are printed automatically according to
+those rules. The pitches in your music are works of art, so they will
+not be added automatically, and you must enter what you want to hear.
-@quotation
-@example
-\score @{
- \notes @{
- \time 4/4
- \key d \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
- @}
- \paper @{ @}
-@}
-@end example
+In this example
-@lilypond
-\score {
- \notes {
- \time 4/4
- \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 }
-}
+@lilypond[quote,notime,fragment]
+\key d \major
+d' cis' fis'
@end lilypond
-@end quotation
-@c accidentals...
-There are some interesting points to note in this example.
-Accidentals (sharps and flats) do not have to be marked explicitly:
-you just enter the note name, and an accidental is printed
-automatically, only when necessary. 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 using standard notation conventions.
-
-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 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 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.
-@c do not use commas or quotes in this sentence
-For example: @code{c f} goes up; @code{c g} goes down:
+@noindent
+no note gets an explicit accidental, but you still must enter
-@quotation
@example
-\relative c'' @{
- c f c g c
-@}
+\key d \major
+d cis fis
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f c g c
-}
-@end lilypond
-@end quotation
-@separate
-
-
-Since most music has small intervals, in relative mode pieces can be
-written almost without using octavation quotes.
+@noindent
+The code @samp{d} does not mean `print a black dot just below the
+staff.' Rather, it means: `a note with pitch D-natural.' In the key
+of A-flat, it does get an accidental
-@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.
-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:
+@lilypond[quote,notime,fragment]
+\key as \major
+d'
+@end lilypond
-@quotation
@example
-\relative c'' @{
- c f, f c' c g' c,
-@}
+\key as \major
+d
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f, f c' c g' c,
-}
-@end lilypond
-@end quotation
-@separate
+Adding all alterations explicitly might require a little more effort
+when typing, but the advantage is that transposing is easier, and
+music can be printed according to different conventions. See
+@ref{Accidentals}, for some examples how accidentals can be printed
+according to different rules.
-Here is an example of the difference between relative mode and
-``normal'' (non-relative) mode:
+For more information on
@quotation
-@example
-\relative a @{
-\clef bass
- a d a e d c' d'
-@}
-@end example
+@table @asis
+@item Accidentals
+see @ref{Accidentals}.
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative a {
-\clef bass
- a d a e d c' d'
-}
-@end lilypond
+@item Key signature
+see @ref{Key signature}.
+@end table
@end quotation
-@separate
-@quotation
-@example
-\clef bass
- a d a e d c' d'
-@end example
+@node Entering ties
+@section Entering ties
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\clef bass
- a d a e d c' d'
+@cindex tie
+A tie is created by appending a tilde @samp{~} to the first note
+being tied
+
+@lilypond[quote,notime,fragment,verbatim,relative=3]
+g4~ g a2~ a4
@end lilypond
-@end quotation
-@separate
-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:
+For more information on Ties see @ref{Ties}.
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4-( c16-)-( cis d e c cis d e-)-( d4-)
-@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 does not
-@c have a phrasing slur. The problem is that we do not want the slur
-@c and the Phrasing slur to collide. We are trying to make a good
-@c impression here.
+@node Automatic and manual beams
+@section Automatic and manual beams
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
-@end lilypond
-@end quotation
-@separate
+@cindex beams, by hand
+Beams are drawn automatically
-Beams are drawn automatically, but if you do not like the choices, you
-can enter beams 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-]
+@lilypond[quote,fragment,relative=2,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 are then grouped inside @code{<} and @code{>}, as is
-demonstrated here:
+@noindent
+If you do not like where beams are put, they can be entered by
+hand. Mark the first note to be beamed with @samp{[} and the last one
+with @samp{]}.
-@quotation
-@lilypond[fragment,verbatim]
-<
- \context Staff = staffA { \clef violin c'' }
- \context Staff = staffB { \clef bass c }
->
+@lilypond[quote,fragment,relative=2,verbatim]
+a8[ ais] d[ es r d]
@end lilypond
-@end quotation
-In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves. It does not matter what names you give, as long
-as each staff has a different name. If you give them the same name,
-they are assumed to belong on the same staff, and will be printed like
-that.
+For more information on beams, see @ref{Beaming}.
-@separate
-We can now typeset a melody with two staves:
+Here are key signatures, accidentals and ties in action
-@quotation
-@lilypond[verbatim,singleline]
-\score {
- \notes
- < \context Staff = staffA {
- \time 3/4
- \clef violin
- \relative c'' {
- e2-( d4 c2 b4 a8-[ a-]
- b-[ b-] g-[ g-] a2.-) }
- }
- \context Staff = staffB {
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- >
- \paper {}
-}
-@end lilypond
-@end quotation
+@example
+@{
+ \time 4/4
+ \key g \minor
+ \clef violin
+ r4 r8 a8 gis4 b
+ a8 d4.~ d e8
+ fis4 fis8 fis8 eis4 a8 gis~
+ gis2 r2
+@}
+@end example
-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.
+@ignore
+FIXME
+ugr: removing the ignore block, leaving the comment line below
+@c TODO: use relative mode, verbatim, junk \transpose and above @example
+@end ignore
-@separate
-Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
-@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c->
+@lilypond[fragment,quote,noindent,linewidth=50\staffspace]
+\transpose c c' {
+ \time 4/4
+ \key g \minor
+ \clef violin
+ r4 r8 a8 gis4 b
+ a8 d4.~ d e8
+ fis4 fis8 fis8 eis4 a8 gis~
+ gis2 r2
+}
@end lilypond
-@end quotation
-@separate
-Similarly, fingering indications can be added to a note using @code{-}
-and the digit to be printed.
-@lilypond[verbatim,relative 1]
- c-3 e-5 b-2 a-1
-@end lilypond
+@cindex accidentals
-
+@noindent
+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 line breaks are in the
+source file. Finally, the order in which time, key and clef changes
+are entered is not relevant: in the printout, these are ordered
+according to standard notation conventions.
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
-c-\ff c-\mf
-@end lilypond
-@end quotation
-@separate
-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,relative 1]
-c2-\< c2-\!-\ff c2-\> c2-\!
-@end lilypond
-@end quotation
-@separate
+@node Octave entry
+@section Octave entry
-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
-@end quotation
-@separate
+@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...
-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
+@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
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
+c'4 c'' c''' \clef bass c c,
@end example
-@lilypond[relative 0, fragment]
-\slurUp
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
+
+@lilypond[quote,notime,fragment]
+c'4 c'' c''' \clef bass c c,
@end lilypond
-@end quotation
-@separate
+An example of the use of quotes is in the following Mozart fragment
-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.
-@lilypond[relative 1,verbatim,fragment]
- \partial 8
- f8 c2 d e
+@lilypond[quote,raggedright,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
+
+@noindent
+The last 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.
+@ignore
+FIXME: move to notation manual?
+ You must also give a note
+from which relative mode starts, in this case @code{c''}.
+@end ignore
+If you do not
+use octavation quotes (i.e., do not add @code{'} or @code{,} after a
+note), relative mode chooses the note that is closest to the previous
+one. For example, @samp{c f} goes up while @samp{c g} goes down
+
+@lilypond[quote,notime,fragment,verbatim]
+\relative {
+ c' f c g c
+}
@end lilypond
-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 for a triplet, the fraction is 2/3.
-@c
-@lilypond[relative 0,verbatim,fragment]
- \times 2/3 { f8 g a }
- \times 2/3 { c r c }
-@end lilypond
+Since most music has small intervals, pieces can be written almost
+without octavation quotes in relative mode. The previous example is
+entered as
+@lilypond[quote,raggedright,fragment,verbatim]
+\relative {
+ \key a \major
+ \time 6/8
+ cis''8. 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.
+Larger intervals are made by adding octavation quotes.
-Comments are pieces of the input that are ignored. There are two
-types of comments. A line comments are 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.
+@lilypond[quote,notime,verbatim,fragment]
+\relative c {
+ c'' f, f c' c g' c,
+}
+@end lilypond
-@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.
+In summary, quotes or commas no longer determine the absolute height
+of a note in @code{\relative} mode. Rather, the height of a note is
+relative to the previous one, and changing the octave of a single note
+shifts all following notes an octave up or down.
- g g f f e e d d c2
- %@}
-@end example
+For more information on Relative octaves see @ref{Relative octaves},
+and @ref{Octave check}.
+@node Music expressions explained
+@section Music expressions explained
+In input files, music is represent by so-called @emph{music
+expression}. We have already seen in the previous examples;
+a single note is a music expression
-@node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
+@lilypond[fragment,quote,verbatim,relative=3]
+a4
+@end lilypond
-Lyrics are entered by separating each syllable with a space, and
-surrounding them with @code{\lyrics @{ @dots{} @}}, for example
-@example
- \lyrics @{ I want to break free @}
-@end example
+Enclosing group of notes in braces creates a new music
+expression
-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
- \context Lyrics \lyrics @{ I want to break free @}
-@end example
-The melody for this song is as follows
-@lilypond[fragment,relative=1]
- \partial 8
- c8
- \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
+@lilypond[fragment,quote,verbatim,relative=3]
+{ a4 g4 }
@end lilypond
-The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword:
-@example
- \addlyrics
- \notes @{ @dots{} @}
- \context Lyrics @dots{}
-@end example
+Putting a bunch of music expressions (notes) in braces, means that
+they should be played in sequence. The result again is a music
+expression, which can be grouped with other expressions sequentially.
+Here, the expression from the previous example is combined with two
+notes
-The final result is
-@lilypond[singleline,verbatim]
-\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{ }
-}
+@lilypond[fragment,quote,verbatim,relative=3]
+{ { a4 g } f g }
@end lilypond
-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
- \lyrics @{ I want to break free __ @}
-@end example
-@lilypond[singleline]
-\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{ }
-}
+This technique is useful for non-monophonic music. To enter music
+with more voices or more staves, we also combine expressions in
+parallel. Two voices that should play at the same time, are entered
+as a simultaneous combination of two sequences. A `simultaneous'
+music expression is formed by enclosing expressions in @code{<<} and
+@code{>>}. In the following example, three sequences (all containing
+two notes) are combined simultaneously
+
+@lilypond[fragment,quote,verbatim,relative=3]
+<<
+ { a4 g }
+ { f e }
+ { d b }
+>>
@end lilypond
-Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables.
+This mechanism is similar to mathematical
+formulas: a big formula is created by composing small formulas. Such
+formulas are called expressions, and their definition is recursive, so
+you can make arbitrarily complex and large expressions. For example,
+
@example
- 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
- }}
-@end lilypond
+1
-More options, like putting multiple lines of lyrics below a melody are
-discussed in @ref{Vocal music}.
+1 + 2
+(1 + 2) * 3
-@node A lead sheet
-@section A lead sheet
+((1 + 2) * 3) / (4 * 5)
+@end example
-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}).
+@cindex expression
+@cindex music expression
+This example shows a sequence of expressions, where each expression is
+contained in the next one. The simplest expressions are numbers and
+operators (like @samp{+}, @samp{*} and @samp{/}). Parentheses are used
+to group expressions.
-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
-The result of @code{\chords} is a list of chords, and is equivalent
-to entering chords with @code{<<@dots{}>>}.
+Like mathematical expressions, music expressions can be nested
+arbitrarily deep@footnote{The reason for getting three staves in the
+previous example but just a single staff in the current one will be
+explained later.}
-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 }
+@lilypond[fragment,quote,verbatim,relative=2]
+{
+ c <<c e>>
+ << { e f } { c <<b d>> } >>
+}
@end lilypond
-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
-A complete list of modifiers, and other options for layout are in the
-reference manual section @ref{Chords}.
+@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 number of closing
+braces at the end of an expression. For example,
+
+@example
+\book @{
+ \score @{
+ <<
+ @{
+ @dots{}
+ @}
+ @{
+ @dots{}
+ @}
+ \paper @{
+ @dots{}
+ @}
+ >>
+ @}
+@}
+@end example
-
-TODO: template example with chord names, lyrics and staff.
+Some editors have special support for entering LilyPond, and can help
+indenting source files. See @ref{Editor support}, for more information.
+@node More staves
+@section More staves
-@node Listening to output
-@section Listening to output
-
-@example
+To print more than one staff, each piece of music that makes up a
+staff is marked by adding @code{\new Staff} before it. These
+@code{Staff} elements are then combined parallel with @code{<<} and
+@code{>>}, as demonstrated here
- \midi @{ \tempo 4=72@}
-
-@end example
-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.
+@lilypond[quote,fragment,verbatim]
+<<
+ \new Staff { \clef violin c'' }
+ \new Staff { \clef bass c }
+>>
+@end lilypond
-@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.
+The command @code{\new} introduces a `notation context.' A notation
+context is an environment in which musical events (like notes or
+@code{\clef} commands) are interpreted. For simple pieces, such
+notation contexts are created implicitly. For more complex pieces, it
+is best to mark contexts explicitly. This ensures that each fragment
+gets its own stave.
+There are several types of contexts: @code{Staff}, @code{Voice} and
+@code{Score} handle normal music notation. Other contexts are also
+@code{Lyrics} (for setting lyric texts) and @code{ChordNames} (for
+printing chord names).
-@node More movements
-@section More movements
+In terms of syntax, prepending @code{\new} to a music expression
+creates a bigger music expression. In this way it resembles the minus
+sign in mathematics. The formula @math{(4+5)} is an expression, so
+@math{-(4+5)} is a bigger expression.
-The program @code{lilypond} only produces sheet music. Titles,
-subtitles, and the composer's name are created by a separate program,
-called use @code{ly2dvi}. @code{ly2dvi} creates the titles, then
-calls @code{lilypond} to format the sheet music. In this section, we
-show you how to create titles like this:
+We can now typeset a melody with two staves
-@center @strong{Two miniatures}
-@flushright
-F. Bar Baz
+@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
-Opus 1.
-@end flushright
-@flushleft
-@var{Up}
-@end flushleft
-@lilypond
- \score {
- \notes { c'4 d'4 }
- \paper { raggedright = ##t }
+@lilypond[fragment,quote,verbatim,raggedright]
+<<
+ \new Staff {
+ \time 3/4
+ \clef violin
+ \relative {
+ e''2 d4 c2 b4 a8[ a]
+ b[ b] g[ g] a2. }
}
-@end lilypond
-@flushright
-Opus 2.
-@end flushright
-@flushleft
-@var{Down}
-@end flushleft
-@lilypond
- \score {
- \notes { d'4 c'4 }
- \paper { linewidth = -1.0 }
+ \new Staff {
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2.
}
+>>
@end lilypond
-For example, consider the following file (@file{miniatures.ly})
+For more information on context see the description in
+@ref{Interpretation contexts}.
-@example
-\header @{
- title = "Two miniatures"
- composer = "F. Bar Baz"
- tagline = "small is beautiful" @}
-\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
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
-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 @code{ly2dvi}, which 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
+@cindex articulation
+@cindex accents
+@cindex staccato
-When you process a file with ly2dvi, a signature line is printed at
-the bottom of the last page. Many people find the default (``Lily was
-here'' with a version number) too droll. If that is the case, you can
-change @code{tagline} in the @code{\header}, as shown above.
+Common accents can be added to a note using a dash (@samp{-}) and a
+single character
-@cindex Lily was here
-@cindex signature line
-@cindex tag line
+@lilypond[fragment,quote,verbatim,relative=2]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(@samp{-}) and the digit to be printed
-@separate
-@example
- \header @{
-@end example
+@lilypond[fragment,quote,verbatim,relative=2]
+c-3 e-5 b-2 a-1
+@end lilypond
-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 are making an exercise book), you can put different
-@code{\score} blocks into the input file. @code{ly2dvi} will assemble
-all LilyPond output files into a one document. The contents of
-@code{\header} blocks specified within each score is used for the
-title of that 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.
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
+@lilypond[fragment,quote,verbatim,relative=2]
+c\ff c\mf
+@end lilypond
-@node Organising larger pieces
-@section Organising larger pieces
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
-TODO: discuss identifiers, p&c, .
+Crescendi and decrescendi are started with the commands @code{\<} and
+@code{\>}. An ending dynamic, for example @code{\f}, will finish the
+crescendo, or the command @code{\!} can be used
-@separate
-@example
-\version "1.5.72"
-@end example
-Lilypond and its language are still under development, and
-occasionally details of the syntax are changed. The @code{version}
-fragment indicates which LilyPond version the input file was written
-for. 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{Invoking convert-ly}), which can used to update the file to the
-latest lily version.
+@lilypond[fragment,quote,verbatim,relative=2]
+c2\< c2\ff\> c2 c2\!
+@end lilypond
-@node A piano excerpt
-@section A piano excerpt
-Our eighth 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, composed around 1740. It's in the source
-package under the name @inputfileref{input/tutorial,sammartini.ly}.
+@cindex slur
-@lilypondfile[smallverbatim]{sammartini.ly}
+A slur is a curve drawn across many notes, and indicates legato
+articulation. The starting note and ending note are marked with
+@samp{(} and @samp{)}, respectively
-As you can see, this example features multiple voices on one staff. To
-make room for those voices, their notes should be stemmed in opposite
-directions.
+@lilypond[fragment,quote,fragment,relative=2,verbatim]
+d4( c16)( cis d e c cis d e)( d4)
+@end lilypond
+@cindex slurs versus ties
+A slur looks like a tie, but it has a different meaning. 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[quote,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
+@end lilypond
-@separate
-@example
-viola = \notes \relative c' \context Voice = viola @{
-@end example
-In this example you see multiple parts on a staff. Each part is
-associated with one notation context. This notation context handles
-stems and dynamics (among other things). 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}').
+@cindex phrasing slurs
+Slurs to indicate phrasing can be entered with @code{\(} and
+@code{\)}, so you can have both legato slurs and phrasing slurs at the
+same time.
-@separate
+@lilypond[quote,fragment,relative=2,verbatim]
+a8(\( ais b c) cis2 b'2 a4 cis, c\)
+@end lilypond
-@cindex arpeggio
+For more information on
+@quotation
+@table @asis
+@item Fingering
+see @ref{Fingering instructions}.
+@item Articulations
+see @ref{Articulations}.
+@item Slurs
+see @ref{Slurs}.
+@item Phrasing slurs
+see @ref{Phrasing slurs}.
+@item Dynamics
+see @ref{Dynamics}.
+@end table
+@end quotation
+@node Combining notes into chords
+@section Combining notes into chords
-@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).
+@cindex chords
+Chords can be made by surrounding pitches with angle brackets.
+Angle brackets are the symbols @samp{<} and @samp{>}.
-@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 do not play. In this case, the viola does not come until one
-and a half measure later.
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>4 <c f a>8
+@end lilypond
-@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
- s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16
-@end example
-The oboes should have stems up to keep them from interfering with
-the staff-jumping bass figure. To do that, we use @code{\voiceOne}.
+You can combine markings like beams and ties with chords. They must
+be placed outside the angled brackets
-@separate
-@example
-\grace <<e g>>-( <<d f>>4-) <<c e>>2
-@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.
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>8[ <c f a>]~ <c f a>
+@end lilypond
-@separate
-@example
-\times 2/3
+@example
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
@end example
-@cindex tuplet
-@cindex triplets
-
-@separate
-@example
-@{ <<d f>>8 <<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 cannot 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
+@lilypond[quote,relative=1,fragment]
+\slurUp
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+@end lilypond
-@separate
-@example
-\\
-@end example
-Entering 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
-\grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
-@end example
-@cindex trill
-@cindex stemBoth
-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
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-@cindex @code{\translator}
+@node Basic rhythmical commands
+@section Basic rhythmical commands
-@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 the stem directions explicitly
-(using the identifiers @code{\stemUp} and @code{\stemDown}, the notes
-can be beamed together (despite jumping between staffs).
+@cindex pickup
+@cindex anacruse
+@cindex partial measure
+A pickup 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
-@separate
-@example
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\autochange Staff \hoomPah \context Voice
-@end example
+@lilypond[quote,relative=2,verbatim,fragment]
+\partial 8
+f8 c2 d e
+@end lilypond
-@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.
+@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
+@lilypond[quote,relative=1,verbatim,fragment]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+@end lilypond
+@cindex grace notes
+@cindex accacciatura
+Grace notes are also made by prefixing a music expression with the
+keyword @code{\appoggiatura} or @code{\acciaccatura}
+@cindex appoggiatura
+@cindex acciaccatura
+
+@lilypond[quote,relative=2,verbatim,fragment]
+c4 \appoggiatura b16 c4
+c4 \acciaccatura b16 c4
+@end lilypond
+@noindent
-@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.
+For more information on
+@quotation
+@table @asis
+@item Grace notes
+see @ref{Grace notes},
+@item Tuplets
+see @ref{Tuplets},
+@item Pickups
+see @ref{Partial measures}.
+@end table
+@end quotation
-@ignore
-[TODO:
-* font-size
+@node Commenting input files
+@section Commenting input files
-* Simple part combining in a Hymn
-@end ignore
+@cindex comments
+@cindex line comment
+@cindex block comment
+A comment is a remark for the human reader of the music input; it is
+ignored and has no effect on the printed output. There are two types
+of comments. The percent symbol @samp{%} introduces a line comment;
+the rest of the line is ignored. A block comments marks a whole
+section of music input---anything that is enclosed in @code{%@{} and
+@code{%@}} is ignored. The following fragment shows possible uses for
+comments
+@example
+% notes for twinkle twinkle follow
+c4 c g' g a a
-@node Fine tuning a piece
-@section Fine tuning a piece
+%@{
+ This line, and the notes below
+ are ignored, since they are in a
+ block comment.
-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 versions) are in @file{input/tutorial/}.
+ g g f f e e d d c2
+%@}
+@end example
-The code for the untuned example shows us some new things.
+There is a special statement that really is a kind of comment. The
+version statement marks for which version of LilyPond the file was
+written. To mark a file for version 2.1.17, use
-@lilypondfile[verbatim]{brahms-original.ly}
+@example
+\version "2.1.17"
+@end example
+@noindent
+These annotations make future upgrades of LilyPond go more
+smoothly. Changes in the syntax are handled with a special program,
+@file{convert-ly} (see @ref{Invoking convert-ly}), and it uses
+@code{\version} to determine what rules to apply.
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex crescendo
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
+@c TODO: (c) status of the Queen fragment.
+@cindex Lyrics
+@cindex Songs
+Lyrics are entered by separating each syllable with a space
-Now that we have the basic piece of music entered, we want to fine
-tune it so that we get something that resembles the original printed
-edition by Schott/Universal Edition:
+@example
+I want to break free
+@end example
-@lilypondfile{brahms-tweaked.ly}
+Consider the melody
-@cindex tuning graphical objects
+@lilypond[quote,verbatim,fragment,raggedright]
+\relative {
+ r4 c \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+}
+@end lilypond
-Fine tuning involves overriding the defaults of the printing system.
-We do this by setting variables which control how Lilypond prints
-symbols. Printed symbols are called graphical objects (often
-abbreviated to @emph{grob}). Each object is described by a bunch of
-settings. Every setting is a variable: it has a name and a value
-which you can change. These values determine the fonts, offsets,
-sub-routines to be called on the object, etc. The initial values of
-these settings are set in the Scheme file
-@file{scm/grob-description.scm}.
+@c FIXME: when/how/to what rename newlyrics?
+The lyrics can be set to these notes, combining both with the
+@code{\newlyrics} keyword
-@cindex slur attachments
+@lilypond[quote,verbatim,fragment,raggedright]
+<<
+ \relative {
+ r4 c \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+ }
+ \newlyrics { I want to break free }
+>>
+@end lilypond
-We start with the slur in the upper part, running from F sharp to A. In
-the printed edition, this slur runs from stem to stem; in our version,
-the slur begins at the note head of the F sharp. The following property
-setting forces all slurs to run from stem to stem (not from or to note
-heads!).
+@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 an @emph{extender
+line}. It is entered as two underscores, i.e.,
@example
- \property Voice.Slur \set #'attachment = #'(stem . stem)
-@end example
+@{ I want to break free __ @}
+@end example
-More precisely, this command modifies 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)}.
-
-@cindex internal documentation
-@cindex finding graphical objects
-@cindex graphical object descriptions
-
-This command fixes one particular problem with a slur. The rest of
-this section explains how to 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 installed a binary distribution. [TODO: revise for
-new site.] These HTML pages are also available on the web: go to the
-LilyPond website, click ``Documentation: Index'' on the side bar, look
-in the ``Information for uses'' section, and click on ``Documentation
-of internals''.
-
-You might want to bookmark either the HTML files on your disk, or the
-one on the web (the HTML on your hard drive will load much faster than
-the ones on the web!). One word of caution: the internals
-documentation is generated from the definitions that the program uses.
-Hence, the internals documentation is strongly tied to the version you
-use. Before you proceed, make sure that the program and documentation
-have matching version numbers.
-
-@c TODO: the quote is incorrect, although that shouldn't be a big
-@c problem for the reader.
-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
+@lilypond[fragment,quote,raggedright]
+<<
+ \relative {
+ r4 c \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+ }
+ \newlyrics { I want to break free __ }
+>>
+@end lilypond
-So the graphical object 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 should 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
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables
-@c this is a long section, and adding an extra space here helps to
-@c break it into smaller subsections and thus is easier to understand.
-@separate
-
-Next we want to move the fingering `3'. In the printed edition it is
-not above the stem, but a little lower and slightly left of the stem.
-From the user manual we find that the associated graphical object 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
+Twin -- kle twin -- kle
@end example
-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} object. 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{}
-@end example
+@lilypond[fragment,quote,raggedright]
+<<
+ \relative {
+ \time 2/4
+ f4 f c' c
+ }
+ \newlyrics { Twin -- kle twin -- kle }
+>>
+@end lilypond
-Since the @code{TabVoice} is only used for tab notation, we see that
-the first guess @code{Voice} was indeed correct.
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
-@cindex setting object properties
-@cindex @code{extra-offset}
+@c FIXME: too geeky, for notation manual?
+@c or introduce using foo = \lyrics { a b c } ?
+
+When using variables for a piece of lyrics
+To prevent certain words (for example `as') as being read as a
+pitch, the input-mode must be switched. This is done with
+@code{\lyrics}. In @code{\lyrics} mode, all words are read as lyric
+syllables.
-For shifting the fingering, we use the 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
- \once \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. 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.
-We only want to offset a single object, so this statement is adorned
-with @code{\once}.
-
-@cindex property types
-@cindex translator properties
-@cindex grob properties
-@cindex music properties
-@separate
-
-There are three different types of variables in LilyPond, something
-which can be confusing at first (and for some people it stays
-confusing). Variables such as @code{extra-offset} and
-@code{attachment} are called grob properties. They are not the same
-as translator properties, like @code{autoBeaming}. Finally, music
-expressions are internally stored using properties (so-called music
-properties). You will encounter music properties 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:
@example
- a-)^" "^\markup @{ \finger "5" @}
+myText = \lyrics @{ I want to break free @}
@end example
-A fingering instruction, which would be entered as @code{^5}, is put
-as close to the notes as possible, closer than the space entered to
-push away the 5. Hence, the 5 is entered as a normal text, with the
-formatting of fingering instructions.
-
-@separate
-
-Normally one would specify all dynamics in the same voice, so that
-dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
-in this case, we do not want the decrescendo to be aligned with 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 using the precooked command
+@noindent
+The braces @code{@{@}} signify that the syllables are sung in
+sequence.
+
+@ignore
+By default, music expressions are interpreted in @code{Staff} context. For
+lyrics, this is obviously not desirable, so it is necessary
+to explicitly specify a @code{Lyrics} context,
+
@example
- \dynamicsUp
+\lyrics @{ I want to break free @}
@end example
-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
-@code{DynamicLineSpanner} supports several so-called `interfaces'.
-This object not only puts 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 an spanning object
-(@code{spanner-interface}). It also has the standard
-@code{grob-interface} with all the variables that come with it.
-
-For the moment we are interested in side positioning:
-@quotation
- side-position-interface
+The melody for this song is as follows
+
+@lilypond[fragment,quote,fragment,relative=2]
+r4 c \times 2/3 { f4 g g }
+\times 2/3 { g4( a2) }
+@end lilypond
+
+@end ignore
+
+
+@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.
+Such chords can be entered like notes,
- 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 object and its support (in this case, the descending
-notes), there should be more space. This space is controlled by
-@code{padding}, so we increase it.
@example
- \property Voice.DynamicLineSpanner \override #'padding = #5.0
+c2 f4. g8
@end example
+@noindent
+but now, each pitch is read as the root of a chord instead of a note.
+This mode is switched on with @code{\chords}
+
+@lilypond[quote,verbatim,raggedright]
+\chords { c2 f4. g8 }
+@end lilypond
-(TODO: huh? what's this: )
+Other chords can be created by adding modifiers after a colon. The
+following example shows a few common modifiers
-This command resembles the one for setting slur attachments, but
-subtly differs in its details. Grob properties can be manipulated
-with two commands: @code{\override} extends the definition of a grob
-with one setting, and @code{\revert} releases this setting. This has
-a theoretical appeal: the operations are simple and symmetric. For
-practical use, it can be cumbersome. The 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}.
+@lilypond[quote,verbatim]
+\chords { c2 f4:m g4:maj7 gis1:dim7 }
+@end lilypond
-@separate
+For lead sheets, chords are not printed on staves, but as names on a
+line of themselves. Hence, we have to override the context with
+@code{\new}, rendering the music expression in a @code{ChordNames}
+context
-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.
+@lilypond[quote,verbatim]
+\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+@end lilypond
+
+@cindex lead sheet
+When put together, chord names, lyrics and a melody form
+a lead sheet, for example,
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
@example
-\property Voice.Stem \set #'transparent = ##t
-d'
+<<
+ \new ChordNames \chords @{ @emph{chords} @}
+ @emph{the melody}
+ \newlyrics @{ @emph{the text} @}
+>>
+@}
@end example
-Blanking the stem should be done for only one object. One of the ways
-to achieve that, is by setting the property before a note. Reverting
-it afterwards is tedious, so for setting a property only once, we have
-the syntax @code{\once}: it reverts the property directly before
-proceeding to the next step in time.
-The @code{\once} keyword is added to @code{\property}.
+@lilypond[quote,raggedright]
+<<
+ \new ChordNames \chords { r2 c:sus4 f }
+ \notes \relative {
+ r4 c' \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+ }
+ \newlyrics { I want to break free __ }
+>>
+@end lilypond
+A complete list of modifiers and other options for layout can be found
+in @ref{Chords}.
-Finally, the last tie is forced up using @code{\tieUp}.
+@c FIXME: we talk about \midi before mentioning \paper (or \layout?)
+@node Listening to output
+@section Listening to output
-@separate
+@cindex sound
+@cindex MIDI
-Here is the complete ``fine tuned'' version, which includes all the
-modifications we discussed in this section:
+MIDI (Musical Instrument Digital Interface) is a standard for
+connecting and controlling digital instruments. A MIDI file is like a
+tape recording of a MIDI instrument.
-@lilypondfile[verbatim]{brahms-tweaked.ly}
+To create a MIDI from a music piece of music, add a @code{\midi}
+block. This causes LilyPond to create a MIDI file, so you can listen
+to what you just 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.
+The @code{\midi} block is added to @code{\score}, for example,
-@node An orchestral score
-@section An orchestral score
+@example
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+@}
+@end example
-@menu
-* The full score::
-* Extracting an individual part::
-@end menu
+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 in the notation manual can be found in
+@ref{Sound}.
+If there is a @code{\midi} command in a @code{\score}, only MIDI will
+be produced. If notation is needed too, a @code{\paper} block must be
+added
-Our next two examples demonstrate one way to create an orchestral score
-in LilyPond. When typesetting a piece for several instruments, you'll
-want to create a full score (for the conductor) along with several
-individual parts (for the players).
+@example
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+ \paper @{ @}
+@}
+@end example
+@cindex paper block
- 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 instruments (for example, one @code{\score} block may
-only include the cello part; another @code{\score} block may be for
-all the strings, and yet another @code{\score} block may be for all
-parts together).
-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 for producing the score and the
-separate parts, but the file does not produce any sheet music itself.
-Other files reference it by stating @code{\include "os-music.ly"}.
+@node Adding titles
+@section Adding titles
-@example
-% os-music.ly
+Bibliographic information is entered in a separate block, the
+@code{\header} block. The name of the piece, its composer, etc., are
+entered as an assignment, within @code{\header
+@{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at
+the top of the file. For example,
+
+@example
\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
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
@}
+
+@{ @dots{} @}
@end example
-We will not examine this example line by line, since you already know
-most of it. We'll examine a few lines which contain new elements.
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Engraved by LilyPond
+When the file is processed the title and composer are printed above
+the music. The `tagline' is a short line printed at bottom of the last
+page which normally says `Engraved by LilyPond, version @dots{}'. In
+the example above it is replaced by the line `small is
+beautiful.'@footnote{Nicely printed parts are good PR for us, so
+please leave the tagline if you can.}
-@separate
-@example
-global = @{
- \time 2/4
- \skip 2*4 \bar "|."
-@}
-@end example
-This declares settings 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.
-You can use @code{s} as a shortcut for @code{\skip} (the last line of
-this section would be @code{s2*4 \bar"|."}).
+The @code{\header} block is usually put at the top of the file.
-@separate
-@example
-Key = \notes \key as \major
-@end example
-This declares the key signature of the piece and assign it to the
-identifier @var{Key}. Later on we will use @code{\Key} for all staves
-except those for transposing instruments.
+A document may contains multiple pieces of music, examples are an
+etude book, or an orchestral part with multiple movements.
+@c FIXME: ugh. \header can only live at toplevel, or inside \score.
+@c If we allow it also to live inside \book, we do not need \score here?
+The @code{\book} block is used to group the individual @code{\score}
+blocks.
-@node The full score
-@subsection The full score
+The header for each piece of music can be put inside the @code{\score}
+block. The @code{piece} name from the header will be printed before
+each movement.
+@ignore
-The second file, @inputfileref{input/tutorial,os-score.ly}, reads the
-definitions of the first (@inputfileref{input/tutorial,os-music.ly}), and
-defines the @code{\score} block for the full conductor's score.
+FIXME: introduce \BOOK
-@example
-\version "1.7.6"
+FIXME: Using "Adagio" as a name is confusing, it's more common to be
+a plain tempo indication.
-\include "os-music.ly"
-\include "paper13.ly"
+Since today (CVS-1.211) we also allow headers and composite music
+inside book:
-textFlat = \markup @{\smaller \musicglyph #"accidentals--1"@}
-\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 = \markup @{ \column << "Timpani" "(C-G)" >> @}
- \property Staff.instr = #"Timp."
- \clef bass
- \Key
- \timpani
- >
- >
- \context StaffGroup = brass <
- \context Staff = trombe <
- \property Staff.midiInstrument = #"trumpet"
- \property Staff.instrument = \markup @{ \column << "2 Trombe" "(C)" >> @}
- \property Staff.instr = \markup@{ \column << "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
- = \markup @{ \column << "Corno" @{ "(E" \textFlat ")" @} >> @}
- \property Staff.instr =
- \markup @{ \column << "Cor." @{ "(E" \textFlat ")" @} >> @}
- \property Staff.transposing = #3
- \notes \key bes \major
- \context Voice=one \corno
- >
- >
- >
- \paper @{
- indent = 15 * \staffspace
- linewidth = 60 * \staffspace
- textheight = 90 * \staffspace
- \translator@{
- \VoiceContext
- \consists "Multi_measure_rest_engraver"
- @}
- \translator@{
- \HaraKiriStaffContext
- \remove "Multi_measure_rest_engraver"
- @}
+ \header { ... }
+ \book {
+ \header { ... }
+ { ... }
+ \header { ... }
+ { ... }
+ }
+
+@end ignore
+
+@cindex Engraved by LilyPond
+@cindex signature line
+@cindex tag line
+
+@example
+\header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+@}
+
+\book @{
+ \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 lilypond}.
-@lilypondfile{os-score.ly}
-@separate
-@example
-\include "os-music.ly"
-@end example
-First we need to include the music definitions we made in
-@file{os-music.ly}.
+@node Single staff polyphony
+@section Single staff polyphony
-@ignore
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
+When different melodic lines are combined on a single staff they 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
+them down.
-[TODO: mention in a more relevant place]
-
-@separate
-@example
-#(ly:set-point-and-click 'line-column)
-@end example
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{...@}}), and combining those simultaneously, separating the
+voices with @code{\\}
-This piece of Scheme code executes the function
-@code{ly:set-point-and-click} with the argument
-@code{line-column}. Editing input files can be complicated if you are
-working with large files: if you are 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}.
-@end ignore
+@lilypond[quote,verbatim,relative=3]
+<< { a4 g2 f4~ f4 } \\
+ { r4 g4 f2 f4 } >>
+@end lilypond
+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. Here is the same example with a spacer rest
+instead of a normal rest---just use @samp{s} instead of @samp{r}
-@separate
-@example
-#(define text-flat '((font-relative-size . -2)
- (music "accidentals--1")))
-@end example
+@lilypond[quote,verbatim,relative=3]
+<< { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 } >>
+@end lilypond
-To name the transposition of the french horn, we will 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}.
+@noindent
+Again, these expressions can be nested arbitrarily
+
+@lilypond[quote,fragment,verbatim,relative=3]
+<<
+ \new Staff <<
+ { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 }
+ >>
+ \new Staff <<
+ \clef bass
+ { <c, g>1 ~ <c g>4 } \\
+ { f4 d e2 ~ e4}
+ >>
+>>
+@end lilypond
-@separate
-@example
- <
- \global
-@end example
-All staves are simultaneous and use the same global settings.
+More features of polyphonic typesetting in the notation manual are
+described in @ref{Polyphony}.
-@separate
-@example
- \property Score.BarNumber \override #'padding = #3
-@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. In LilyPond, a bar number is called @var{BarNumber}.
-BarNumber objects can be manipulated through their
-@var{side-position-interface}. One of the properties of a
-@var{side-position-interface} that can be tweaked is @var{padding}:
-the amount of extra space that is put between this and other objects.
-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}
-or in @ref{Fine tuning a piece}.
-@end ifnottex
-@iftex
-the online documentation or in the previous section of the tutorial.
-@end iftex
-
-@c REFERENCE MAO
-
-@separate
-@example
- \context StaffGroup = woodwind <
- \context Staff = flauti <
-@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. This starts 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, who also play simultaneously.
-@separate
-@example
- \property Staff.midiInstrument = #"flute"
-@end example
-Specify the instrument for MIDI output (see @ref{MIDI instrument
-names}).
+@node Piano staves
+@section Piano staves
-@separate
-@example
- \property Staff.instrument = "2 Flauti"
- \property Staff.instr = "Fl."
-@end example
-This defines the instrument names to be printed in the
-margin. @code{instrument} specifies the name for the first line
-of the score, @code{instr} is used for the rest of the score.
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+@cindex @code{\context}
+Piano music is typeset in two staves connected by a brace. Printing
+such a staff is similar to the polyphonic example in @ref{More staves},
-@separate
@example
- \Key
+<< \new Staff @{ @dots{} @}
+ \new Staff @{ @dots{} @} >>
@end example
-The flutes play in the default key.
-@separate
+@noindent
+but now this entire expression must be interpreted as a
+@code{PianoStaff}
+
@example
- \context Voice=one @{ \voiceOne \flautoI @}
- \context Voice=two @{ \voiceTwo \flautoII @}
+\new PianoStaff << \new Staff @dots{} >>
@end example
-Last come the actual flute parts. Remember that we are still in
-simultaneous mode. We name both voices differently, so that LilyPond
-will 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.
-
-@separate
+
+Here is a full-fledged example
+
+@lilypond[quote,verbatim,relative=1,fragment]
+\new PianoStaff <<
+ \new Staff { \time 2/4 c4 c g' g }
+ \new Staff { \clef bass c,, c' e c }
+>>
+@end lilypond
+
+More information on formatting piano music is in @ref{Piano music}.
+
+
+@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 pieces,
+more deeply nested. Such large expressions can become unwieldy.
+
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions. An identifier is assigned as follows
+
@example
- >
- >
+namedMusic = \notes @{ @dots{} @}
@end example
-Close the flutes staff and woodwind staff group.
-@separate
+@noindent
+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 two times by using
+variable substitution
+
+@lilypond[quote,raggedright,verbatim,nofragment]
+seufzer = \notes {
+ e'4( dis'4)
+}
+{ \seufzer \seufzer }
+@end lilypond
+
+The name of an identifier should have alphabetic characters only;
+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
- \property Staff.instrument = #'(lines "Timpani" "(C-G)")
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example
-The timpani staff demonstrates a new piece of scheme markup, it sets two
-lines of text.
-@separate
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables
+
@example
- \context Voice=one \partcombine Voice
- \context Thread=one \tromboI
- \context Thread=two \tromboII
+\score @{
+ \notes @{ c4^\name @}
+ \paper @{
+ \aFivePaper
+ linewidth = \width
+ @}
+@}
@end example
-You have seen the notation contexts Staff and Voice, but here is a new
-one: Thread. One or more Threads can be part of a Voice. Thread
-takes care of note heads and rests; 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 are similar, and splits the threads up
-when they are different.
-
-@separate
+
+More information on the possible uses of identifiers is in the
+technical manual, in TODO.
+
+
+@node An orchestral part
+@section An orchestral part
+
+In orchestral music, all notes are printed twice; 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
+a 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 @file{horn-music.ly} contains the following part
+of a horn/bassoon duo
+
@example
-\property Staff.instrument = #`(lines "Corno"
- (columns "(E" ,text-flat ")"))
+hornNotes = \notes \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
@end example
-The french horn (``Corno'') 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 previously,
-and a final @code{")"}. 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
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
@example
- \property Staff.transposing = #3
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
+\score @{
+ \notes \transpose f c' \hornNotes
+@}
@end example
-The french horn is to be tuned in E-flat, so we tell the MIDI back-end to
-transpose this staff by three steps.
-Note how we can choose different tunings for the text input, sheet music
-output and, and MIDI output, using @code{\transpose} and the MIDI Staff
-property @var{transposing}.
+The line
-@separate
@example
- \notes \key bes \major
+\include "horn-music.ly"
@end example
-Since the horn is transposing, it is in a different key.
-@separate
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
+@samp{f} is denoted by notated @code{c'}, which corresponds with
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,raggedright]
+\score {
+ \notes \transpose f c' \notes \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+ }
+}
+@end lilypond
+
+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 @samp{R} followed by a duration
+(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
@example
- indent = 15 * \staffspace
- linewidth = 55 * \staffspace
+R2*3
@end example
-We specify a big indent for the first line and a small linewidth for this
-tutorial.
-
-@separate
-Usually the default setup of notation contexts (Thread, Voice, Staff,
-Staffgroup, Score) is just fine. But in this case we want a different
-type of Staff context.
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
@example
- \translator@{
- \HaraKiriStaffContext
- @}
+\set Score.skipBars = ##t
@end example
-In orchestral scores it often happens that one instrument only has
-rests during one line of the score. @code{HaraKiriStaffContext} can
-be used as a regular @code{StaffContext} drop-in and will take care of
-the automatic removing of empty staves -- so if the strings are the
-only instruments playing for a line, LilyPond will only print the string
-parts for that line of the score. This reduces the number of page turns
-(and the number of dead trees!) required in a score.
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
+
+@lilypond[quote,raggedright]
+\score {
+ \notes \transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+ }
+}
+@end lilypond
-@node Extracting an individual part
-@subsection Extracting an individual 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.
+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}, a score is made with
@example
-\include "os-music.ly"
-\include "paper16.ly"
+\include "bassoon-music.ly"
+\include "horn-music.ly"
\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
+ \simultaneous @{
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
@}
@}
@end example
-@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 is the part for the second flute player. Of
-course, we would make separate parts for all individual instruments if
-we were preparing the score for an orchestra.
-
-@separate
-@example
- \flautoII
-@end example
-In this individual part the second flute has a whole staff for itself,
-so we do not want to force stem or tie directions.
+@noindent
+leading to
-@separate
-@example
- \header @{
- instrument = "Flauto II"
- @}
-@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.
+@lilypond[quote,raggedright]
+\score {
+ \notes \relative c \simultaneous {
+ \new Staff {
+ \time 2/4 R2*3
+ r4 f8 a cis4 f e d
+ }
+ \new Staff {
+ \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f
+ }
+ }
+}
+@end lilypond
-@separate
-@example
- \property Score.skipBars = ##t
-@end example
-In the conductor's full score, all bars with rests are printed, but for
-the individual parts, we want to print one multimeasure rest instead of
-many consecutive empty bars. LilyPond will do this if
-@code{Score.skipBars} is set to true (@code{##t}).
+More in-depth information on preparing parts and scores can be found
+in the notation manual; see @ref{Orchestral music}.
+
+Setting run-time variables (`properties') is discussed in ref-TODO.
@node Integrating text and music
@section Integrating text and music
-
@cindex La@TeX{}, music in
@cindex HTML, music in
@cindex Texinfo, music in
+Some texts include music examples. Examples are musicological
+treatises, songbooks or manuals like this. Such texts can be made by
+hand, simply by importing a PostScript figure into the word processor.
+However, there is an automated procedure to reduce the amount of work
+involved HTML, La@TeX{}, and Texinfo documents.
-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 program is fully described in @ref{lilypond-book manual}. Here
-we show a small example. Since the example also contains explanatory
-text, we will not comment it further.
+A script called @code{lilypond-book} will extract the music fragments,
+run format them, and put back the resulting notation. This program is
+fully described in @ref{lilypond-book manual}. Here we show a small
+example. The example also contains explanatory text, so we will not
+comment on it further
@example
\documentclass[a4paper]@{article@}
\begin@{document@}
-In a lilypond-book document, you can freely mix music and text. For
-example:
+Documents for lilypond-book may freely mix music and text. For
+example,
+
\begin@{lilypond@}
\score @{ \notes \relative c' @{
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.
-
-If you have no \verb+\score+ block in the fragment,
-\texttt@{lilypond-book@} will supply one:
+If there is no \verb+\score+ block in the fragment,
+\texttt@{lilypond-book@} will supply one
-\begin@{lilypond@}
+\begin[quote]@{lilypond@}
c'4
\end@{lilypond@}
-In the example you see here, two things happened: a
+\noindent
+In this example 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:
-
-\begin[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]@{lilypond@}
- c'4 f bes es
-\end@{lilypond@}
+length.
-The option \texttt@{verbatim@} prints the LilyPond code in addition to
-the graphical score, \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.
+Options are put in brackets.
-If you want to include large examples into the text, it may be more
-convenient to put the example in a separate file:
+\begin[quote,staffsize=26,verbatim]@{lilypond@}
+ c'4 f16
+\end@{lilypond@}
-\lilypondfile[printfilename]@{sammartini.ly@}
+Larger examples can be put in a separate file, and introduced with
+\verb+\lilypondfile+.
-The \texttt@{printfilename@} option adds the file name to the output.
+\lilypondfile[quote,noindent]@{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.7.16
-Reading `input/tutorial/lilbook.tex'
-Reading `input/tutorial/sammartini.ly'
+$ lilypond-book --output=out/ lilybook.tex
+lilypond-book (GNU LilyPond) 2.1.19
+Reading `input/tutorial/lilybook.tex'
+Reading `input/screech-boink.ly'
@var{lots of stuff deleted}
-Writing `out/lilbook.latex'
+Writing `out/lilybook.tex'
$ cd out
-$ latex lilbook.latex
+$ latex lilybook
@var{lots of stuff deleted}
-$ xdvi lilbook
+$ xdvi lilybook
@end example
-Notice the @code{outdir} option to lilypond-book. Running lilypond-book
-and running latex creates a lot of temporary files, and you would not want
-those to clutter up your working directory. Hence, we have them created
-in a separate subdirectory.
+To convert the file into a nice PDF document, run the following
+commands
-The result looks more or less like this:
+@example
+$ dvips -Ppdf -u +lilypond lilybook
+$ ps2pdf lilybook.ps
+@end example
-@separate
+Running lilypond-book and running latex creates a lot of temporary
+files, which would clutter up the working directory. To remedy this,
+use the @code{--output=@var{dir}} option. It will create the files in
+a separate subdirectory @file{dir}.
-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
- }
- \paper {
- raggedright = ##t
- }
-}
-@end lilypond
+Finally the result of the La@TeX{} example shown above.@footnote{Note
+that in this tutorial the example is processed with Texinfo. This gives
+slightly different results in layout.} This finishes the tutorial
+section.
-Notice that the music line length matches the margin settings of the
-document.
+@page
-If you have no @code{\score} block in the fragment,
-@code{lilypond-book} will supply one:
+Documents for lilypond-book may freely mix music and text. For
+example,
@lilypond
- c'4
+\score { \notes \relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+} }
@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:
+If there is no @code{\score} block in the fragment,
+@code{lilypond-book} will supply one
-@lilypond[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]
- c'4 f bes es
+@lilypond[fragment,quote]
+c'4
@end lilypond
-The option @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.
+@noindent
+In this example two things happened. A
+@code{score} block was added, and the line width was set to natural
+length.
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
+Options are put in brackets.
-@lilypondfile[printfilename]{sammartini.ly}
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
-The @code{printfilename} option adds the file name to the output.
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.
-[TODO: include excercises? ]
+@lilypondfile[quote,noindent]{screech-boink.ly}