@c -*-texinfo-*-
+@c This file is part of lilypond.tely
-@c TODO: LilyPond LilyPond LilyPond
+@c TODO:
+@c * more details about running lilypond; error messages,
+@c compiling/viewing (emacs?)
+@c * where to go from First steps+More basics?
+@c Your first LilyPond score in 10 minutes?
@node Tutorial
@chapter Tutorial
-
-@menu
-* First steps:: Music language of LilyPond
-* Simple legend:: Small table of music language symbols
-* Running LilyPond:: Printing music
-* The first real tune:: The first real tune
-* Lyrics and chords:: Lyrics and chords
-* More movements :: Joining separate pieces of music
-* A piano excerpt:: Piano music
-* An orchestral score:: Conductor's score and individual parts
-* Other ways to run LilyPond:: Other ways to run LilyPond
-* Integrating text and music:: Integrating text and music
-* End of tutorial:: The end
-@end menu
+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.
-The music is described in a text file, using a simple music language.
-LilyPond reads that text file and generates music that you can print or
-view.
+@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
-Therefore, creating music notation with LilyPond is done in two steps.
-Using a text editor, you write down the notes to print. Then, you run
-LilyPond to get your printed output.
-
-This tutorial starts with a small introduction to the LilyPond music
-language. After this first contact, we will show you how to run
-LilyPond to produce printed output; you should then be able to create
-your first sheets of music.
+@lilypond[fragment,quote,raggedright,relative=2]
+c-\markup { \bold \huge { Click here. } }
+@end lilypond
+@end ifhtml
-The tutorial continues with a slightly more elaborate example of real music.
-This piece introduces and explains some finer details of LilyPond.
-Then, a number of more complex examples follow, that will help you to
-produce most complex music with LilyPond.
+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::
+* 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::
+* Adding titles::
+* Single staff polyphony::
+* Piano staves::
+* Organizing larger pieces::
+* An orchestral part::
+* Integrating text and music::
+@end menu
-@c title?
@node First steps
@section First steps
-@c @node Music language of LilyPond
-@c @section Music language of LilyPond
-
-This section shows how easy writing music with LilyPond actually is. If
-you have not seen LilyPond input source before, this section is for you.
-
-The next section has a table (see @ref{Simple legend}) of all symbols
-that are introduced here, you may want to keep an eye on that.
+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
-Writing music with LilyPond is explained below by a number of small
-examples. Each example has a small piece of text; the LilyPond input
-that you should type, with the resulting music printed below it.
-
-You get a simple note by typing its note name, from @code{a} through
-@code{g}:
-
-@quotation
@example
c d e f g a b
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\transpose c'' { c d e f g a b }
+@noindent
+the result looks like this
+
+@lilypond[fragment,quote,notime,relative=1]
+c d e f g a b
@end lilypond
-@end quotation
-@separate
-The length of a note is specified by adding a number, ``@code{1}'' for a
-whole note, ``@code{2}'' for a halve 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
-@quotation
@example
a1 a2 a4 a16 a32
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-%\property Staff.Clef = \turnOff
-\transpose 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
-@end quotation
-@separate
-If you don't specify a duration, the previous duration 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
-@quotation
@example
-a a a2 a
+a a8 a a2 a
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-%\property Staff.Clef = \turnOff
-\transpose c'' { a a a2 a }
-s16_" "
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a a8 a a2 a s16_" " }
@end lilypond
-@end quotation
-@separate
-A sharp (@texisharp{}) is made by adding ``@code{is}'', a flat
-(@texiflat{}) by adding ``@code{es}'':
-@quotation
+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[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\transpose c'' { cis1 ees fisis aeses }
-s16_" "
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+r2 r4 r8 r16 s16_" "
@end lilypond
-@end quotation
-@separate
-Add a dot ``@code{.}'' after the duration to get a dotted note:
-@quotation
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}
+
@example
a2. a4 a8. a16
@end example
-@c missing clef seems to raise more questions than actual pitch of notes,
-@c as these are snippets anyway
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-%\property Staff.Clef = \turnOff
-\transpose c'' { a2. a4 a8. a16 }
-s16_" "
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a2. a4 a8. a16 s16_" " }
@end lilypond
-@end quotation
-@separate
-The meter (or time signature) can be set with the ``@code{\time}'' command:
+The @rglos{meter} (or @rglos{time signature}) can be set with the
+@code{\time} command
-@quotation
@example
\time 3/4
\time 6/8
\time 4/4
@end example
-@c a clef here may lead to confusion
-@lilypond[fragment]
-\property Staff.Clef = \turnOff
+@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
\time 4/4
s16_" "
@end lilypond
-@end quotation
-@separate
-The clef can be set using the ``@code{\clef}'' command:
+The @rglos{clef} can be set using the @code{\clef} command
@c what is more common name treble or violin?
-@c in Dutch, its violin.
-@quotation
+@c in Dutch, it is violin.
+@c in English it is definitely treble.
@example
-\clef violin
+\clef treble
\clef bass
\clef alto
\clef tenor
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
\clef violin
s4_" "
\clef bass
\clef tenor
s16_" "
@end lilypond
-@end quotation
-@separate
-From these commands and notes, a piece of music can be formed. A piece
-of music is made by enclosing it in ``@code{\notes @{ ... @}}''.
-LilyPond then knows that music follows (and not lyrics, for example):
+
+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
-@example
-\notes @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
-@}
-@end example
+@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
-@separate
-At this point, the piece of music is ready to be printed. This is done
-by combining the music with a printing command.
-The printing command is the so-called ``@code{\paper}'' block. You will
-see later that the \paper block is necessary to customize all kinds of
-printing specifics. The music and the \paper block are combined by
-enclosing them in ``@code{\score @{ ... @}}''. This is what a full
-LilyPond source file looks like:
+@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 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 @{
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- @}
- \paper @{ @}
-@}
+@{ c'4 e' g' @}
@end example
-@lilypond
-\score {
- \notes {
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- \paper { linewidth = 60 * \staffspace }
-}
-@end lilypond
-@end quotation
-@separate
+@noindent
+To process @file{test.ly}, proceed as follows
+@example
+lilypond test.ly
+@end example
+
+@noindent
+You will see something resembling
-We continue with the introduction of the remaining musical constructs.
+@example
+lilypond (GNU LilyPond) 2.2.0
+Running lilypond...
+Now processing `/home/fred/ly/test.ly'
+Parsing...
+Interpreting music...[1]
+@emph{... more interesting stuff ... }
+DVI output to `test.dvi'...
+PDF output to `test.pdf'...
+PS output to `test.ps'...
+@end example
-@c maybe legend here?
+@cindex DVI file
+@cindex Viewing music
+@cindex xdvi
+@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.}
-Rests are entered just like notes with the name ``@code{r}'':
+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
-@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
+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-don't-work
-@c score, but we'd need to remove quotes from the other two (key and
-@c tie) examples...
-@c better to have this just before the `octaves are bad' snipped
-@c but we'd need to remove the ', from \key and tie
-To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a ``low quote'' @code{,}
-(a comma). The central C is @code{c'}:
+@node More about pitches
+@section More about pitches
+
+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,
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
@end lilypond
-@end quotation
-@separate
-A tie is created by entering a tilde ``@code{~}'' between the notes to
-be tied. A tie between two notes means that the second note must not be
-played separately, but just makes the first note sound longer:
-
-@quotation
-@lilypond[fragment,verbatim]
-g'4 ~ g' a'2 ~ a'4
-@end lilypond
-@end quotation
-@separate
+@cindex key signature, setting
+The key signature is set with the command @code{\key}, followed by
+a pitch and @code{\major} or @code{\minor}
-The key signature is set with the command ``@code{\key}'':
-@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.
-Don't worry about all the quotes.
-@quotation
+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.
+
+In this example
+
+@lilypond[quote,notime,fragment]
+\key d \major
+d' cis' fis'
+@end lilypond
+
+@noindent
+no note gets an explicit accidental, but you still must enter
+
@example
-\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 @{ @}
-@}
+\key d \major
+d cis fis
@end 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 }
-}
+@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
+
+@lilypond[quote,notime,fragment]
+\key as \major
+d'
@end lilypond
+
+@example
+\key as \major
+d
+@end example
+
+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.
+
+
+For more information on
+
+@quotation
+@table @asis
+@item Accidentals
+see @ref{Accidentals}.
+
+@item Key signature
+see @ref{Key signature}.
+@end table
@end quotation
-@c accidentals...
-There are some interesting points to note in this example. Firstly,
-accidentals (sharps and flats) don't have to be marked explicitly: you
-just enter the note name, and LilyPond determines whether or not to
-print an accidental. Secondly, bar lines and beams are drawn
-automatically. Thirdly, LilyPond calculates line breaks for you; it
-doesn't matter where you make new lines in the source file.
+@node Entering ties
+@section Entering ties
-The example also indicates that a piece of music written in a high
-register needs lots of quotes. This makes the input a bit unreadable,
-and is therefore also a potential source of errors.
+@cindex tie
+A tie is created by appending a tilde @samp{~} to the first note
+being tied
-@separate
+@lilypond[quote,notime,fragment,verbatim,relative=3]
+g4~ g a2~ a4
+@end lilypond
-The solution is to use ``relative octave'' mode. In practice, most
-music is entered using this mode.
+For more information on Ties see @ref{Ties}.
-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''}.
-@c In relative octave mode, quotes are used to mark large jumps in the
-@c melody. Without any quotes or commas, the interval between a note and
-@c its predecessor is assumed to be a fourth or less. Quotes and commas
-@c add octaves in up and down direction.
-If you type no octaviation quotes, relative mode chooses the note that
-is closest to the previous one, which is often just the one you need.
-@c don't use commas or quotes in this sentence
-For example: @code{c f} goes up; @code{c g} goes down:
+@node Automatic and manual beams
+@section Automatic and manual beams
+
+@cindex beams, by hand
+Beams are drawn automatically
+
+@lilypond[quote,fragment,relative=2,verbatim]
+a8 ais d es r d
+@end lilypond
+
+@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{]}.
+
+@lilypond[quote,fragment,relative=2,verbatim]
+a8[ ais] d[ es r d]
+@end lilypond
+
+For more information on beams, see @ref{Beaming}.
+
+
+Here are key signatures, accidentals and ties in action
-@quotation
@example
-\relative c'' @{
- c f c g 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 example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f c g c
+@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
+
+
+@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
-@c needed better, maybe even redundant explanation
-@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
-@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-You can make a large interval by adding octaviation quotes. Note that
-quotes or commas do not determine the absolute height of a note;
-the height of a note is relative to the previous one.
-@c don't use commas or quotes in this sentence
-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:
+@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.
+
+
+
+@node Octave entry
+@section Octave entry
+
+
+@c Tim wants to move this quotes example just before the: quotes-do not-work
+@c score, but we'd need to remove quotes from the other two (key and
+@c tie) examples...
+
+@c better to have this just before the `octaves are bad' snipped
+@c but we'd need to remove the ', from \key and tie
+To raise a note by an octave, add a high quote @code{'} (apostrophe) to
+the note name, to lower a note one octave, add a `low quote' @code{,}
+(a comma). Middle C is @code{c'}
-@quotation
@example
-\relative c'' @{
- c f, f c' c g' c,
-@}
+c'4 c'' c''' \clef bass c c,
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f, f c' c g' c,
-}
+@lilypond[quote,notime,fragment]
+c'4 c'' c''' \clef bass c c,
@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:
+An example of the use of quotes is in the following Mozart fragment
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4( )c16( cis d e c cis d )e( )d4
+@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
-@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
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8(\( ais b ) c cis2 b'2 a4 cis, \) c
+@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
-@end quotation
-@separate
-Beams are drawn automatically, but if you don't like the choices, you
-can enter beams by hand. Surround the notes to be grouped with @code{[}
-and @code{]}:
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-[a8 ais] [d es r d]
+
+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
-@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 staffs can
-be grouped inside @code{<} and @code{>}, as is demonstrated here:
+@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.
-@quotation
-@lilypond[fragment,verbatim]
-<
- \context Staff = staffA { \clef violin c'' }
- \context Staff = staffB { \clef bass c }
->
+@lilypond[quote,notime,verbatim,fragment]
+\relative c {
+ c'' f, f c' c g' c,
+}
@end lilypond
-@end quotation
-In this example, @code{staffA} and @code{staffB} are names that are
-given to the staffs. For now, it doesn't matter what names you give, as
-long as each staff has a unique name.
+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.
-@separate
+For more information on Relative octaves see @ref{Relative octaves},
+and @ref{Octave check}.
-We can typeset a melody with two staffs now:
-@quotation
-@lilypond[verbatim]
-\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
+@node Music expressions explained
+@section Music expressions explained
-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 staffs.
-@separate
+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
-Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
-@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c->
+@lilypond[fragment,quote,verbatim,relative=3]
+a4
@end lilypond
-@end quotation
-@separate
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
-c-\ff c-\mf
+Enclosing group of notes in braces creates a new music
+expression
+
+@lilypond[fragment,quote,verbatim,relative=3]
+{ a4 g4 }
@end lilypond
-@end quotation
-@separate
-Crescendi are started with the commands @code{\<} and @code{\>}. The
-command @code{\!} finishes a crescendo on the following note.
-@quotation
-@lilypond[verbatim,relative 1]
-c2\< \!c2-\ff \>c2 \!c2
+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
+
+@lilypond[fragment,quote,verbatim,relative=3]
+{ { a4 g } f g }
@end lilypond
-@end quotation
-@separate
-Chords can be made by surrounding notes with @code{<} and @code{>}:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <c e g> <c f a>
+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
-@end quotation
-@separate
-@ignore
-@c te diepzinnig?
-@c hmm, te losjes, iig
-In general, @code{ < @var{stuff} > } is used when @var{stuff} all
-happens at the same time, like in chords, or (like in the two-staff
-example above) in a bunch of stacked staffs.
-@end ignore
+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,
-Of course, you can combine beams and ties with chords. Notice that
-beam and tie markings are placed outside the chord markers:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 [<c8 e g> <c8 f a>] ~ <c8 f a>
-@end lilypond
-@end quotation
+@example
+1
-When you want to combine chords with slurs and dynamics, an annoying
-technical detail crops up: you have type these commands next to the
-notes, which means that they have to be inside the @code{< >}:
+1 + 2
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a>
-@end lilypond
-@end quotation
-@separate
+(1 + 2) * 3
-A nasty technical detail also crops up when you start a score with a
-chord:
+((1 + 2) * 3) / (4 * 5)
+@end example
-@quotation
-@lilypond[verbatim,singleline]
-\score { \notes <c'1 e'1> }
-@end lilypond
-@end quotation
-@separate
+@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.
-The program can not guess that you want the notes on only one staff. To
-force the chord on a staff, add @code{\context Staff} like this:
+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.}
-@quotation
-@lilypond[verbatim,singleline]
-\score { \notes \context Staff <c'1 e'1> }
+@lilypond[fragment,quote,verbatim,relative=2]
+{
+ c <<c e>>
+ << { e f } { c <<b d>> } >>
+}
@end lilypond
-@end quotation
-@separate
+@cindex indent
+When spreading expressions over multiple lines, it is customary to use
+an indent that indicates the nesting level. Formatting music like this
+eases reading, and helps you insert the right number of closing
+braces at the end of an expression. For example,
+
+@example
+\book @{
+ \score @{
+ <<
+ @{
+ @dots{}
+ @}
+ @{
+ @dots{}
+ @}
+ \paper @{
+ @dots{}
+ @}
+ >>
+ @}
+@}
+@end example
+Some editors have special support for entering LilyPond, and can help
+indenting source files. See @ref{Editor support}, for more information.
-@ignore
-[TODO add some more here
+@node More staves
+@section More staves
-* lyrics, chords (?)
+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
-* \header
+@lilypond[quote,fragment,verbatim]
+<<
+ \new Staff { \clef violin c'' }
+ \new Staff { \clef bass c }
+>>
+@end lilypond
-* identifiers?
-]
-@end ignore
+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.
-This is the end of the simple tutorial. You know the basic ingredients
-of a music file, so this is the right moment to try your at hand at
-doing it yourself: try to type some simple examples, and experiment a
-little.
+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).
-When you're comfortable with the basics, then you might want to read the
-rest of this chapter. It also a manual in tutorial-style, but it is much
-more in-depth. It will also be very intimidating if you're not familiar
-with the basics. It deals with some of the more advanced features of
-LilyPond. Topics include lyrics, chords, orchestral scores and parts,
-fine tuning output, polyphonic music, and integrating text and music.
+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.
-@c refer to this section
-@node Simple legend
-@section Simple legend
+We can now typeset a melody with two staves
+@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
-@c need texinfo-4.0a or later for this
+@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. }
+ }
+ \new Staff {
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2.
+ }
+>>
+@end lilypond
+For more information on context see the description in
+@ref{Interpretation contexts}.
-@c both Tim and my father came independently with a request for a
-@c `legend' like this.
-@c what should be in it?
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
+@cindex articulation
+@cindex accents
+@cindex staccato
-@quotation
-@multitable @columnfractions .10 .20 .40
-
-@item @code{[ ]}
-@tab beam
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-[a8 b]
-@end lilypond
+Common accents can be added to a note using a dash (@samp{-}) and a
+single character
-@item @code{~}
-@tab tie
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-d ~ d
+@lilypond[fragment,quote,verbatim,relative=2]
+c-. c-- c-> c-^ c-+ c-_
@end lilypond
-@item @code{( )}
-@tab slur
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-c( d )e
-@end lilypond
-@item @code{'}
-@tab raise octave
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-a a'
-@end lilypond
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(@samp{-}) and the digit to be printed
-@item @code{,}
-@tab lower octave
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-c c,
+@lilypond[fragment,quote,verbatim,relative=2]
+c-3 e-5 b-2 a-1
@end lilypond
-@item @code{< >}
-@tab chord
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-\context Voice { <a c> }
-@end lilypond
-@item @code{\< \!}
-@tab crescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-a\< a \!a
-@end lilypond
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
-@item @code{\> \!}
-@tab decrescendo
-@tab
-@lilypond[fragment, relative 1]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\property Staff.noAutoBeaming = ##t
-\property Staff.Clef = \turnOff
-a\> a \!a
+@lilypond[fragment,quote,verbatim,relative=2]
+c\ff c\mf
@end lilypond
-@end multitable
-@end quotation
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+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
+@lilypond[fragment,quote,verbatim,relative=2]
+c2\< c2\ff\> c2 c2\!
+@end lilypond
-@node Running LilyPond
-@section Running LilyPond
-You write music with LilyPond as follows: first you edit a text file
-containing a description of the notes. Then you run LilyPond on the
-file. This leaves you with an output file, which you can view or print.
-In this section we explain how to run LilyPond, and view or print the
-output. If you have not used LilyPond before, want to test your setup
-of LilyPond, or try to run an example file yourself, then read this
-section.
+@cindex slur
-The instructions that follow are for running LilyPond on Unix-like
-systems. Some additional instructions for running LilyPond on Windows
-are given at the end of this section.
+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
-You begin with opening a terminal window, and start up a text editor.
-For example, open an xterm and execute @code{joe}. In your text editor,
-enter the following input, and save the file as @file{test.ly}:
+@lilypond[fragment,quote,fragment,relative=2,verbatim]
+d4( c16)( cis d e c cis d e)( d4)
+@end lilypond
-@quotation
-@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
-@end example
-@end quotation
+@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
-@cindex ly2dvi
+@lilypond[quote,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
+@end lilypond
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal)
+@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.
-To run LilyPond, you invoke ly2dvi to compile your LilyPond source file:
-
-@quotation
-@example
-ly2dvi -P test.ly
-@end example
-@end quotation
+@lilypond[quote,fragment,relative=2,verbatim]
+a8(\( ais b c) cis2 b'2 a4 cis, c\)
+@end lilypond
-You will see the following on your screen:
-@quotation
-@example
-GNU LilyPond 1.4.0
-Now processing: `/home/fred/ly/test.ly'
-Parsing...
-Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PS output to `test.ps'...
-DVI output to `test.dvi'...
-@end example
-@end quotation
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
+For more information on
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.ps}. The PS file (@file{test.ps}) is the one you can print.
-You can view the PS file using the program ghostview. If a version of
-ghostview is installed on your system, one of these commands will
-produce a window with some music notation on your screen:
-@c eeek
@quotation
-@example
- gv test.ps
- ghostview test.ps
- ggv test.ps
- kghostview test.ps
-@end example
+@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
-If you are satisfied with the looks of the music displayed on your
-screen, you can print the PS file 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. Execute @code{xdvi test.dvi}
-to view the DVI file.
-
-If your DVI viewer does not have a "Print" button, you can print the
-file by executing @code{lpr test.ps}.
-
-@c volgende alinea schrappen?
-
-If you can't get the examples to print, then you should look into
-installing and configuring ghostscript. Refer to GhostScript's website
-at @uref{http://www.ghostscript.com}.
-
-@cindex GhostScript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-
-@unnumberedsubsec Windows users
-Windows users start the terminal by clicking on the LilyPond icon.
-Notepad is sufficient for editing the LilyPond file. Viewing the PS file
-can be done with @code{gsview32 test.ps}. Viewing DVI files can be done
-with @code{yap test.dvi}. The "print" button in Yap will print files.
-You can also print from the command line by executing @code{gsview32 /s
-test.ps}
-
-
-@node The first real tune
-@section The first real tune
-
-
-The rest of this tutorial will demonstrate how to use Lilypond by
-presenting examples of input along with resulting output. We will use
-English terms for notation. In case you are not familiar with those,
-you may consult the glossary that is distributed with LilyPond.
-
-The examples discussed are included in the distribution, in the
-subdirectory @file{input/tutorial/}@footnote{When we refer to filenames,
-they are relative to the top directory of the source package. }
-
-To demonstrate what LilyPond input looks like, we start off with a
-full-fledged, yet simple example. It is a convoluted version
-of the famous minuet in J. S. Bach's @emph{Klavierb@"uchlein}. The file
-is included in the distribution as @file{minuet.ly}.
-@cindex Bach, Johann Sebastian
-
-@lilypond[verbatim]
-% all text after a percent sign is a comment
-% and is ignored by LilyPond
-\include "paper16.ly"
-\score {
- \notes
- \relative c'' \sequential {
- \time 3/4
- \key g \major
-
- \repeat "volta" 2 {
- d4 g,8 a b c d4 g, g |
- e'4 c8 d e fis g4 g, g |
- c4 d8( )c b a( )b4 c8 b a g |
- a4 [b8 a] [g fis] g2. |
- }
-
- b'4 g8 a b g
- a4 d,8 e fis d |
- g4 e8 fis g d cis4 b8 cis a4 |
- a8-. b-. cis-. d-. e-. fis-.
- g4 fis e |
- fis a, r8 cis8
- d2.-\fermata
- \bar "|."
- }
- \paper {
- % standard settings are too big and wide for a book
- indent = 1.0 \cm
- linewidth = 15.0 \cm
- }
-}
-@end lilypond
-We will analyse the input, line by line.
-@separate
-@example
- % all text after a percent sign is a comment
- % and is ignored by LilyPond
-@end example
-Percent signs introduce comments: everything after a percent sign is
-ignored. You can use this to write down mental notes to yourself. You
-can also make longer comments by enclosing text in @code{%@{} and
-@code{%@}}.
-@cindex comment
-@cindex block comment
-@cindex line comment
-@separate
-@example
- \include "paper16.ly"
-
-@end example
-@cindex @code{\include}
-@cindex point, printer's
-@cindex staff size setting
-By default, LilyPond will typeset the music in a size such that each
-staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output
-(16 point staff height), so we must import the settings for that size,
-which is done here.
-@separate
-@example
+@node Combining notes into chords
+@section Combining notes into chords
- \score @{
-
-@end example
-Music is printed by combining a piece of music with directions for
-outputting it. This combination is formed in the @code{\score} block.
-@separate
-@example
-
- \notes
-
-@end example
-Prepare LilyPond for accepting notes.
-@cindex octaves, choosing
-@cindex pitch
-@separate
-@example
-
- \relative c''
-
-@end example
-@cindex relative
-@c removed duplicate introduction to octave marks /MB
-@c Shorten even more?
-
-@c As we will see, each note is described by its note name, duration,
-@c octave and possibly a chromatic alteration. In this setup, the octave
-@c is indicated by using high quotes (@code{'}) and ``lowered quotes''
-@c (commas: @code{,}). The central C is denoted by @code{c'}. The C one
-@c octave higher is @code{c''}. One and two octaves below the central C is
-@c denoted by @code{c} and @code{c,} respectively.
-
-Even though a piece of music often spans a range of several octaves, it
-mostly moves in small intervals. LilyPond has a special entry mode to
-save typing in this situation. In this ``relative'' octave mode,
-octaves of notes without quotes are chosen such that a note is as close
-as possible (graphically, on the staff) to the preceding note. If you
-add a high-quote an extra octave is added. A lowered quote (a comma)
-will subtract an extra octave.
-
-Because the first note has no predecessor,
-you have to give the (absolute) pitch of the note to start with.
-@separate
-@example
-
- \sequential @{
-
-@end example
-What follows is sequential music, i.e.,
-@cindex sequential music
-notes that are to be played and printed after each other.
-@separate
-@example
-
- \time 3/4
-
-@end example
-@cindex time signature, setting
-@cindex @code{\time}
-Set (or change) the time signature of the current piece: a 3/4 sign is
-printed. The time signature setting is also used to generate bar lines
-at the right spots.
-@separate
-@example
-
- \key g \major
-
-@end example
-@cindex key signature, setting
-@cindex @code{\key}
-Set (or change) the current key signature to G-major. Although in this
-example, the @code{\key} command happened to be entered after the
-@code{\time} command, in the output the time signature will be printed
-after the key signature; LilyPond knows about music typesetting
-conventions.
-@separate
-@example
-
- \repeat "volta" 2
-
-@end example
-The following piece of music is played twice. The first argument
-indicates the type of repeat. In this case, @code{"volta"} means that
-prima volta/secunda volta brackets are used for the alternative
-endings---if there were any.
-@separate
-@example
-
- @{
-
-@end example
-The subject of the repeat is again sequential music. Since
-@code{\sequential} is such a common construct, a shorthand is provided:
-just leave off @code{\sequential}, and the result is the same.
-@separate
-@example
-
- d4 g,8
-
-@end example
-Two notes. The first note is a quarter note with relative pitch
-@code{d}. The relative music was started with a @code{c''}, so the real
-pitch of this note is @code{d''}. The duration of a note is designated
-by a number; the @code{4} here represents a quarter note.
-
-The second note is an eight note with relative pitch @code{g,}. The
-pitch is taken relative to the previous @code{d''}, making this
-note have real pitch @code{g'}. The @code{8} represents an eight note.
-@separate
-@example
-
- a b
-
-@end example
-Two more notes, with pitch @code{a} and @code{b}. Because their
-duration is the same as the @code{g,8}, there is no need to enter the
-duration, but you may enter it anyway, i.e., @code{a4 b4}
-@separate
-@example
-
- d4 g, g |
-
-@end example
-@cindex bar check
-@cindex @code{|}
-@cindex errors, finding
-Three more notes. The @code{|} character is a ``bar check''. LilyPond
-will verify that bar checks are found at the start of a measure. This can
-help you track down typing errors.
-
-@cindex alteration, chromatic
-@cindex chromatic alteration
-@separate
-@example
-
- c8 d e fis
-
-@end example
-So far, no notes were chromatically altered. Here is the first one that
-is: @code{fis}. LilyPond by default uses Dutch@footnote{Note names are
-available in several languages, but we find the Dutch names quite
-convenient.} note names, and ``Fis'' is the Dutch note name for ``F
-sharp''. However, there is no sharp sign in the output. The program
-keeps track of key signatures, and will only print accidentals if they
-are needed.
-
-For groups of eighth notes and shorter, LilyPond can determine how the
-notes should form a beam. In this case, the 4 eights are automatically
-printed as a beam.
-@separate
-@example
-
- c4 d8( )c b a( )b4 c8 b a g |
-
-@end example
-The beginning and ending notes of a slur are marked with parentheses,
-@code{(} and @code{)} for start and end respectively. The line above
-indicates two slurs. These slur markers (parentheses) are entered
-between the slurred notes.
-@separate
-@example
-
- a4 [b8 a] [g fis]
-
-@end example
-Automatic beaming can be overridden by inserting beam marks, @code{[}
-and @code{]}. These beam markers (brackets) are put around the notes
-you want beamed.
-@separate
-@example
-
- g2. |
-
-@end example
-@cindex augmentation dot
-@cindex dotted note
-A period adds a dot to the note.
-@separate
-@example
+@cindex chords
+Chords can be made by surrounding pitches with angle brackets.
+Angle brackets are the symbols @samp{<} and @samp{>}.
- @}
-
-@end example
-The end of the sequential music to be repeated. LilyPond will typeset a
-repeat bar.
-@separate
-@example
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>4 <c f a>8
+@end lilypond
- cis'4 b8 cis a4 |
-
-@end example
-Accidentals are printed whenever necessary: the first C sharp of the bar
-will be printed with an accidental, the second one without.
-@separate
-@example
- a8-. b-. cis-. d-. e-. fis-.
-
-@end example
-@cindex articulation
-You can enter articulation signs either in a verbose form or using a
-shorthand. Here we demonstrate the shorthand: it is formed by a dash
-and the character for the articulation to use, e.g. @code{-.} for
-staccato as shown above.
-@separate
-@example
+You can combine markings like beams and ties with chords. They must
+be placed outside the angled brackets
- fis a, r8 cis8
-
-@end example
-
-Rests are denoted by the special note name @code{r}.
-@separate
-@example
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>8[ <c f a>]~ <c f a>
+@end lilypond
- d2.-\fermata
-
-@end example
-All articulations have a verbose form, like @code{\fermata}. The
-command @code{\fermata} is not part of the core of the language, but it
-is a shorthand for a more complicated description of a fermata symbol.
-@code{\fermata} names that description and is therefore called an
-identifier.
-@cindex identifier
-@cindex @code{\fermata}
-@separate
@example
- \bar "|."
- @}
-@end example
-Here the music ends. LilyPond does not automatically typeset an end
-bar, we must explicitly request one, using @code{"|."}.
-
-@separate
-@example
-
- \paper @{
- % standard settings are too big and wide for a book
- indent = 1.0\cm
- linewidth = 15.0\cm
- @}
-
-@end example
-The @code{\paper} block specifies how entered music should be converted
-to notation output. Most of the details of the conversion (font sizes,
-dimensions, etc.) have been taken care of, but to fit the output in this
-document, it has to be narrower. We do this by setting the line width
-to 14 centimeters (approximately 5.5 inches).
-@separate
-@example
-
- @}
-
-@end example
-The last brace ends the @code{\score} block.
-
-
-
-
-@node Lyrics and chords
-@section Lyrics and chords
-
-In this section we show how to typeset a song. This file is
-included as @file{flowing.ly}.
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+@end example
-@example
-\header @{
- title = "The river is flowing"
- composer = "Traditional"
-@}
-\include "paper16.ly"
-melody = \notes \relative c' @{
- \partial 8
- \key c \minor
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-@}
+@lilypond[quote,relative=1,fragment]
+\slurUp
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
+@end lilypond
-text = \lyrics @{
- The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri -- ver is flo -- wing down to the sea.
-@}
-accompaniment =\chords @{
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min @}
-\score @{
- \simultaneous @{
- %\accompaniment
- \context ChordNames \accompaniment
-
- \addlyrics
- \context Staff = mel @{
- \property Staff.noAutoBeaming = ##t
- \property Staff.automaticMelismata = ##t
- \melody
- @}
- \context Lyrics \text
- @}
- \midi @{ \tempo 4=72 @}
- \paper @{ linewidth = 10.0\cm @}
-@}
-@end example
+@node Basic rhythmical commands
+@section Basic rhythmical commands
-The result would look this.@footnote{The titling and font size shown
-may differ, since the titling in this document is not generated by
-@code{ly2dvi}.}
+@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
-@center @strong{The river is flowing}
-@center Traditional
+@lilypond[quote,relative=2,verbatim,fragment]
+\partial 8
+f8 c2 d e
+@end lilypond
-@lilypond[center]
-\header {
- title = "The river is flowing"
- composer = "Traditional"
-}
-\include "paper16.ly"
-melody = \notes \relative c' {
- \partial 8
- \key c \minor
- g8 |
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-}
+@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
-text = \lyrics {
- The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri -- ver is flo -- wing down to the sea.
-}
+@lilypond[quote,relative=1,verbatim,fragment]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+@end lilypond
-accompaniment =\chords {
- r8
- c2:3- f:3-.7 d:min es4 c8:min r8
- c2:min f:min7 g:7^3.5 c:min }
-
-\score {
- \simultaneous {
- %\accompaniment
- \context ChordNames \accompaniment
-
- \addlyrics
- \context Staff = mel {
- \property Staff.noAutoBeaming = ##t
- \property Staff.automaticMelismata = ##t
- \melody
- }
- \context Lyrics \text
- }
- \midi { \tempo 4=72 }
- \paper { linewidth = 10.0\cm }
-}
+@cindex grace notes
+@cindex acciaccatura
+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
-Again, we will dissect the file line by line.
-@separate
-@example
+@noindent
- \header @{
-
-@end example
-@cindex @code{\header}
-Information about the music you are about to typeset goes into a
-@code{\header} block. The information in this block is not used by
-LilyPond, but it is passed into the output. @file{ly2dvi} uses this
-information to print titles above the music.
-@separate
-@example
+For more information on
- title = "The river is flowing"
- composer = "Traditional (?)"
-@end example
-@cindex assignments
-@cindex identifier assignment
-the @code{\header} block contains assignments. In each assignment, a
-variable is set to a value. Lexically, both the variable name and the
-assigned value are strings. The values have to be quoted here, because
-they contain spaces. The variable names could also be put within quotes
-but it is not necessary.
-@separate
-@example
+@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
- \include "paper16.ly"
-
-@end example
-Smaller size for inclusion in a book.
-@separate
-@example
- melody = \notes \relative c' @{
-
-@end example
-The structure of the file will be the same as the previous one, a
-@code{\score} block with music in it. To keep things readable, we will
-give names to the different parts of music, and use the names to
-construct the music within the score block.
+@node Commenting input files
+@section Commenting input files
-@separate
-@example
- \partial 8
-@end example
+@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
-@cindex @code{\partial}
-@cindex anacrusis
-The piece starts with an anacrusis of one eighth.
-@separate
@example
- \key c \minor
-@end example
-The key is C minor: we have three flats.
-
-@separate
-@example
-
- c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
- c4 c8 d [es () d] c4 | d4 es8 d c4.
- \bar "|."
-
-@end example
-
-@cindex manual beaming
-@cindex automatic beaming, turning off
-We use explicit beaming. Since this is a song, we turn automatic
-beams off, and use explicit beaming where needed.
-@separate
-@example
-
- @}
-
-@end example
-This ends the definition of @code{melody}.
-
-@separate
-@example
+% notes for twinkle twinkle follow
+c4 c g' g a a
- text = \lyrics @{
-
-@end example
-@cindex lyrics
-@cindex identifier assignment
-@cindex syllables, entering
-Another identifier assignment. This one is for the lyrics.
-Lyrics are formed by syllables that have duration, and not by
-notes. To make LilyPond parse words as syllables, switch it into
-lyrics mode with @code{\lyrics}. Again, the brace after @code{\lyrics}
-is a shorthand for @code{\sequential @{}.
-@separate
-@example
+%@{
+ This line, and the notes below
+ are ignored, since they are in a
+ block comment.
- The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
- ri- ver is flo- __ wing down to the sea.
-@}
-
+ g g f f e e d d c2
+%@}
@end example
-@cindex extenders, lyric
-@cindex hyphens, lyric
-The syllables themselves are separated by spaces. You can get syllable
-extenders by entering @code{__}, and centered hyphens with
-@code{-}@code{-}. We enter the syllables as if they are all quarter notes
-in length (hence the @code{4}), and use a feature to align the
-syllables to the music, which obviously isn't all quarter notes.
-@separate
-@example
- accompaniment =\chords @{
-
-@end example
-@cindex chords
-@cindex mode, chords
-We'll put chords over the music. To enter them, there is a special mode
-analogous to @code{\lyrics} and @code{\notes} mode, where you can give
-the names of the chords you want, instead of listing the notes
-comprising the chord.
-@separate
-@example
-
- r8
-
-@end example
-There is no accompaniment during the anacrusis.
-@separate
-@example
-
- c2:3- f:3-.7
-
-@end example
-
-@cindex tonic
-@cindex chord modifier
-@cindex modifier, chord
-A chord is started by the tonic of the chord. The
-first one lasts a half note. An unadorned note creates a major
-triad. Since a minor triad is wanted, @code{3-} is added to modify the
-third to be small. @code{7} modifies (adds) a seventh, which is small by
-default to create the @code{f a c es} chord. Multiple modifiers must be
-separated by dots.
-@separate
-@example
+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
- d:min es4 c8:min r8
-
+@example
+\version "2.1.17"
@end example
-Some modifiers have predefined names, e.g. @code{min} is the same as
-@code{3-}, so @code{d-min} is a minor @code{d} chord.
-@separate
-@example
+@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.
- c2:min f:min7 g:7^3.5 c:min @}
-
-@end example
-@cindex named modifier
-
-A named modifier @code{min} and a normal modifier @code{7} do not have
-to be separated by a dot. Tones from a chord are removed with chord
-subtractions. Subtractions are started with a caret, and they are
-also separated by dots. In this example, @code{g:7^3.5} produces a
-minor seventh. The brace ends the sequential music.
-@separate
-@example
-
- \score @{
- \simultaneous @{
-
-@end example
-We assemble the music in the @code{\score} block. Melody, lyrics and
-accompaniment have to sound at the same time, so they should be
-@code{\simultaneous}.
-@cindex @code{\simultaneous}
-@separate
-@example
- %\accompaniment
-
-@end example
-Chord mode generates notes grouped in @code{\simultaneous} music. If
-you remove the comment sign, you can see the chords in normal
-notation: they will be printed as note heads on a separate
-staff. To print them as chords names, they have to be interpreted as
-being chords, not notes. This is done with the following command:
-@separate
-@example
+@node Printing lyrics
+@section Printing lyrics
+@cindex lyrics
- \context ChordNames \accompaniment
-
-@end example
-@cindex context
-@cindex interpretation context
-@cindex notation context
-
-
-Normally, the notes that you enter are transformed into note heads.
-Note heads alone make no sense, they need surrounding information: a key
-signature, a clef, staff lines, etc. They need @emph{context}. In
-LilyPond, these symbols are created by objects called `interpretation
-contexts'. Interpretation contexts exist for generating notation
-(`notation context') and for generating sound (`performance
-context'). These objects only exist during a run of LilyPond.
-
-By default, LilyPond will create a Staff context for you. If you would
-remove the @code{%} sign in the previous line, you would see that
-mechanism in action.
-
-We don't want that default here, because we want chord names. The
-command above explicitly creates an interpretation context of
-@code{ChordNames} type to interpret the music @code{\accompaniment}.
-@separate
-@example
+@c TODO: (c) status of the Queen fragment.
- \addlyrics
-
-@end example
-@cindex @code{\addlyrics}
-@cindex lyrics and melody, combining
-@cindex combining lyrics and melody
-
-The lyrics should be aligned with the melody. This is done by
-combining both with @code{\addlyrics}. @code{\addlyrics} takes two
-pieces of music (usually a melody and lyrics, in that order) and
-aligns the syllables of the second piece under the notes of the
-first piece. If you would reverse the order, the notes would be
-aligned on the lyrics, which is not very useful, and looks
-silly.
-@separate
-@example
+@cindex Lyrics
+@cindex Songs
+Lyrics are entered by separating each syllable with a space
- \context Staff = mel @{
-
+@example
+I want to break free
@end example
-The first argument of @code{\addlyrics} is the melody. We instantiate
-a @code{Staff} context explicitly: should you choose to remove the
-comment before the ``note heads'' version of the accompaniment, the
-accompaniment will be on a nameless staff. The melody has to be on
-staff different from the accompaniment. This is accomplished by giving
-the melody and accompaniment staffs different names.
-@separate
-@example
+Consider the melody
- \property Staff.noAutoBeaming = ##t
-
-@end example
-@cindex \property
-@cindex context variables
-@cindex setting context variables
-An interpretation context has variables, called properties, that tune
-its behavior. One of the variables is @code{noAutoBeaming}. Setting
-this Staff's property to @code{##t}, which is the boolean value @var{true},
-turns the automatic beaming mechanism off for the current staff.
-@cindex GUILE
-@cindex Scheme
-@cindex accessing Scheme
-@cindex evaluating Scheme
-@cindex LISP
-
-LilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
-language from the LISP family. You can learn more about Scheme at
-@uref{http://www.scheme.org}. It is used to represent data throughout
-the whole program. The hash-sign (@code{#}) accesses GUILE directly: the
-code following the hash-sign is evaluated as Scheme. The boolean value
-@var{true} is @code{#t} in Scheme, so for LilyPond @var{true} looks like
-@code{##t}.
-
-If Scheme scares you, don't worry. You don't need to know Scheme to
-create beautiful sheet music.
-
-
-
-@separate
-@example
+@lilypond[quote,verbatim,fragment,raggedright]
+\relative {
+ r4 c \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+}
+@end lilypond
- \property Staff.automaticMelismata = ##t
-
-@end example
-@cindex automaticMelismata
-@cindex melismata
-@cindex @code{\addlyrics} and slurs
-Similarly, we don't want to print a syllable when there is
-a slur. This sets up @code{\addlyrics} to not put lyrics under each
-separate note while there is a slur.
-@separate
-@example
+@c FIXME: when/how/to what rename newlyrics?
+The lyrics can be set to these notes, combining both with the
+@code{\newlyrics} keyword
- \melody
- @}
-
-@end example
-Finally, we put the melody on the current staff. Note that the
-@code{\property} directives and @code{\melody} are grouped in sequential
-music, so the property settings are done before the melody is
-processed.
-@separate
-@example
+@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
- \context Lyrics \text
-
-@end example
-The second argument of @code{\addlyrics} is the text. The text also
-should not land on a Staff, but on a interpretation context for
-syllables, extenders, hyphens etc. This context is called
-Lyrics.
-@separate
-@example
+@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.,
- \midi @{ \tempo 4=72@}
-
-@end example
-MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and recording digital instruments. So a MIDI file is like a
-tape recording of an instrument. The @code{\midi} block makes the
-music go to a MIDI file, so you can listen to the music you entered. It
-is great for checking the music. Whenever you hear something weird, you
-probably hear a typing error.
-
-Syntactically, @code{\midi} is similar to @code{\paper @{ @}}, since it
-also specifies an output method. You can specify the tempo using the
-@code{\tempo} command, in this case the tempo of quarter notes is set to
-72 beats per minute.
-@separate
-@example
-
- \paper @{ linewidth = 10.0\cm @}
-
+@example
+@{ I want to break free __ @}
@end example
-We also want notation output. The linewidth is short so the piece
-will be set in two lines.
-
-@node More movements
-@section More movements
-
-[FIXME: merge here with, or move this to: Other ways to run LilyPond]
-
-You probably ran @file{ly2dvi} on the last example, and ended up with a
-viewable @file{.dvi} file. However, between there are a few steps of
-which LilyPond is only one. To enhance your understanding of what's
-happening under the hood when you run @code{ly2dvi}, we explain what
-programs are run.
-@code{ly2dvi} is a program that calls a number of programs in sequence.
-The first thing it does, is running LilyPond on the input file. After
-some calculations, a @file{.tex} is produced. The contents
-of this file are very low-level instructions.
+@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
-For example, consider the following file (@file{miniatures.ly})
+Similarly, hyphens between words can be entered as two dashes,
+resulting in a centered hyphen between two syllables
@example
-\version "1.4.0"
-\header @{
- title = "Two miniatures"
- tagline = "small is beautiful"
-@}
-
-#(set! point-and-click line-column-location)
-
-\paper @{ linewidth = -1.0 @}
-
-\score @{
- \notes @{ c'4 d'4 @}
- \header @{
- opus = "Opus 1."
- piece = "Up" @}
-@}
-\score @{
- \notes @{ d'4 c'4 @}
- \header @{
- opus = "Opus 2."
- piece = "Down" @}
-@}
+Twin -- kle twin -- kle
@end example
-The titling in this manual was not generated by ly2dvi, so we can't
-exactly show what it would look like, but the result should resemble this:
-
-@center @strong{Two miniatures}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@var{Up}
-@end flushleft
-@lilypond
- \score {
- \notes { c'4 d'4 }
- \paper { linewidth = -1.0 }
- }
-@end lilypond
-@flushright
-Opus 2.
-@end flushright
-@flushleft
-@var{Down}
-@end flushleft
-@lilypond
- \score {
- \notes { d'4 c'4 }
- \paper { linewidth = -1.0 }
- }
+@lilypond[fragment,quote,raggedright]
+<<
+ \relative {
+ \time 2/4
+ f4 f c' c
+ }
+ \newlyrics { Twin -- kle twin -- kle }
+>>
@end lilypond
-This file is produced by ly2dvi in a few stages, with the help of text
-formatting tools. LilyPond produces two output files,
-@file{miniatures.tex} and @file{miniatures-1.tex}. Both files contain
-only graphical music notation. @file{ly2dvi} looks at what output
-LilyPond produces, and adds page layout and titling to those files. The
-result is a DVI file called @file{miniatures.dvi}.
+More options, like putting multiple lines of lyrics below a melody are
+discussed in @ref{Vocal music}.
-Next, now we'll look at the example line by line to explain new things.
-
-@separate
-@example
-\version "1.4.0"
-@end example
-Lilypond and its language are still under development, and occasionally,
-details of the syntax are changed. This fragment indicates for which
-version the input file was written. When you compile this file, the
-version number will be checked, and you will get a warning when the file
-is too old.
+@c FIXME: too geeky, for notation manual?
+@c or introduce using foo = \lyrics { a b c } ?
-This version number is also used by the @code{convert-ly} program (See
-@ref{convert-ly}), which is used to update the file to the latest lily
-version.
+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.
-@separate
@example
- \header @{
- title = "Two miniatures" @}
-@end example
-This sets the titling information for the entire file.
-@separate
-@example
- tagline = "small is beautiful"
-@end example
-A signature line is printed at the bottom of the last page.
- This signature is produced from the @code{tagline} field of
-@code{\header}. Many people find the default "Lily was here,
-@var{version number}" too droll. If that is the case, assign
-something else to @code{tagline}, as shown above.
-@separate
-@example
- #(set! point-and-click line-column-location)
+myText = \lyrics @{ I want to break free @}
@end example
-This piece of Scheme code sets the Scheme variable
-@code{point-and-click} to the value @var{line-column-location} (which
-itself is a Scheme procedure).
-
-Editing input files can be quite complicated if you're working with
-large files: if you're digitizing existing music, you have to
-synchronize the .ly file, the sheet music on your lap and the sheet
-music on the screen. The point-and-click mechanism makes it easy to
-find the origin of an error in the LY file: when you view the file with
-Xdvi and click on a note, your editor will jump to the spot where that
-note was entered. For more information, see @ref{Point and click}.
-
-@separate
-@example
- \paper @{
-@end example
+@noindent
+The braces @code{@{@}} signify that the syllables are sung in
+sequence.
-The @code{\score} blocks that follow in the file don't have
-@code{\paper} sections, so the settings of this block are substituted: A
-paper block at top level, i.e. not in a @code{\score} block sets the
-default page layout.
+@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,
-@separate
@example
- linewidth = -1.0 @}
+\lyrics @{ I want to break free @}
@end example
+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
-The variable @code{linewidth} normally sets the length of the systems on
-the page. However, a negative value has a special meaning. If
-@code{linewidth} is less than 0, no line breaks are inserted into the
-score, and the spacing is set to natural length: a short phrase takes up
-little space, a longer phrase more space.
-
-@separate
-@example
- \score @{
- \notes @{ c'4 d'4 @}
-@end example
+@end ignore
-In previous examples, notes were specified in relative octaves,
-i.e. each note was put in the octave that is closest to its
-predecessor. Besides relative, there is also absolute octave
-specification, which you get when you don't specify @code{\relative}. In
-this input mode, the central C is denoted by @code{c'}. Going down, you
-get @code{c} @code{c,} @code{c,,} etc. Going up, you get @code{c''}
-@code{c'''} etc.
-When you're copying music from existing sheet music, relative octaves
-are probably the easiest to use: it's less typing work and errors are
-easily spotted. However, if you write LilyPond input directly, either by
-hand (i.e. composing) or by computer, absolute octaves may be easier to use.
+@node A lead sheet
+@section A lead sheet
+@cindex Lead sheets
+@cindex chords
+@cindex chord names
-@separate
-@example
- \header @{
-@end example
+In popular music, it is common to denote accompaniment as chord names.
+Such chords can be entered like notes,
-The @code{\header} is normally at the top of the file, where it sets
-values for the rest of the file. If you want to typeset different pieces
-from one file (for example, if there are multiple movements, or if
-you're making an exercise book), you can put different @code{\score}
-blocks into the input file. ly2dvi will assemble all LilyPond output
-files into a big document. The contents of \header blocks specified
-within each score, are used for the titling of each movement.
-@separate
@example
- opus = "Opus 1."
- piece = "Up" @}
+c2 f4. g8
@end example
-For example, the Opus number is put at the right, and the piece string
-will be at the left.
-
-
-
-@node A piano excerpt
-@section A piano excerpt
-
-Our fourth subject is a piece of piano music. The fragment in the input
-file is a piano reduction of the G major Sinfonia by Giovanni Battista
-Sammartini. It was composed around 1740. It's in the source package
-under the name @file{sammartini.ly}.
-@lilypond[verbatim]
-\include "paper16.ly"
+@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}
-stemDown = \property Voice.Stem \override #'direction = #-1
-stemUp = \property Voice.Stem \override #'direction = #1
-stemBoth = \property Voice.Stem \revert #'direction
-
-viola = \notes \relative c' \context Voice = viola {
- <c4-\f-\arpeggio g' c>
- \stemDown g'8. b,16
- s1 s2. r4
- g
-}
-
-oboes = \notes \relative c'' \context Voice = oboe {
- \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a>
- \grace <e8( g> <d4 )f> <c2 e>
- \times 2/3 { <d8 \< f> <e g> <f a> }
- <
- { \times 2/3 { a8 g c } \! c2 }
- \context Voice = oboeTwo {
- \stemDown
- \grace {
- \property Grace.Stem \override #'direction = #-1
- [f,16 g] }
- f8 e e2
- }
- >
- \stemBoth
- \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
- [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r |
- [<c16( e> < )e8. g>] <c8 e,>
-}
+@lilypond[quote,verbatim,raggedright]
+\chords { c2 f4. g8 }
+@end lilypond
-hoomPah = \repeat unfold 8 \notes
- \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth }
-
-bassvoices = \notes \relative c' {
- c4 g8. b,16
- \autochange Staff \hoomPah
- \translator Staff = down
- \stemDown [c8 c'8] r4
- <g d'> r4
- < {\stemUp r2 <e4 c'> <c8 g'> }
- \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } >
-}
+Other chords can be created by adding modifiers after a colon. The
+following example shows a few common modifiers
-\score {
- \context PianoStaff \notes <
- \context Staff = up < \time 2/2
- \viola
- \oboes
- >
- \context Staff = down < \time 2/2 \clef bass
- \bassvoices
- >
- >
- \midi { }
- \paper {
- indent = 0.0
- linewidth = 15.0 \cm }
-}
+@lilypond[quote,verbatim]
+\chords { c2 f4:m g4:maj7 gis1:dim7 }
@end lilypond
-If this looks like incomprehensible gibberish to you, you are right.
-This example has been doctored to have as many quirks as possible.
+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
-As you can see, this example features multiple voices on one staff. To
-make room for those voices, their notes have to be stemmed in opposite
-directions.
+@lilypond[quote,verbatim]
+\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+@end lilypond
-Printed symbols are internally represented by so-called Graphical
-Objects (more colloquially: Grobs). These statements concern the
-grob called `Stem'. Each grob is described by a bunch of settings. These
-setting determine the fonts, offsets, sub-routines to be called on the
-grob, etc. The initial values of these settings are set in the Scheme
-file @file{scm/grob-description.scm}.
+@cindex lead sheet
+When put together, chord names, lyrics and a melody form
+a lead sheet, for example,
-@separate
@example
- stemDown = \property Voice.Stem \override #'direction = #-1
+<<
+ \new ChordNames \chords @{ @emph{chords} @}
+ @emph{the melody}
+ \newlyrics @{ @emph{the text} @}
+>>
+@}
@end example
-Set a property for all Stem grobs in the current Voice:
-@code{direction} is set to @code{-1}, which encodes down. The setting
-remains in effect until it is reverted.
+@lilypond[quote,raggedright]
+<<
+ \new ChordNames \chords { r2 c:sus4 f }
+ \relative {
+ r4 c' \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+ }
+ \newlyrics { I want to break free __ }
+>>
+@end lilypond
-@separate
-@example
- \property Voice.Stem \revert #'direction
-@end example
+A complete list of modifiers and other options for layout can be found
+in @ref{Chords}.
-Revert the to the previous setting. The effect of precisely one
-@code{\stemDown} or @code{\stemUp} is neutralized.
+@c FIXME: we talk about \midi before mentioning \paper (or \layout?)
+@node Listening to output
+@section Listening to output
+@cindex sound
+@cindex MIDI
-LilyPond includes the identifiers @code{\stemUp}, @code{\stemDown} along
-with some other commonly used formatting instructions, but to explain how
-it works, we wrote our own here. Of course, you should use predefined
-identifiers like these if possible: then you will be affected less by
-the implementation changes we occasionally make.
+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.
+
+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,
-@separate
-@example
-viola = \notes \relative c' \context Voice = viola @{
-@end example
-In this example, you can see multiple parts on a staff. Each part is
-associated with one notation context. This notation context handles
-stems and dynamics (among others). The type name of this context is
-@code{Voice}. For each part we have to make sure that there is
-precisely one @code{Voice} context, so we give it a unique name
-(`@code{viola}').
-
-@separate
@example
-<c4-\f-\arpeggio g' c>
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+@}
@end example
-The delimiters @code{<} and @code{>} are shorthands for
-@code{\simultaneous @{} and @code{@}}. The expression enclosed in
-@code{<} and @code{>} is a chord.
-
-@cindex dynamics
-@cindex loudness
-@cindex forte
-@cindex arpeggio
-@code{\f} places a forte symbol under the chord. The forte applies to
-the whole chord, but the syntax requires that commands like forte and
-arpeggio are attached to a note, so here we attach them to the first
-note.
+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}.
-@code{\arpeggio} typesets an arpeggio sign (a wavy vertical line) before
-the chord.
+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
-@separate
@example
- \stemDown
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+ \paper @{ @}
+@}
@end example
+@cindex paper block
-@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).
+@node Adding titles
+@section Adding titles
-@separate
-@example
-s1 s2. r4
-@end example
-@code{s} is a spacer rest. It does not print anything, but it does have
-the duration of a rest. It is useful for filling up voices that
-temporarily don't play. In this case, the viola doesn't come until one
-and a half measure later.
+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,
-@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
-\stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a>
-@end example
-@code{\stemUp} is a reference to the @code{\property \override} command
-defined above.
-@separate
-@example
-\grace <e8 g> < d4 f> <c2 e>
+\header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+@}
+
+@{ @dots{} @}
@end example
-@cindex @code{\grace}
-@cindex ornaments
-@cindex grace notes
-@code{\grace} introduces grace notes. It takes one argument, in this
-case a chord.
+@cindex bibliographic information
+@cindex titles
+@cindex composer
+@cindex Engraved by LilyPond
-@ignore
-The slur started on the @code{e} of the chord
-will be attached to the next note.@footnote{LilyPond will squirm
-about unended Slurs. In this case, you can ignore the warning}.
-@end ignore
-@separate
-@example
-\times 2/3
-@end example
-@cindex tuplet
-@cindex triplets
-Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the piece
-of music is multiplied by the fraction. Triplets make notes occupy 2/3
-of their notated duration, so in this case the fraction is 2/3.
-@separate
-@example
-@{ <d8 \< f> <e g> <f a> @}
-@end example
-The piece of music to be `tripletted' is sequential music containing
-three notes. On the first chord, a crescendo is started with
-@code{\<}. To be precise, the crescendo start is syntactically attached
-to the preceding note, the @code{d}.
+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.}
-@cindex dynamics
-@cindex crescendo
-@cindex @code{\<}
-@separate
-@example
-<
-@end example
-At this point, the homophonic music splits into two rhythmically
-different parts. We can't use a sequence of chords to enter this, so
-we make a `chord' of sequences to do it. We start with the upper
-voice, which continues with upward stems:
-@separate
-@example
- @{ \times 2/3 @{ a8 g c @} \! c2 @}
-@end example
+The @code{\header} block is usually put at the top of the file.
-@cindex @code{\!}
+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.
-The crescendo is ended at the half note by the escaped exclamation
-mark @code{\!}.
-@separate
-@example
-\context Voice = oboeTwo @{
-\stemDown
-@end example
-We can't share stems with the other voice, so we have to create a new
-@code{Voice} context. We give it the name @code{oboeTwo} to distinguish
-it from the other context. Stems go down in this voice.
-@separate
-@example
-\grace @{
-@end example
-@cindex Grace context
-When a grace section is processed, a @code{Grace} context is
-created. This context acts like a miniature score of its own. It has
-its own time bookkeeping, and you can make notes, beams, slurs
-etc. Here we fiddle with a property and make a beam. The argument of
-@code{\grace} is sequential music.
-
-@separate
-@example
-\property Grace.Stem \override #'direction = #-1
-[f,16 g] @}
-@end example
+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.
-Normally, grace notes are always stem up, but in this case, the upper
-voice interferes, so we set the stems down here.
+@ignore
-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
+FIXME: introduce \BOOK
- f8 e e2
-@} >
-@end example
-This ends the two-part section.
-@separate
-@example
-\stemBoth
-\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
-@end example
-@cindex trill
-@cindex stemBoth
+FIXME: Using "Adagio" as a name is confusing, it's more common to be
+a plain tempo indication.
-@code{\stemBoth} ends the forced stem directions. From here, stems are
-positioned as if it were single part music.
+Since today (CVS-1.211) we also allow headers and composite music
+inside book:
-The bass has a little hoom-pah melody to demonstrate parts switching
-between staffs. Since it is repetitive, we use repeats:
-@separate
-@example
-hoomPah = \repeat unfold 8
-@end example
-@cindex unfolded @code{\repeat}
-The unfolded repeat prints the notes in its argument as if they were
-written out in full eight times.
-@separate
-@example
-\notes \transpose c' @{
-@end example
-@cindex transposing
-@cindex relative mode and transposing
-
-Transposing can be done with @code{\transpose}, which takes two arguments.
-The first specifies what central C should be transposed to. The second
-is the to-be-transposed music. As you can see, in this case, the
-transposition has no effect, as central C stays at central C.
-
-The purpose of this no-op is circumventing relative mode. Relative mode
-can not be used together with transposition, so @code{\relative} will
-leave the contents of @code{\hoomPah} alone. We can use it without
-having to worry about getting the motive in a wrong octave.
-@separate
-@example
-bassvoices = \notes \relative c' @{
-c4 g8. b,16
-\autochange Staff \hoomPah
-@end example
-@cindex staff switch, automatic
-@cindex cross staff voice, automatic
-@cindex @code{\autochange}
-
-Voices can switch between staffs. The easiest way to get this, is to use
-@code{\autochange}. This command looks at the pitch of each note, and if
-necessary, will cross to the other staff. For this to work, the two
-staffs must be called @code{"up"} and @code{"down"}.
-@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.
+ \header { ... }
+ \book {
+ \header { ... }
+ { ... }
+ \header { ... }
+ { ... }
+ }
+@end ignore
-@separate
-@example
-\context Voice = reallyLow @{\stemDown g2 ~ | g4 c8 @} >
-@end example
-@cindex tie
-@cindex @code{~}
-After skipping some lines, we see @code{~}. This mark makes ties. Note
-that ties and slurs are different things. A tie can only connect two
-note heads of the same pitch, whereas a slur can connect many chords
-with one curve.
+@cindex Engraved by LilyPond
+@cindex signature line
+@cindex tag line
-@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.
+\header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+@}
+\book @{
+ \score @{
+ @dots{}
+ \header @{ piece = "Adagio" @}
+ @}
+ \score @{
+ @dots{}
+ \header @{ piece = "Menuetto" @}
+ @}
+@}
+@end example
-@ignore
-[TODO:
+More information on titling can be found in @ref{Invoking lilypond}.
-* font-size, multi-stanza.
-* Simple part combining in a Hymn
-@end ignore
+@node Single staff polyphony
+@section Single staff polyphony
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
+When different melodic lines are combined on a single staff 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.
-@node An orchestral score
-@section An orchestral score
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{...@}}), and combining those simultaneously, separating the
+voices with @code{\\}
-@menu
-* The full score::
-* Extracting an individual part::
-@end menu
+@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}
-Our last two examples show a way to setup the music for an orchestral
-score. When typesetting a piece for several instruments, you'll want to
-create a conductor's full score, alongside several individual parts.
+@lilypond[quote,verbatim,relative=3]
+<< { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 } >>
+@end lilypond
-LilyPond is well suited for this task. We will declare the music for
-each instrument individually, giving the music of each instrument its
-own name. These pieces of music are then combined in different
-@code{\score} blocks to produce different combinations of the score.
+@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
-This orchestral score example consists of three input files. In the
-first file, @file{os-music.ly}, we define the music for all instruments.
-This file will be used both for producing the score and the separate
-parts.
+More features of polyphonic typesetting in the notation manual are
+described in @ref{Polyphony}.
-If you were to run LilyPond on this file, no printable output would be
-produced.
-@example
-% os-music.ly
-\header @{
- title = "Zo, goed lieverd?"
- subtitle = "How's, this babe?"
- composer = "JCN"
- opus = "1"
- piece = "Laid back"
-@}
-global = @{
- \time 2/4
- \skip 2*4 \bar "|."
-@}
-Key = \notes \key as \major
-flautoI = \notes\relative c'' @{
- f8 g f g f g f g
- bes as bes as bes as bes as
-@}
-flautoII = \notes\relative c'' @{
- as8 bes as bes R1 d4 ~ d
-@}
-tromboI = \notes\relative c'' @{
- c4. c8 c8 c4. es4 r as, r
-@}
-tromboII = \notes\relative c'' @{
- as4. as8 as8 as4. R1*1/2 as4 es'
-@}
-timpani = \notes\relative c, @{
- \times 2/3 @{ f4 f f @}
- \times 4/5 @{ as8 as as as as @}
- R1
-@}
-corno = \notes\relative c' @{
- bes4 d f, bes d f, bes d
-@}
-@end example
+@node Piano staves
+@section Piano staves
-We will not go through the input line by line, but only indicate and
-explain the new elements.
+@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
-global = @{
- \time 2/4
- \skip 2*4 \bar "|.";
-@}
+<< \new Staff @{ @dots{} @}
+ \new Staff @{ @dots{} @} >>
@end example
-Declare setting to be used globally. The @code{\skip} command produces
-no output, but moves forward in time: in this case, the duration of a
-half note (@code{2}), and that four times (@code{*4}). This brings us
-to the end of the piece, and we can set the end bar.
+@noindent
+but now this entire expression must be interpreted as a
+@code{PianoStaff}
-@separate
@example
-Key = \notes \key as \major
+\new PianoStaff << \new Staff @dots{} >>
@end example
-Declare the key signature of the piece and assign it to the identifier
-@var{Key}. Later on, we'll use @code{\Key} for all staffs except those
-for transposing instruments.
-@node The full score
-@subsection The full score
+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
-The second file, @file{os-score.ly} reads the definitions of the first
-(@file{os-music.ly}), and defines the @code{\score} block for the full
-conductor's score.
+More information on formatting piano music is in @ref{Piano music}.
-@example
-% os-score.ly
-\include "os-music.ly"
-\include "paper13.ly"
+@node Organizing larger pieces
+@section Organizing larger pieces
-#(set! point-and-click line-column-location)
-#(define text-flat '((font-relative-size . -2)
- (music "accidentals--1")))
+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.
-\score @{
- <
- \global
- \property Score.BarNumber \override #'padding = #3
- \context StaffGroup = woodwind <
- \context Staff = flauti <
- \property Staff.midiInstrument = #"flute"
- \property Staff.instrument = "2 Flauti"
- \property Staff.instr = "Fl."
- \Key
- \context Voice=one @{ \voiceOne \flautoI @}
- \context Voice=two @{ \voiceTwo \flautoII @}
- >
- >
- \context StaffGroup = timpani <
- \context Staff = timpani <
- \property Staff.midiInstrument = #"timpani"
- \property Staff.instrument = #'(lines "Timpani" "(C-G)")
- \property Staff.instr = #"Timp."
- \clef bass
- \Key
- \timpani
- >
- >
- \context StaffGroup = brass <
- \context Staff = trombe <
- \property Staff.midiInstrument = #"trumpet"
- \property Staff.instrument = #`(lines "2 Trombe" "(C)")
- \property Staff.instr = #`(lines "Tbe." "(C)")
- \Key
- \context Voice=one \partcombine Voice
- \context Thread=one \tromboI
- \context Thread=two \tromboII
- >
- \context Staff = corni <
- \property Staff.midiInstrument = #"french horn"
- \property Staff.instrument = #`(lines "Corno"
- (columns "(E" ,text-flat ")"))
- \property Staff.instr = #`(lines "Cor."
- (columns "(E" ,text-flat ")"))
- \property Staff.transposing = #3
- \notes \key bes \major
- \context Voice=one \corno
- >
- >
- >
- \paper @{
- indent = 15 * \staffspace
- linewidth = 60 * \staffspace
- textheight = 90 * \staffspace
- \translator@{
- \HaraKiriStaffContext
- @}
- @}
- \midi @{
- \tempo 4 = 75
- @}
-@}
-@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
+By using variables, also known as identifiers, it is possible to break
+up complex music expressions. An identifier is assigned as follows
-@lilypondfile{os-score.ly}
-
-@separate
@example
-\include "os-music.ly"
+namedMusic = @{ @dots{} @}
@end example
-First, we need to include the music definitions we made in
-@file{os-music.ly}.
-@separate
-@example
-#(set! point-and-click line-column-location)
-@end example
-In a large orchestral score like this you're bound to make some small
-mistakes, so we enable point and click (See @ref{Point and click})
-editing.
+@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
-@separate
-@example
-#(define text-flat '((font-relative-size . -2)
- (music "accidentals--1")))
-@end example
+@lilypond[quote,raggedright,verbatim,nofragment]
+seufzer = {
+ e'4( dis'4)
+}
+{ \seufzer \seufzer }
+@end lilypond
-When naming the tuning of the french horn, we'll need a piece of text
-with a flat sign. LilyPond has a mechanism for font selection and
-kerning called Scheme markup text (See @ref{Text markup}). The flat
-sign is taken from the music font, and its name is @code{accidentals--1}
-(The sharp sign is called @code{accidentals-1}). The default font is
-too big for text, so we select a relative size of @code{-2}.
+The name of an identifier should have alphabetic characters only;
+no numbers, underscores or dashes. The assignment should be outside of
+running music.
-@separate
-@example
- <
- \global
-@end example
-Of course, all staffs are simultaneous and use the same global settings.
+It is possible to use variables for many other types of objects in the
+input. For example,
-@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.
-A bar number internally is a Grob called @var{BarNumber}. BarNumber
-Grobs can be manipulated through their @var{side-position-interface}. One
-of the properties of a @var{side-position-interface} that can be tweaked
-is the @var{padding}: the amount of extra space that is put between this
-Grob and other Grobs. We set the padding to three staff spaces.
-
-You can find information on all these kind of properties in LilyPond's
-automatically generated documentation in
-@ifnottex
-@ref{ (lilypond-internals)lilypond-internals, LilyPond Internals}.
-@end ifnottex
-@iftex
-the online documentation.
-@end iftex
-
-@separate
@example
- \context StaffGroup = woodwind <
- \context Staff = flauti <
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example
-A new notation context: the StaffGroup. StaffGroup can hold one or more
-Staffs, and will print a big bracket at the left of the score. Start a
-new staff group for the woodwind section (just the flutes in this case).
-Immediately after that, we start the staff for the two flutes, that also
-play simultaneously.
-@separate
-@example
- \property Staff.midiInstrument = #"flute"
-@end example
-Specify the instrument for MIDI output (see @ref{MIDI instrument
-names}).
+Depending on its contents, the identifier can be used in different
+places. The following example uses the above variables
-@separate
@example
- \property Staff.instrument = "2 Flauti"
- \property Staff.instr = "Fl."
+ \paper @{
+ \aFivePaper
+ linewidth = \width
+ @}
+ @{ c4^\name @}
@end example
-And define the instrument names to be printed in the margin,
-@code{instrument} for the first line of the score, @code{instr} for the
-rest of the score.
-@separate
-@example
- \Key
-@end example
-The flutes play in the default key.
+More information on the possible uses of identifiers is in the
+technical manual, in TODO.
-@separate
-@example
- \context Voice=one @{ \voiceOne \flautoI @}
- \context Voice=two @{ \voiceTwo \flautoII @}
-@end example
-Last come the actual flute parts. Remember that we're still in
-simultaneous mode. We name both voices differently, so that LilyPond
-will actually create two Voice contexts. The flute parts are simple, so
-we specify manually which voice is which: @code{\voiceOne} forces the
-direction of stems, beams, slurs and ties up, @code{\voiceTwo} sets
-directions down.
-
-@separate
-@example
- >
- >
-@end example
-Close the flutes staff and woodwind staff group.
-@separate
-@example
- \property Staff.instrument = #'(lines "Timpani" "(C-G)")
-@end example
-The timpani staff only shows a new piece of scheme markup, it sets two
-lines of text.
+@node An orchestral part
+@section An orchestral part
-@separate
-@example
- \context Voice=one \partcombine Voice
- \context Thread=one \tromboI
- \context Thread=two \tromboII
-@end example
-You have seen the notation contexts Staff and Voice, but here's a new
-one: Thread. One or more Threads can be part of a Voice. The Thread
-takes care of note heads and rests, the Voice combine note heads onto a
-stem.
-
-For the trumpets we use the automatic part combiner (see @ref{Automatic
-part combining}) to combine the two simultaneous trumpet parts onto the
-trumpet staff. Each trumpet gets its own Thread context, which must be
-named @code{one} and @code{two}). The part combiner makes these two
-threads share a Voice when they're similar, and splits the threads up
-when they're different.
-
-@separate
-@example
- \property Staff.instrument = #`(lines "Corno"
- (columns "(E" ,text-flat ")"))
-@end example
-The french horn has the most complex scheme markup name, made up of two
-lines of text. The second line has three elements (columns), the @code{(E},
-the flat sign @code{text-flat} that we defined before and a final @code{")"}.
-Note that we use a backquote instead of an ordinary quote at the
-beginning of the Scheme expression to be able to access the
-@code{text-flat} identifier, `unquoting' it with a @code{,}.
-
-@separate
-@example
- \property Staff.transposing = #3
-@end example
-The french horn is to be tuned in E-flat, so we tell the MIDI backend to
-transpose this staff by three steps.
+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.
-Note how we can choose different tuning for entering, printing and
-playing, using @code{\transpose} and the MIDI Staff property
-@var{transposing}.
+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
-@separate
@example
- \notes \key bes \major
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
@end example
-Therefore, it has a different key.
-@separate
+@noindent
+Then, an individual part is made by putting the following in a file
+
@example
- indent = 15 * \staffspace
- linewidth = 60 * \staffspace
-@end example
-We specify a big indent for the first line and a small linewidth for this
-tutorial.
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
-@separate
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
-Usually, LilyPond's predefined setup of notation contexts (Thread,
-Voice, Staff, Staffgroup, Score) is just fine. But in this case, we
-want a different type of Staff context.
+The line
@example
- \translator@{
- \HaraKiriStaffContext
- @}
+\include "horn-music.ly"
@end example
-In orchestral scores, it often happens that one instrument has only
-rests during one line of the score. The @code{HaraKiriStaffContext} can
-be used as a regular @code{StaffContext} drop-in and will take care of
-the automatic removing of empty staffs.
-
-@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.
+@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
-@example
-\include "os-music.ly"
-\include "paper16.ly"
+@lilypond[quote,raggedright]
+ \transpose f c' \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+ }
+@end lilypond
-\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
- @}
-@}
-@end example
+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
-@center @strong{Zo, goed lieverd?}
-@sp 1
-@center How's, this babe?
-@center @emph{Flauto II}
-@flushright
-Opus 1.
-@end flushright
-@flushleft
-@sc{Laid back}
-@end flushleft
-@lilypondfile{os-flute-2.ly}
-
-
-Because we separated the music definitions from the @code{\score}
-instantiations, we can easily define a second score with the music of
-the second flute. This then is the part for the second flute player.
-Of course, we make separate parts for all individual instruments.
-
-@separate
@example
- \flautoII
+R2*3
@end example
-In this individual part the second flute has a whole staff for itself,
-so we don't want to force stem or tie directions.
-@separate
-@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.
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
-@separate
@example
- \property Score.skipBars = ##t
+\set 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 contract pieces of consecutive empty
-bars. LilyPond will do this if Score's @var{skipBars} property to
-true.
+@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
-@node Other ways to run LilyPond
-@section Other ways to run LilyPond
+@lilypond[quote,raggedright]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+ }
+@end lilypond
-Until now, you have been using @file{ly2dvi} to invoke LilyPond.
-There are three other routes. Firstly, there is a script called
-@code{lilypond-book}, that allows you to freely mix LilyPond input with
-Texinfo or \LaTeX input. For example, this manual was written using
-@code{lilypond-book}. It is discussed below and in @ref{lilypond-book}.
+The score is made by combining all of the music together. Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
-Secondly, you can generate PostScript directly. This is useful if you
-can not or do not want to run @TeX{} on your system. To obtain direct
-PostScript output, invoke LilyPond as follows:
-@cindex PostScript output
@example
-lilypond -f ps test.ly
-@end example
-You have to set some environment variables to view or print this output.
-More information can be found in @ref{Invoking LilyPond}. Since the
-direct Postscript generation has some problems, it is recommended
-to use @file{ly2dvi}.
-
+\include "bassoon-music.ly"
+\include "horn-music.ly"
-Thirdly, if you want to do special things with your output, you can run
-invoke LilyPond directly:
-@example
-lilypond test.ly
+ <<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+ >>
@end example
-to produce plain @TeX{} output. Note that La@TeX{} will not work on the
-resulting @file{test.tex}. You must run plain @TeX{} on it.
-@cindex @TeX{}
+@noindent
+leading to
+@lilypond[quote,raggedright]
+ \relative c <<
+ \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
+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
-Sometimes, you might want to use music examples in a text that you are
-writing. For example, if you are writing a musicological treatise, a
-songbook, or (like us) the LilyPond manual. You can make such texts by
-hand, simply by importing a PostScript figure into your wordprocessor.
-However, there is a also an automated procedure:
+@cindex La@TeX{}, music in
+@cindex HTML, music in
+@cindex Texinfo, music in
+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.
-If you use 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. lilypond-book is
-described fully in @ref{lilypond-book}, but here we show a small
-example. Since the example also contains explanatory text, we won't
-comment on the contents.
+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:
-\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:
+Documents for lilypond-book may freely mix music and text. For
+example,
\begin@{lilypond@}
- c'4
+ @{ \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
-\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:
+Options are put in brackets.
-\begin[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]@{lilypond@}
- c'4 f bes es
+\begin[fragment,quote,staffsize=26,verbatim]@{lilypond@}
+ c'4 f16
\end@{lilypond@}
-\texttt@{verbatim@} also shows the LilyPond code, \texttt@{11pt@} selects
-the default music size, \texttt@{fragment@} adds a score block,
-\texttt@{relative@} uses relative mode for the fragment, and
-\texttt@{intertext@} specifies what to print between the
-\texttt@{verbatim@} code and the music.
-
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
-
-\lilypondfile[printfilename]@{sammartini.ly@}
+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
-$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.3.146
-Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex'
-Reading
-`/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/sammartini.ly'
+$ mkdir -p out/
+$ 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 wouldn't want
-those to clutter up your working directory. Hence, we have them created
-in a separate subdirectory.
-
-The result more or less looks like this:
-
-@separate
-
-In a lilypond-book document, you can freely mix music and text. For
-example:
-@lilypond
- \score { \notes \relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
- } }
-@end lilypond
-Notice that the music line length matches the margin settings of the
-document.
-
-If you have no @code{\score} block in the fragment,
-@code{lilypond-book} will supply one:
+To convert the file into a nice PDF document, run the following
+commands
-@lilypond
- c'4
-@end lilypond
-
-In the example you see here, a number of things happened: a
-@code{\score} block was added, and the line width was set to natural
-length. You can specify many more options using La@TeX{} style options
-in brackets:
-
-@lilypond[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]
- c'4 f bes es
-@end lilypond
-
-@code{verbatim} also shows the LilyPond code, @code{11pt} selects
-the default music size, @code{fragment} adds a score block,
-@code{relative} uses relative mode for the fragment, and
-@code{intertext} specifies what to print between the
-@code{verbatim} code and the music.
-
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
-
-@lilypondfile[printfilename]{sammartini.ly}
-
-The @code{printfilename} option adds the file name to the output.
-@node End of tutorial
-@section End of tutorial
-
-That's all folks. From here, you can either try fiddling with input
-files, or you can read the reference manual. You can find more example
-files in @file{input} and @file{input/test}. You can also look at some
-real music. The website @uref{http://www.mutopiaproject.org} has many
-examples of real music typeset by LilyPond.
-
-
-
-@ignore
-
-[TODO
-
-this should be on mutopia website.
-
-]
-
-
-@c waar deze info? is uiteindelijk wel handig, schat ik.
-[TODO: cut blabla]
-
-If you have a big music project, or just a lot of LilyPond input files,
-all generated output from LilyPond, @TeX{} and metafont will clutter
-your working directory. LilyPond comes with a one-size-fits-all
-pre-cooked makefile that helps you manage producing output. It will
-produce all output in the directory @file{out} , generate and track
-dependencies. Also, it helps in preparing your submission to @ref{Mutopia
-project}.
-
-@file{make/ly.make}
@example
-mkdir my-project
-cd my-project
-cp /usr/share/lilypond/make/ly.make GNUmakefile
-cp /usr/share/doc/lilypond/examples/input/tutorial/minuet.ly .
-make minuet
-[..]
-Generated out/minuet.ps for target minuet.
+$ dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
+$ ps2pdf lilybook.ps
@end example
-Type @samp{make help} to see possible targets.
-
-[TODO]
-@file{/usr/share/lilypond/doc/lilypond/examples/input/mutopia-header.ly}
+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}.
+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.
+@page
+Documents for lilypond-book may freely mix music and text. For
+example,
+@lilypond
+\relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+}
+@end lilypond
-[TODO: rewrite completely.]
+Options are put in brackets.
-@menu
-* Songs with additional verses::
-@end menu
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
-@end ignore
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.
+@lilypondfile[quote,noindent]{screech-boink.ly}
projects / lilypond.git / blobdiff