@c -*-texinfo-*-
+@c This file is part of lilypond.tely
@c TODO:
@c * more details about running lilypond; error messages,
@c compiling/viewing (emacs?)
-@c * where to go from First steps+More basics?
+@c * where to go from First steps+More basics?
+
+@c Your first LilyPond score in 10 minutes?
@node Tutorial
@chapter Tutorial
-@html
-<!--- @@WEB-TITLE@@=Tutorial --->
-@end html
-
-@menu
-* First steps:: Music language of LilyPond.
-* Running LilyPond:: Printing music.
-* More basics::
-* Printing lyrics::
-* A lead sheet::
-* Listening to output::
-* Titling ::
-* Single staff polyphony ::
-* Piano staffs::
-* Setting variables::
-* Fine tuning layout::
-* Organizing larger pieces::
-* An orchestral part::
-* Integrating text and music:: Integrating text and music.
-@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.
-Printing music with LilyPond is a two step process. First, the music
-to be printed is described in a text file. After that, LilyPond reads
-this @emph{input file} that describes the music and produces an
-@emph{output file} that can be printed or viewed.
+@ifhtml
+Many people learn programs by trying and fiddling around with the
+program. This is also possible with LilyPond. If you click on a
+picture in the HTML version of this manual, you will see the exact
+LilyPond input that was used to generate that image.
+Try it on this image
+
+@lilypond[fragment,quote,raggedright,relative=2]
+c-\markup { \bold \huge { Click here. } }
+@end lilypond
+@end ifhtml
-This tutorial starts with a short introduction to the LilyPond music
-language. After this first contact, we will show you how to to
-produce printed output, normally using the program @code{ly2dvi}. You
-should then be able to create and print your first sheets of music.
-Before starting out, it will be convenient for you to print
+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
@node First steps
@section First steps
-We start off by showing how very simple music is entered in LilyPond:
-you get a note simply by typing its @htmlref{note name}, from @samp{a}
-through @samp{g}. So if you enter
+The first example demonstrates how to enter the most elementary piece
+of music, a scale. A note can be entered by typing its name, from
+@samp{a} through @samp{g}. So, if you enter
@example
c d e f g a b
@end example
@noindent
-then the result looks like this:
+the result looks like this
-@c ?
-@c \transpose c c' { c d e f g a b }
-@c @lily pond[notime]
-@c \property Score.timing = ##f
-@lilypond[notime, relative=2]
+@lilypond[fragment,quote,notime,relative=1]
c d e f g a b
@end lilypond
-We will continue with this format: First we show a snippet of input,
-then the resulting output.
-
-The length of a note is specified by adding a number, @samp{1} for a
-@rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
+The duration of a note is specified by a number after the note name.
+@samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
+@samp{4} for a @rglos{quarter note} and so on
@example
a1 a2 a4 a16 a32
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\property Staff.autoBeaming = ##f
-\transpose c c' { a1 a2 a4 a16 a32 s16_" " }
+@c FIXME: have NOTIME also remove Score.timing?
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+\set Staff.autoBeaming = ##f
+{ a1 a2 a4 a16 a32 s16_" " }
@end lilypond
-If you do not specify a @rglos{duration}, the previous one is used:
+If you do not specify a @rglos{duration}, the duration last entered is
+used for the next notes. The duration of the first note in input
+defaults to a quarter
@example
-a4 a a2 a
+a a8 a a2 a
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a a a2 a s16_" " }
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a a8 a a2 a s16_" " }
@end lilypond
-A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
-@rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect,
-a @rglos{double sharp} or @rglos{double flat} is made by adding
-@samp{isis} or @samp{eses}:@footnote{This syntax derived from note
-naming conventions in Nordic and Germanic languages, like German and
-Dutch.}
+Rests are entered just like notes, but with the name @samp{r}
+
+@cindex rests
@example
-cis1 ees fisis aeses
+r2 r4 r8 r16
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+r2 r4 r8 r16 s16_" "
@end lilypond
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
+Add a dot @samp{.} after the duration to get a @rglos{dotted note}
@example
a2. a4 a8. a16
@end example
-@lilypond[notime]
-\property Score.timing = ##f
-\transpose c c' { a2. a4 a8. a16 s16_" " }
+@lilypond[fragment,quote,notime,relative=1]
+\set Score.timing = ##f
+{ a2. a4 a8. a16 s16_" " }
@end lilypond
-Entering pitches and durations is fully explained in @ref{Pitches} and
-@ref{Durations}.
-
-
The @rglos{meter} (or @rglos{time signature}) can be set with the
-@code{\time} command:
+@code{\time} command
@example
\time 3/4
\time 4/4
@end example
-@c a clef here may lead to confusion
-@lilypond
-\property Staff.Clef \set #'transparent = ##t
+@c A clef here may lead to confusion, remove it.
+@lilypond[fragment,quote]
+\override Staff.Clef #'transparent = ##t
\time 3/4
s4_" "
\time 6/8
s16_" "
@end lilypond
-Time signatures and other timing commands are described in @ref{Time
-signature}.
-
-
-The @rglos{clef} can be set using the @code{\clef} command:
+The @rglos{clef} can be set using the @code{\clef} command
@c what is more common name treble or violin?
-@c in Dutch, its violin.
-@c in English its definitely treble.
+@c in Dutch, it is violin.
+@c in English it is definitely treble.
@example
\clef treble
\clef bass
\clef tenor
@end example
-@lilypond[notime]
-\property Score.timing = ##f
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
\clef violin
s4_" "
\clef bass
s16_" "
@end lilypond
-Clefs are fully explained in @ref{Clef}.
-
-
-These commands must be enclosed in @code{\notes @{@dots{}@}}. This
-indicates that music (as opposed to @rglos{lyrics}) follows:
+@ignore
+To recognize names like @samp{c} and @samp{d} as pitches, they have to
+be entered inside a so-called @code{\notes} block. This block is
+formed by enclosing notes and commands are enclosed in curly braces
+@code{@{@tie{}@dots{}@tie{}@}} and adding the keyword @code{\notes} before
+the opening brace
@example
-\notes @{
+@{
\time 3/4
\clef bass
c2 e4 g2.
- f4 e d c2.
+ f4 e d c2 r4
@}
@end example
-Now the piece of music is almost ready to be printed. The final step is to
-combine the music with a printing command.
-The printing command is the so-called @code{\paper} block. Later on
-you will see that the @code{\paper} block is used to customize
-printing specifics. The music and the @code{\paper} block are combined by
-enclosing them in @code{\score @{ ... @}}. This is what a full source file looks like:
+Now the piece of music is almost ready to be printed. Enclose
+the @code{\notes} block in a @code{\score} block
@example
\score @{
\time 3/4
\clef bass
c2 e4 g2.
- f4 e d c2.
+ f4 e d c2 r4
@}
- \paper @{ @}
@}
@end example
-@lilypond[noindent]
-\score {
- \notes {
- \time 3/4
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- \paper {
- linewidth = 55 * \staffspace
- }
+@noindent
+and the music will be converted to printable output.
+@end ignore
+
+Remember to enclose the notes and commands in curly braces
+@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
+
+@lilypond[fragment,quote,noindent,linewidth=55\staffspace]
+{
+ \time 3/4
+ \clef bass
+ c2 e4 g2.
+ f4 e d c2 r4
}
@end lilypond
+For more elaborate information on
+
+@quotation
+@table @asis
+@item Entering pitches and durations
+see
+@ref{Pitches}, and @ref{Durations}.
+@item Clefs
+see @ref{Clef}.
+@item Rests
+see @ref{Rests}.
+@item Time signatures and other timing commands
+see @ref{Time signature}.
+@end table
+@end quotation
+
@node Running LilyPond
@section Running LilyPond
+@c FIXME: let's not be so casual about Emacs and VIM, but rather
+@c instruct (how) to use them; let advanced user figure-out what
+@c commands to type?
+
+@c
+@c We don't have enough space to explain either VIM
+@c or Emacs non-advanced users, and I fear that both editors will only
+@c confuse newbies. I vote for keeping the material in footnotes.
+@c
+@c --hwn
+
In the last section we explained what kind of things you could enter
-in a LilyPond file. In this section we explain what commands to run
-and how to view or print the output. If you have not used LilyPond
-before, want to test your setup, or want to run an example file
-yourself, read this section. The instructions that follow are for
-Unix-like systems. Some additional instructions for 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}. In your
-text editor, enter the following input and save the file as
-@file{test.ly}:
+in a LilyPond file. In this section we will explain what commands to
+run and how to view or print the output. If you have not used
+LilyPond before, want to test your setup, or want to run an example
+file yourself, read this section. The instructions that follow are
+for Unix-like systems. Some additional instructions for Microsoft
+Windows are given at the end of this section.
+
+Begin by opening a terminal window and starting a text editor. For
+example, you could open an xterm and execute
+@code{joe}.@footnote{There are macro files for VIM addicts, and there
+is a @code{LilyPond-mode} for Emacs addicts. If it has not been
+installed already, refer to
+@c FIXME lousy reference.
+the file @file{INSTALL.txt}.} In your text editor, enter the following
+input and save the file as @file{test.ly}
-@quotation
@example
-\score @{
- \notes @{ c'4 e' g' @}
-@}
+@{ c'4 e' g' @}
@end example
-@end quotation
-@cindex ly2dvi
-
-@c now this is weird, running ly2dvi to run LilyPond
-@c (therefore name change proposal)
-
-LilyPond is the program that computes the sheet music. All other
-things, such as adding titles, page breaking and other page layout,
-are done by a small wrapper program called
-@code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
-then adds the titling and page layout instructions. To process
-@file{test.ly} with @code{ly2dvi}, proceed as follows:
+@noindent
+To process @file{test.ly}, proceed as follows
-@quotation
@example
-ly2dvi -p test.ly
+lilypond test.ly
@end example
-@end quotation
-You will see the following on your screen:
+@noindent
+You will see something resembling
-@quotation
@example
-GNU LilyPond 1.7.16
-Now processing: `/home/fred/ly/test.ly'
+lilypond (GNU LilyPond) 2.2.0
+Running lilypond...
+Now processing `/home/fred/ly/test.ly'
Parsing...
Interpreting music...[1]
- @emph{ ... more interesting stuff ... }
-PDF output to `test.pdf'...
+@emph{... more interesting stuff ... }
DVI output to `test.dvi'...
+PDF output to `test.pdf'...
+PS output to `test.ps'...
@end example
-@end quotation
+
@cindex DVI file
@cindex Viewing music
@cindex xdvi
+@noindent
+The result is the file @file{test.pdf}@footnote{For @TeX{}
+aficionados: there is also a @file{test.dvi} file. It can be viewed
+with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
+not show up in the magnifying glass. The specials also mean that the
+DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
+printing.
+@cindex dvips
+@cindex dvilj
+@cindex DVI driver
+} which you can print or with the standard facilities of your
+operating system.@footnote{If your system does not have any tools
+installed, you can try @uref{Ghostscript,
+http://www.cs.wisc.edu/~ghost/}, a freely available package for
+viewing and printing PDF and PostScript files.}
+
+On Windows, start up a text-editor@footnote{Any simple or
+programmer-oriented editor will do, for example Notepad. Do not use a
+word processor, its formatting codes will confuse LilyPond.} and enter
-The results of the ly2dvi run are two files, @file{test.dvi} and
-@file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can
-print or view. For example, viewing PDF can be done with ghostview.
-If a version of ghostview is installed on your system, one of these
-commands will produce a window with some music notation on your
-screen:
-@c eeek
-@quotation
@example
- gv test.pdf
- ghostview test.pdf
- ggv test.pdf
- kghostview test.pdf
- xpdf test.pdf
- gpdf test.pdf
+@{ c'4 e' g' @}
@end example
-@end quotation
-If the music on your screen looks good, you can print it by clicking
-File/Print inside ghostview.
-
-The DVI file (@file{test.dvi}) contains the same sheet music in a
-different format. DVI files are more easily processed by the computer,
-so viewing them usually is quicker. You can run @code{xdvi test.dvi}
-@c KDVI doesn't grok the PS specials.
-@c or
-@c @code{kdvi test.dvi}
-@c
-to view the DVI file. In Xdvi, the mouse buttons
-activate magnifying glasses. Unfortunately, variable symbols (such as
-beams and slurs) are not displayed in the magnifying glasses.
+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.
-@cindex Ghostscript
-@cindex @code{lpr}
-@cindex Printing output
-@cindex PostScript
-@cindex PDF
-If you are familiar with @TeX{}, be warned: do not use other DVI
-drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code
-and will not render correctly with other DVI drivers besides
-@code{dvips}.
+@node More about pitches
+@section More about pitches
-@cindex dvips
-@cindex dvilj
-@cindex DVI driver
+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.}
+
+@example
+cis1 ees fisis aeses
+@end example
+
+@lilypond[fragment,quote,notime]
+\set Score.timing = ##f
+\transpose c c' { cis1 ees fisis aeses s16_" " }
+@end lilypond
+@cindex key signature, setting
+The key signature is set with the command @code{\key}, followed by
+a pitch and @code{\major} or @code{\minor}
-Various commands for formatting and printing music are detailed in
-@ref{Invoking LilyPond}.
+@example
+\key d \major
+g1
+\key c \minor
+g
+@end example
+@lilypond[fragment,quote,notime,fragment]
+\key d \major
+g'1
+\key c \minor
+g'
+@end lilypond
-@unnumberedsubsec Windows users
+@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.
+
+
+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
-On Windows, the terminal is started by clicking on the LilyPond or
-Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be
-used to edit the LilyPond file. When Cygwin's @code{XFree86} X11
-window system is installed along with @code{tetex-x11} and
-@code{ghostscript-x11} packages, then the @code{dvi} output may be
-viewed with @code{xdvi test.dvi} as described above. If you have
-installed a PostScript/PDF viewer, such as @code{GSView} from
-@uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
-with:
-@quotation
@example
-@code{gsview32 test.pdf}
+\key d \major
+d cis fis
@end example
-@end quotation
-Printing may be done by executing
-@quotation
+
+@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
-@code{gsview32 /s test.pdf}
+\key as \major
+d
@end example
-@end quotation
+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.
-@node More basics
-@section More basics
-We continue with the introduction of more musical constructs. Normal
-rests are entered just like notes with the name ``@code{r}'':
+For more information on
@quotation
+@table @asis
+@item Accidentals
+see @ref{Accidentals}.
+
+@item Key signature
+see @ref{Key signature}.
+@end table
+@end quotation
+
+@node Entering ties
+@section Entering ties
+
+@cindex tie
+A tie is created by appending a tilde @samp{~} to the first note
+being tied
+
+@lilypond[quote,notime,fragment,verbatim,relative=3]
+g4~ g a2~ a4
+@end lilypond
+
+For more information on Ties see @ref{Ties}.
+
+
+
+@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
+
@example
-r2 r4 r8 r16
+@{
+ \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.Clef = \turnOff
-\property Staff.TimeSignature = \turnOff
-r2 r4 r8 r16
-s16_" "
+@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
-Rests are described in full detail in @ref{Rests}.
+@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 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'}:
+the note name, to lower a note one octave, add a `low quote' @code{,}
+(a comma). Middle C is @code{c'}
-@quotation
@example
c'4 c'' c''' \clef bass c c,
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
+@lilypond[quote,notime,fragment]
c'4 c'' c''' \clef bass c c,
@end lilypond
-@end quotation
-@separate
-A tie is created by adding a tilde ``@code{~}'' to the first note
-being tied.
-@quotation
-@lilypond[fragment,verbatim]
-g'4-~ g' a'2-~ a'4
+An example of the use of quotes is in the following Mozart fragment
+
+@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
-A tie is different from a slur. A tie simply makes the first note
-sound longer, and can only be used on pairs of notes with the same
-pitch. Slurs indicate the articulations of notes, and can be used on
-larger groups of notes. Slurs and ties are also nested in practice:
-@lilypond[fragment, relative=1]
-c2-~-( c8 fis fis4 ~ fis2 g2-)
+
+@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
-The notation manual discusses ties in @ref{Ties}.
-The key signature is set with the command ``@code{\key}'', followed by
-a pitch and @code{\major} or @code{\minor}:
-@quotation
-@example
-\key d \major
-g'1
-\key c \minor
-g'
-@end example
+Since most music has small intervals, pieces can be written almost
+without octavation quotes in relative mode. The previous example is
+entered as
-@lilypond[fragment]
-\property Staff.TimeSignature = \turnOff
-\key d \major
-g'1
-\key c \minor
-g'
+@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
+@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.
+@lilypond[quote,notime,verbatim,fragment]
+\relative c {
+ c'' f, f c' c g' c,
+}
+@end lilypond
-@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.
+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.
-@quotation
-@example
-\score @{
- \notes @{
- \time 4/4
- \key d \minor
- \clef violin
- r4 r8 d''8 cis''4 e''
- d''8 a'4.-~ a' b'8
- cis''4 cis''8 cis'' bis'4 d''8 cis''-~
- cis''2 r2
- @}
- \paper @{ @}
-@}
-@end example
+For more information on Relative octaves see @ref{Relative octaves},
+and @ref{Octave check}.
-@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 }
-}
-@end lilypond
-@end quotation
-@c accidentals...
-There are some interesting points to note in this example.
-Accidentals (sharps and flats) do not have to be marked explicitly:
-you just enter the note name, and an accidental is printed
-automatically, only when necessary. Bar lines and beams are drawn
-automatically. Line breaks are calculated automatically; it does not
-matter where the lines breaks are in the source file. Finally, the
-order of time, key and clef changes is not relevant: in the printout,
-these are ordered using standard notation conventions.
-
-The example also indicates that a piece of music written in a high
-register needs lots of quotes. This makes the input less readable,
-and is also a potential source of errors.
-
-The solution is to use ``relative octave'' mode. In practice, this is
-the most convenient way to copy existing music. To use relative mode,
-add @code{\relative} before the piece of music. You must also give a
-note from which relative starts, in this case @code{c''}. If you do
-not use octavation quotes (i.e. do not add ' or , after a note),
-relative mode chooses the note that is closest to the previous one.
-@c do not use commas or quotes in this sentence
-For example: @code{c f} goes up; @code{c g} goes down:
+@node Music expressions explained
+@section Music expressions explained
-@quotation
-@example
-\relative c'' @{
- c f c g c
-@}
-@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f c g c
-}
-@end lilypond
-@end quotation
-@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
+@lilypond[fragment,quote,verbatim,relative=3]
+a4
+@end lilypond
-Since most music has small intervals, in relative mode pieces can be
-written almost without using octavation quotes.
+Enclosing group of notes in braces creates a new music
+expression
-@c needed better, maybe even redundant explanation
-@c added another example below.
-@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
-@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-Larger intervals are made by adding octavation quotes. Quotes or
-commas do not determine the absolute height of a note; the height of a
-note is relative to the previous one.
-@c do not use commas or quotes in this sentence
-For example: @code{c f,} goes down; @code{f, f} are both the same;
-@code{c' c} are the same; and @code{c g'} goes up:
+@lilypond[fragment,quote,verbatim,relative=3]
+{ a4 g4 }
+@end lilypond
-@quotation
-@example
-\relative c'' @{
- c f, f c' c g' c,
-@}
-@end example
+Putting a bunch of music expressions (notes) in braces, means that
+they should be played in sequence. The result again is a music
+expression, which can be grouped with other expressions sequentially.
+Here, the expression from the previous example is combined with two
+notes
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative c'' {
- c f, f c' c g' c,
-}
+@lilypond[fragment,quote,verbatim,relative=3]
+{ { a4 g } f g }
@end lilypond
-@end quotation
-@separate
+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
-Here is an example of the difference between relative mode and
-``normal'' (non-relative) mode:
+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,
-@quotation
@example
-\relative a @{
-\clef bass
- a d a e d c' d'
-@}
+1
+
+1 + 2
+
+(1 + 2) * 3
+
+((1 + 2) * 3) / (4 * 5)
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\relative a {
-\clef bass
- a d a e d c' d'
+@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.
+
+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.}
+
+@lilypond[fragment,quote,verbatim,relative=2]
+{
+ c <<c e>>
+ << { e f } { c <<b d>> } >>
}
@end lilypond
-@end quotation
-@separate
-@quotation
+
+@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
-\clef bass
- a d a e d c' d'
+\book @{
+ \score @{
+ <<
+ @{
+ @dots{}
+ @}
+ @{
+ @dots{}
+ @}
+ \paper @{
+ @dots{}
+ @}
+ >>
+ @}
+@}
@end example
-@lilypond[fragment]
-\property Score.timing = ##f
-\property Staff.TimeSignature = \turnOff
-\clef bass
- a d a e d c' d'
-@end lilypond
-@end quotation
-@separate
+Some editors have special support for entering LilyPond, and can help
+indenting source files. See @ref{Editor support}, for more information.
-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:
+@node More staves
+@section More staves
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-d4-( c16-)-( cis d e c cis d e-)-( d4-)
+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
+
+@lilypond[quote,fragment,verbatim]
+<<
+ \new Staff { \clef violin c'' }
+ \new Staff { \clef bass c }
+>>
@end lilypond
-@end quotation
-@separate
-If you need two slurs at the same time (one for articulation, one for
-phrasing), you can also make a phrasing slur with @code{\(} and
-@code{\)}.
-@c lousy example
-@c ? --hwn
-@c fragment of 1st hrn in Adams' The Chairman Dances, with creative
-@c chromatic thing pasted in front. (admittedly the original does not
-@c have a phrasing slur. The problem is that we do not want the slur
-@c and the Phrasing slur to collide. We are trying to make a good
-@c impression here.
+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.
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
-@end lilypond
-@end quotation
-@separate
+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).
-Beams are drawn automatically, but if you do not like where they are
-put, they can be entered by hand. Mark the first note to be beamed
-with @code{[} and the last one with @code{]}:
-@quotation
-@lilypond[fragment,relative 1, verbatim]
-a8-[ ais-] d-[ es r d-]
+
+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.
+
+We can now typeset a melody with two staves
+
+@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
+
+@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
-@end quotation
-@separate
-@menu
-* Combining music into compound expressions::
-* Adding articulation marks to notes ::
-* More basic rhythms::
-* Commenting input files::
-@end menu
+For more information on context see the description in
+@ref{Interpretation contexts}.
-@node Combining music into compound expressions
-@subsection Combining music into compound expressions
-To print more than one staff, each piece of music that makes up a staff
-is marked by adding @code{\context Staff} before it. These
-@code{Staff}'s are then grouped inside @code{\simultaneous @{} and @code{@}}, as is
-demonstrated here:
-@quotation
-@lilypond[fragment,verbatim]
-\simultaneous {
- \context Staff = staffA { \clef violin c'' }
- \context Staff = staffB { \clef bass c }
-}
+@node Adding articulation marks to notes
+@section Adding articulation marks to notes
+
+@cindex articulation
+@cindex accents
+@cindex staccato
+
+Common accents can be added to a note using a dash (@samp{-}) and a
+single character
+
+@lilypond[fragment,quote,verbatim,relative=2]
+c-. c-- c-> c-^ c-+ c-_
@end lilypond
-@end quotation
-In this example, @code{staffA} and @code{staffB} are names that are
-given to the staves. It does not matter what names you give, as long
-as each staff has a different name. If you give them the same name,
-they are assumed to belong on the same staff, and will be printed like
-that. @code{\simultaneous } indicates that both fragments happen at
-the same time, and must be printed stacked vertically. The notation
-@code{< .. >} can also be used as a shorthand for @code{\simultaneous
-@{ .. @}}.
+@cindex fingering
+Similarly, fingering indications can be added to a note using a dash
+(@samp{-}) and the digit to be printed
-@separate
+@lilypond[fragment,quote,verbatim,relative=2]
+c-3 e-5 b-2 a-1
+@end lilypond
-We can now typeset a melody with two staves:
-@quotation
-@lilypond[verbatim,singleline]
-\score {
- \notes
- < \context Staff = staffA {
- \time 3/4
- \clef violin
- \relative c'' {
- e2-( d4 c2 b4 a8-[ a-]
- b-[ b-] g-[ g-] a2.-) }
- }
- \context Staff = staffB {
- \clef bass
- c2 e4 g2.
- f4 e d c2.
- }
- >
- \paper {}
-}
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
+
+@lilypond[fragment,quote,verbatim,relative=2]
+c\ff c\mf
@end lilypond
-@end quotation
-The example shows how small chunks of music, for example the notes
-@code{c2}, @code{e4}, etc. of the second staff, are combined to form a
-larger chunk by enclosing it in braces. Again, a larger chunk is
-formed by prefix @code{\context Staff} to it, and that chunk is
-combined with @code{< >}. This mechanism is similar with mathematical
-formulas: in a formula, a so-called expression is formed by combining
-simpler expressions into larger expressions. For example,
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
-@quotation
- 1
-
- 1 + 2
-
- (1 + 2) * 3
-
- ((1 + 2) * 3) / (4 * 5)
-@end quotation
-is a sequence of expressions, where each expression is contained in
-the next one. The simplest expressions are numbers and operators
-(like +, * and /). Parentheses are used to group expressions. In
-LilyPond input, a similar mechanism is used. Here, the simplest
-expressions are notes and rests. By enclosing expressions in @code{<
->} and @code{@{ @}}, more complex music is formed. The @code{\context}
-also forms new expressions; it is prepended to a music expression.
+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
-When spreading expressions over multiple lines, it is customary to use
-an indent that indicates the nesting level. Formatting music like this
-eases reading, and helps you insert the right amount of closing
-braces at the end of an expression. For example
-@example
-\score @{
- \notes <
- @{
- @dots{}
- @}
- @{
- @dots{}
- @}
- >
-@}
-@end example
+@lilypond[fragment,quote,verbatim,relative=2]
+c2\< c2\ff\> c2 c2\!
+@end lilypond
-@node Adding articulation marks to notes
-@subsection Adding articulation marks to notes
-Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
-@quotation
-@lilypond[verbatim,relative 1]
-c-. c-- c->
+
+@cindex slur
+
+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
+
+@lilypond[fragment,quote,fragment,relative=2,verbatim]
+d4( c16)( cis d e c cis d e)( d4)
@end lilypond
-@end quotation
-@separate
-Similarly, fingering indications can be added to a note using @code{-}
-and the digit to be printed.
-@lilypond[verbatim,relative 1]
- c-3 e-5 b-2 a-1
+@cindex slurs versus ties
+A slur looks like a tie, but it has a different meaning. A tie simply
+makes the first note sound longer, and can only be used on pairs of
+notes with the same pitch. Slurs indicate the articulations of notes,
+and can be used on larger groups of notes. Slurs and ties are also
+nested in practice
+
+@lilypond[quote,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
+@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.
-Dynamic signs are made by adding the markings to the note:
-@quotation
-@lilypond[verbatim,relative 1]
-c-\ff c-\mf
+@lilypond[quote,fragment,relative=2,verbatim]
+a8(\( ais b c) cis2 b'2 a4 cis, c\)
@end lilypond
-@end quotation
-@separate
-Crescendi and decrescendi are started with the commands @code{\<} and
-@code{\>}. The command @code{\!} finishes a crescendo on the note it
-is attached to.
+
+For more information on
+
@quotation
-@lilypond[verbatim,relative 1]
-c2-\< c2-\!-\ff c2-\> c2-\!
-@end lilypond
+@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
-@separate
-Chords can be made by
-surrounding pitches with @code{<<} and @code{>}>:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <<c e g>>4 <<c f a>>8
+
+@node Combining notes into chords
+@section Combining notes into chords
+
+@cindex chords
+Chords can be made by surrounding pitches with angle brackets.
+Angle brackets are the symbols @samp{<} and @samp{>}.
+
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>4 <c f a>8
@end lilypond
-@end quotation
-@separate
-You can combine beams and ties with chords. Beam and tie markings
-must be placed outside the chord markers:
-@quotation
-@lilypond[relative 0, fragment,verbatim]
-r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
+You can combine markings like beams and ties with chords. They must
+be placed outside the angled brackets
+
+@lilypond[quote,relative=1,fragment,verbatim]
+r4 <c e g>8[ <c f a>]~ <c f a>
@end lilypond
-@end quotation
-@quotation
@example
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
@end example
-@lilypond[relative 0, fragment]
+
+@lilypond[quote,relative=1,fragment]
\slurUp
-r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
+r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
@end lilypond
-@end quotation
-@separate
-@node More basic rhythms
-@subsection More basic rhythms
-A pickup (or upstep) is entered with the keyword @code{\partial}. It
+
+@node Basic rhythmical commands
+@section Basic rhythmical commands
+
+@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.
-@lilypond[relative 1,verbatim,fragment]
- \partial 8
- f8 c2 d e
+and @code{\partial 8} an eighth note
+
+@lilypond[quote,relative=2,verbatim,fragment]
+\partial 8
+f8 c2 d e
@end lilypond
+@cindex tuplets
+@cindex triplets
Tuplets are made with the @code{\times} keyword. It takes two
arguments: a fraction and a piece of music. The duration of the piece
of music is multiplied by the fraction. Triplets make notes occupy
-2/3 of their notated duration, so a triplet has 2/3 as its fraction.
-@c
-@lilypond[relative 0,verbatim,fragment]
- \times 2/3 { f8 g a }
- \times 2/3 { c r c }
-@end lilypond
-
-Grace notes are also made by prefixing a note, or a set of notes with
-a keyword. In this case, the keyword is @code{\grace}.
-@lilypond[relative 1, verbatim,fragment]
- c4 \grace b16-( c4-)
- \grace { d16-( e } d4-)
+2/3 of their notated duration, so a triplet has 2/3 as its fraction
+
+@lilypond[quote,relative=1,verbatim,fragment]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+@end lilypond
+
+@cindex grace notes
+@cindex accacciatura
+Grace notes are also made by prefixing a music expression with the
+keyword @code{\appoggiatura} or @code{\acciaccatura}
+@cindex appoggiatura
+@cindex acciaccatura
+
+@lilypond[quote,relative=2,verbatim,fragment]
+c4 \appoggiatura b16 c4
+c4 \acciaccatura b16 c4
@end lilypond
@noindent
-More information on the use of grace notes is in @ref{Grace notes}.
+For more information on
-@node Commenting input files
-@subsection Commenting input files
+@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
-Comments are pieces of the input that are ignored. There are two
-types of comments. A line comments are introduced by @code{%}: after
-that, the rest of that line is ignored. Block comments span larger
-sections of input. Anything that is enclosed in @code{%@{} and
-@code{%@}} is ignored too. The following fragment shows possible uses
-for comments.
+
+@node Commenting input files
+@section Commenting input files
+
+@cindex comments
+@cindex line comment
+@cindex block comment
+A comment is a remark for the human reader of the music input; it is
+ignored and has no effect on the printed output. There are two types
+of comments. The percent symbol @samp{%} introduces a line comment;
+the rest of the line is ignored. A block comments marks a whole
+section of music input---anything that is enclosed in @code{%@{} and
+@code{%@}} is ignored. The following fragment shows possible uses for
+comments
@example
- % notes for twinkle twinkle follow:
- c4 c g' g a a
-
- %@{
-
+% notes for twinkle twinkle follow
+c4 c g' g a a
+
+%@{
This line, and the notes below
are ignored, since they are in a
block comment.
g g f f e e d d c2
- %@}
+%@}
@end 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
+@example
+\version "2.1.17"
+@end example
+
+@noindent
+These annotations make future upgrades of LilyPond go more
+smoothly. Changes in the syntax are handled with a special program,
+@file{convert-ly} (see @ref{Invoking convert-ly}), and it uses
+@code{\version} to determine what rules to apply.
@node Printing lyrics
@section Printing lyrics
@cindex lyrics
-Lyrics are entered by separating each syllable with a space, and
-surrounding them with @code{\lyrics @{ @dots{} @}}, for example
-@example
- \lyrics @{ I want to break free @}
-@end example
+@c TODO: (c) status of the Queen fragment.
+
+@cindex Lyrics
+@cindex Songs
+Lyrics are entered by separating each syllable with a space
-Like notes, lyrics are also a form of music, but they must not be
-printed on a staff, which is the default way to print music. To print
-them as lyrics, they must be marked with @code{ \context Lyrics}:
@example
- \context Lyrics \lyrics @{ I want to break free @}
+I want to break free
@end example
-The melody for this song is as follows
-@lilypond[fragment,relative=1]
- \partial 8
- c8
- \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
+Consider the melody
+
+@lilypond[quote,verbatim,fragment,raggedright]
+\relative {
+ r4 c \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+}
@end lilypond
+@c FIXME: when/how/to what rename newlyrics?
The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword:
-@example
- \addlyrics
- \notes @{ @dots{} @}
- \context Lyrics @dots{}
-@end example
+@code{\newlyrics} keyword
-The final result is
-@lilypond[verbatim,linewidth=6.0cm]
-\score {
- \notes {
- \addlyrics
- \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
- }
- \context Lyrics \lyrics { I want to break free }
- }
- \paper{ }
-}
+@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
-This melody ends on a @rglos{melisma}, a single syllable (``free'')
-sung to more than one note. This is indicated with a @emph{extender
-line}. It is entered as two underscores, i.e.,
+@cindex melisma
+@cindex extender line
+@c synonyms?
+This melody ends on a @rglos{melisma}, a single syllable (`free')
+sung to more than one note. This is indicated with an @emph{extender
+line}. It is entered as two underscores, i.e.,
+
@example
- \lyrics @{ I want to break free __ @}
+@{ I want to break free __ @}
@end example
-@lilypond[]
-\score {
- \notes {
- \addlyrics
- \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
-
- %% ugh, this is to deal with bugs in the extender implementation
- \hideNotes
- c8
- }
- \context Lyrics \lyrics { I want to break free __ }
- }
- \paper{ linewidth = 9.0 \cm }
-}
+
+@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
Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables.
+resulting in a centered hyphen between two syllables
+
@example
- Twin -- kle twin -- kle
+Twin -- kle twin -- kle
@end example
-@lilypond[singleline]
-\score {
- \addlyrics \notes \relative f' { \time 2/4
- f4 f c' c' }
- \context Lyrics \lyrics { Twin -- kle twin -- kle
- }
-\paper { linewidth = 6.0 \cm }
- }
-
+
+@lilypond[fragment,quote,raggedright]
+<<
+ \relative {
+ \time 2/4
+ f4 f c' c
+ }
+ \newlyrics { Twin -- kle twin -- kle }
+>>
@end lilypond
More options, like putting multiple lines of lyrics below a melody are
discussed in @ref{Vocal music}.
+@c FIXME: too geeky, for notation manual?
+@c or introduce using foo = \lyrics { a b c } ?
+When using variables for a piece of lyrics
+To prevent certain words (for example `as') as being read as a
+pitch, the input-mode must be switched. This is done with
+@code{\lyrics}. In @code{\lyrics} mode, all words are read as lyric
+syllables.
-TODO: discuss contexts.
+@example
+myText = \lyrics @{ I want to break free @}
+@end example
+
+@noindent
+The braces @code{@{@}} signify that the syllables are sung in
+sequence.
+
+@ignore
+By default, music expressions are interpreted in @code{Staff} context. For
+lyrics, this is obviously not desirable, so it is necessary
+to explicitly specify a @code{Lyrics} context,
+
+@example
+\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
+
+@end ignore
@node A lead sheet
@section A lead sheet
-In popular music, it is common to denote accompaniment as chord-names.
-Using them in LilyPond has two parts, just like lyrics: entering the
-chords (with @code{\chords}), and printing them (with @code{\context
-ChordNames}).
+@cindex Lead sheets
+@cindex chords
+@cindex chord names
-Chord names are entered by starting chords mode (with @code{\chords}).
-In chords mode, you can enter chords with a letter (indicating the
-root of the chord), and a durations following that.
-@c
-@lilypond[verbatim]
- \chords { c2 f4. g8 }
-@end lilypond
+In popular music, it is common to denote accompaniment as chord names.
+Such chords can be entered like notes,
+
+@example
+c2 f4. g8
+@end example
@noindent
-The result of @code{\chords} is a list of chords, and is equivalent
-to entering chords with @code{<<@dots{}>>}.
+but now, each pitch is read as the root of a chord instead of a note.
+This mode is switched on with @code{\chords}
-Other chords can be created by adding modifiers, after a colon. The
-following example shows a few common modifiers
-@c
-@lilypond[verbatim]
- \chords { c2 f4:m g4:maj7 gis1:dim7 }
+@lilypond[quote,verbatim,raggedright]
+\chords { c2 f4. g8 }
@end lilypond
-Printing chords is done by adding @code{\context ChordNames}
-before the chords thus entered:
-@c
-@lilypond[verbatim]
- \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+Other chords can be created by adding modifiers after a colon. The
+following example shows a few common modifiers
+
+@lilypond[quote,verbatim]
+\chords { c2 f4:m g4:maj7 gis1:dim7 }
@end lilypond
-A complete list of modifiers, and other options for layout are in the
-reference manual section @ref{Chords}.
+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
+
+@lilypond[quote,verbatim]
+\new ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+@end lilypond
-@cindex lead sheet
-When put together, chord names, lyrics and a melody form
+@cindex lead sheet
+When put together, chord names, lyrics and a melody form
a lead sheet, for example,
@example
-\score @{
- <
- \context ChordNames \chords @{ @emph{chords} @}
- \addlyrics
- \notes @emph{the melody}
- \context Lyrics \lyrics @{ @emph{the text} @}
- >
- \paper @{ @}
+<<
+ \new ChordNames \chords @{ @emph{chords} @}
+ @emph{the melody}
+ \newlyrics @{ @emph{the text} @}
+>>
@}
@end example
-@lilypond[]
-\score {
- <
- \context ChordNames \chords { r8 c2:sus4 f }
- \addlyrics
- \notes \relative c' {
- \partial 8
- c8
- \times 2/3 { f g g } \times 2/3 { g4-( a2-) } }
- \context Lyrics \lyrics { I want to break free __ }
- >
- \paper{ raggedright = ##t }
-}
+
+@lilypond[quote,raggedright]
+<<
+ \new ChordNames \chords { r2 c:sus4 f }
+ \notes \relative {
+ r4 c' \times 2/3 { f g g }
+ \times 2/3 { g4( a2) }
+ }
+ \newlyrics { I want to break free __ }
+>>
@end lilypond
+A complete list of modifiers and other options for layout can be found
+in @ref{Chords}.
+@c FIXME: we talk about \midi before mentioning \paper (or \layout?)
@node Listening to output
@section Listening to output
+@cindex sound
+@cindex MIDI
+
MIDI (Musical Instrument Digital Interface) is a standard for
-connecting and recording digital instruments. A MIDI file is like a
-tape recording of a MIDI instrument. The @code{\midi} block makes the
-music go to a MIDI file, so you can listen to the music you entered.
-It is great for checking the music: octaves that are off, or
-accidentals that were mistyped, stand out very much when listening to
-the musical transcription.
-
-@code{\midi} can be used in similarly to @code{\paper @{ @}}, for
-example
+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,
+
@example
\score @{
- @var{..music..}
- \midi @{ \tempo 4=72 @}
- \paper @{ @}
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
@}
@end example
Here, the tempo is specified using the @code{\tempo} command. In this
-case the tempo of quarter notes is set to 72 beats per minute. More
-information on auditory output is in the @ref{Sound} section in the
-notation manual.
+case the tempo of quarter notes is set to 72 beats per minute. More
+information on auditory output in the notation manual can be found in
+@ref{Sound}.
+
+If there is a @code{\midi} command in a @code{\score}, only MIDI will
+be produced. If notation is needed too, a @code{\paper} block must be
+added
+
+@example
+\score @{
+ @var{...music...}
+ \midi @{ \tempo 4=72 @}
+ \paper @{ @}
+@}
+@end example
+@cindex paper block
-@node Titling
-@section Titling
+@node Adding titles
+@section Adding titles
Bibliographic information is entered in a separate block, the
-@code{\header} block. The name of the piece, its composer, etc. are
-entered as assignment within @code{\header @{ @dots{} @}}. For
-example,
+@code{\header} block. The name of the piece, its composer, etc., are
+entered as an assignment, within @code{\header
+@{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at
+the top of the file. For example,
+
@example
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- tagline = "small is beautiful"
- @}
-
- \score @{ @dots{} @}
+\header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+@}
+
+@{ @dots{} @}
@end example
@cindex bibliographic information
@cindex titles
@cindex composer
-@cindex ly2dvi
+@cindex Engraved by LilyPond
+
+When the file is processed the title and composer are printed above
+the music. The `tagline' is a short line printed at bottom of the last
+page which normally says `Engraved by LilyPond, version @dots{}'. In
+the example above it is replaced by the line `small is
+beautiful.'@footnote{Nicely printed parts are good PR for us, so
+please leave the tagline if you can.}
+
+The @code{\header} block is usually put at the top of the file.
-When the file is processed by @code{ly2dvi}, the title and composer
-specified are printed above the music. The `tagline' is a short line
-printed at bottom of the last page, which normally says ``Lily was
-here, version @dots{}''. In the example above, it is replaced by the
-line ``small is beautiful.''
+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.
-Normally, the @code{\header} is put at the top of the file. However,
-for a document that contains multiple pieces (e.g. a etude book, or
-part with multiple movements), then the header can be put into the
-@code{\score} block as follows In this case, the name of each piece
-will be printed before each movement.
+The header for each piece of music can be put inside the @code{\score}
+block. The @code{piece} name from the header will be printed before
+each movement.
+@ignore
-@cindex Lily was here
+FIXME: introduce \BOOK
+
+FIXME: Using "Adagio" as a name is confusing, it's more common to be
+a plain tempo indication.
+
+Since today (CVS-1.211) we also allow headers and composite music
+inside book:
+
+ \header { ... }
+ \book {
+ \header { ... }
+ { ... }
+ \header { ... }
+ { ... }
+ }
+
+@end ignore
+
+@cindex Engraved by LilyPond
@cindex signature line
@cindex tag line
@example
- \header @{
- title = "Eight miniatures"
- composer = "Igor Stravinsky"
- tagline = "small is beautiful"
- @}
-
- \score @{ @dots{}
+\header @{
+ title = "Eight miniatures"
+ composer = "Igor Stravinsky"
+ tagline = "small is beautiful"
+@}
+
+\book @{
+ \score @{
+ @dots{}
\header @{ piece = "Adagio" @}
@}
- \score @{ @dots{}
+ \score @{
+ @dots{}
\header @{ piece = "Menuetto" @}
@}
+@}
@end example
-More information on titling can be found in @ref{Invoking ly2dvi}.
+More information on titling can be found in @ref{Invoking lilypond}.
-@node Single staff polyphony
+@node Single staff polyphony
@section Single staff polyphony
-When different melodic lines are combined on a single staff, these are
-printed as polyphonic voices: each voice has its own stems, slurs
-and beams, and the top voice has the stems up, while the bottom voice
-has stems down.
+@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.
Entering such parts is done by entering each voice as a sequence (with
-@code{@{ .. @}}), and combing those simultaneously, separating the
-voices with @code{\\}:
+@code{@{...@}}), and combining those simultaneously, separating the
+voices with @code{\\}
-@example
- < @{ a4 g2 f4-~ f4 @} \\
- @{ r4 g4 f2 f4 @} >
-@end example
-@lilypond[relative 1]
-\context Staff < { a4 g2 f4-~ f4 } \\
- { r4 g4 f2 f4 } >
+@lilypond[quote,verbatim,relative=3]
+<< { a4 g2 f4~ f4 } \\
+ { r4 g4 f2 f4 } >>
@end lilypond
-For polyphonic typesetting spacer rests can also be convenient: these
+For polyphonic music typesetting, spacer rests can also be convenient; these
are rests that do not print. It is useful for filling up voices that
-temporarily do not play:
-@example
- < @{ a4 g2 f4-~ f4 @} \\
- @{ s4 g4 f2 f4 @} >
-@end example
-@lilypond[relative 1]
-\context Staff < { a4 g2 f4-~ f4 } \\
- { s4 g4 f2 f4 } >
-@end lilypond
-
-More features of polyphonic typesetting are in the notation manual
-in @ref{Polyphony}.
-
-@node Piano staffs
-@section Piano staffs
-
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-@cindex @code{\translator}
-
-Piano music is always typeset in two staffs connected by a brace.
-Printing such a staff is done similar to the polyphonic example in
-@ref{More basics}:
-@example
- < \context Staff = up @{ @dots{} @}
- \context Staff = down @{ @dots{} @}
- >
-@end example
-but now this entire expression must be interpreted as a
-@code{PianoStaff}:
-@example
- \context PianoStaff < \context Staff @dots{} >
-@end example
-
-Here is a full-fledged example:
+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}
-@lilypond[relative 0,fragment]
-\context PianoStaff
- < \context Staff = up {
- c4 c g' g }
- \context Staff = down {
- \clef bass c, c' e c }
- >
+@lilypond[quote,verbatim,relative=3]
+<< { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 } >>
@end lilypond
-More information on formatting piano music is in @ref{Piano music}.
-
-@node Setting variables
-@section Setting variables
-
-When the music is converted from notes to print, it is interpreted
-from left-to-right order, similar to what happens when we read
-music. During this step, context-sensitive information, such as the
-accidentals to print, and where barlines must be placed, are stored in
-variables. These variables are called @emph{translation properties}.
-The properties can also be manipulated from input files: for example,
-@example
-\property Staff.autoBeaming = ##f
-@end example
-sets the property named @code{autoBeaming} in the current staff to
-@code{##f} which means `false'. This property controls whether beams
-are printed automatically:
-@lilypond[relative 1,fragment,verbatim]
- c8 c c c
- \property Staff.autoBeaming = ##f
- c8 c c c
+@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
-@noindent
-LilyPond includes a built-in programming language, namely, a dialect
-of Scheme. The argument to @code{\property}, @code{##f}, is an
-expression in that language. The first hash-mark signals that a piece
-of Scheme code follows. The second hash character is part of the
-boolean value true (@code{#t}). Values of other types may be
-entered as follows
-@itemize @bullet
-@item a string, enclosed in double quotes, for example
-@example
- \property Staff.instrument = #"French Horn"
-@end example
-@item a boolean: either @code{#t} or @code{#f}, for true and false
-respectively, e.g.
-@example
- \property Voice.autoBeaming = ##f
- \property Score.skipBars = ##t
-@end example
+More features of polyphonic typesetting in the notation manual are
+described in @ref{Polyphony}.
-@item a number
-@example
- \property Score.currentBarNumber = #20
-@end example
-@item a symbol, which is introduced by a quote character,
-@example
- \property Staff.crescendoSpanner = #'dashed-line
-@end example
+@node Piano staves
+@section Piano staves
-@item a pair, which is also introduced by a quote character.
-The following statements set properties to the pairs (-7.5, 6) and
-(3, 4) respectively.
+@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},
@example
- \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
- \property Staff.timeSignatureFraction = #'(3 . 4)
+<< \new Staff @{ @dots{} @}
+ \new Staff @{ @dots{} @} >>
@end example
-
-@end itemize
-
-There are many different properties, and not all of them are listed in
-this manual. However, the internal documentation lists them all in the
-@internalsref{All translation properties}, and almost all properties
-are demonstrated in one of the
-@ifhtml
-@uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
-@end ifhtml
-@ifnothtml
-tips-and-tricks
-@end ifnothtml
-examples.
-
-
-@node Fine tuning layout
-@section Fine tuning layout
-
-Sometimes it is necessary to change music layout by hand. When music
-is formatted, layout objects are created for each symbol. For
-example, every clef and every note head is represented by a layout
-object. These layout objects also carry variables, which we call
-@emph{layout properties}. By changing these variables from their
-values, we can alter the look of a formatted score.
-
-@lilypond[verbatim,relative 0]
- c4
- \property Voice.Stem \override #'thickness = #3.0
- c4 c4 c4
-@end lilypond
-
@noindent
-In the example shown here, the layout property @code{thickness} (a
-symbol) is set to 3 in the @code{Stem} layout objects of the current
-Voice. As a result, the notes following @code{\property} have thicker
-stems.
-
-In most cases of manual overrides, only a single object must be
-changed. This can be achieved by prefix @code{\once} to the
-@code{\property} statement, i.e.,
+but now this entire expression must be interpreted as a
+@code{PianoStaff}
@example
- \once \property Voice.Stem \set #'thickness = #3.0
+\new PianoStaff << \new Staff @dots{} >>
@end example
-@lilypond[relative 0]
- c4
- \once \property Voice.Stem \set #'thickness = #3.0
- c4 c4 c4
-@end lilypond
+Here is a full-fledged example
-@noindent
-Some overrides are so common that predefined commands are provided as
-a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in the @ref{Notation manual}, under the
-sections for slurs and stems respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the internal documentation of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a couple of these:
-
-@itemize @bullet
-@cindex @code{extra-offset}
-@item The @code{extra-offset} property
-moves around objects in the printout. The unit of these offsets are
-staff-spaces. The first number controls left-right movement; a
-positive number will move the object to the right. The second number
-controls up-down movement; a positive number will move it higher. The
-@code{extra-offset} is a low-level feature: the formatting engine is
-completely oblivious to these offsets.
-
-In the following example example, the second fingering is moved a
-little to the left, and 1.8 staff space downwards.
-
-@cindex setting object properties
-
-@lilypond[relative 1,verbatim]
-\stemUp
-f-5
-\once \property Voice.Fingering
- \set #'extra-offset = #'(-0.3 . -1.8)
-f-5
-@end lilypond
-
-@item
-Setting the @code{transparent} property will make an object be
-printed in `invisible ink': the object is not printed, but all its
-other behavior is retained. The object still takes space, takes part
-in collisions, and slurs, ties and beams can be attached to it.
-
-@cindex transparent objects
-@cindex removing objects
-@cindex invisible objects
-The following example demonstrates how to connect different voices
-using ties. Normally ties only happen between notes of the same
-voice. By introducing a tie in a different voice, and blanking a stem
-in that voice, the tie appears to cross voices.
-
-@lilypond[fragment,relative 1]
-\context Staff < {
- \once \property Voice.Stem \set #'transparent = ##t
- b8~ b8
- } \\ {
- b-[ g8-]
- } >
+@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
-@item
-The @code{padding} property for objects with
-@code{side-position-interface} can be set to increase distance between
-symbols that are printed above or below notes. An example of the use
-of padding is in @ref{Constructing a tweak}.
-@end itemize
+More information on formatting piano music is in @ref{Piano music}.
-More specific overrides are also possible. The notation manual
-discusses in depth how to figure out these statements for yourself, in
-@ref{Tuning output}.
@node Organizing larger pieces
@section Organizing larger pieces
When all of the elements discussed earlier are combined to produce
larger files, the @code{\score} blocks get a lot bigger, because the
-music expressions are longer, and, in the case of polyphonic and/or
-orchestral pieces, more deeply nested.
+music expressions are longer, and, in the case of polyphonic pieces,
+more deeply nested. Such large expressions can become unwieldy.
By using variables, also known as identifiers, it is possible to break
-up complex music expressions.
-An identifier is assigned as follows
+up complex music expressions. An identifier is assigned as follows
+
@example
- namedMusic = \notes @{ @dots{}
+namedMusic = \notes @{ @dots{} @}
@end example
+@noindent
The contents of the music expression @code{namedMusic}, can be used
-later by preceding the name with a backslash, i.e. @code{\namedMusic}.
-For example
+later by preceding the name with a backslash, i.e., @code{\namedMusic}.
+In the next example, a two-note motive is repeated two times by using
+variable substitution
-@lilypond[singleline,verbatim]
-seufzer = \notes {
- dis'8 e'8
+@lilypond[quote,raggedright,verbatim,nofragment]
+seufzer = \notes {
+ e'4( dis'4)
}
-\score { \notes {
- \seufzer \seufzer
-} }
+{ \seufzer \seufzer }
@end lilypond
-The name of an identifier should only have alphabetic characters only,
-and no numbers, underscores or dashes. The assignment should be
-outside of the @code{\score} block.
+The name of an identifier should have alphabetic characters only;
+no numbers, underscores or dashes. The assignment should be outside of
+the @code{\score} block.
It is possible to use variables for many other types of objects in the
input. For example,
+
@example
- width = 1.5\cm
- name = "Wendy"
- aFivePaper = \paper @{ paperheight = 22.7 \cm @}
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
@end example
+
Depending on its contents, the identifier can be used in different
-places. The following example uses the above variables:
+places. The following example uses the above variables
+
@example
- \score @{
- \notes @{ c4^\name @}
- \paper @{
- \aFivePaper
- linewidth = \width
- @}
+\score @{
+ \notes @{ c4^\name @}
+ \paper @{
+ \aFivePaper
+ linewidth = \width
@}
+@}
@end example
More information on the possible uses of identifiers is in the
-technical manual, in @ref{Scheme datatypes}.
+technical manual, in TODO.
@node An orchestral part
@section An orchestral part
-In orchestral music, all notes are printed twice: both in a part for
-the musicians, and in a full score for the which is printed both in
-parts as in full score. Identifiers can be used to avoid double work:
-the music is entered once, and stored in an variables. The contents of
-that variable is then used to generate both the part and the score.
+In orchestral music, all notes are printed twice; in a part for
+the musicians, and in a full score for the conductor. Identifiers can
+be used to avoid double work. The music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the score.
+
+It is convenient to define the notes in a special file. For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/bassoon duo
-It is convenient to define the notes in a special file, for example,
-suppose that the following is in @file{horn-music.ly}:
@example
hornNotes = \notes \relative c @{
\time 2/4
@}
@end example
+@noindent
Then, an individual part is made by putting the following in a file
+
@example
\include "horn-music.ly"
\header @{
instrument = "Horn in F"
@}
\score @{
- \notes \transpose c' f \hornNotes
+ \notes \transpose f c' \hornNotes
@}
@end example
-The @code{\include} command substitutes the contents of the file at
-this position in the file, so that @code{hornNotes} is defined
-afterwards. Since the horn is tuned in F, the @code{\transpose}
-command is used. The code @code{\transpose c' f} indicates that the
-argument, being @code{\hornNotes} should be transposed by a fifth
-downwards: the @code{c'} becomes a @code{f}. The transposition can be
-seen in the following output:
-
-@lilypond[singleline]
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth downwards. Sounding
+@samp{f} is denoted by notated @code{c'}, which corresponds with
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,raggedright]
\score {
- \notes \transpose c' f \notes \relative c' {
- \time 2/4
- r4 f8 a cis4 f e d
-}
+ \notes \transpose f c' \notes \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+ }
}
@end lilypond
In ensemble pieces, one of the voices often does not play for many
-measures. This is denoted by a special rest, the multi-measure
-rest. It is entered with a capital R, and followed by a duration (1
-for a whole note, 2 for a half note, etc.) By multiplying the
-duration, longer rests can be constructed. For example, the next rest
-takes 3 measures in 2/4 time.
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital @samp{R} followed by a duration
+(1@tie{}for a whole note, 2@tie{}for a half note, etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
@example
- R2*3
+R2*3
@end example
-When printing the part, the following @code{skipBars} property must be
-set to false, to prevent the rest from being expanded in three one bar
-rests.
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
@example
- \property Score.skipBars = ##t
+\set Score.skipBars = ##t
@end example
-The result would look like
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
-@lilypond[singleline]
-\score {\notes { \transpose c' f \relative c' { \time 2/4
-\property Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e d } }}
+@lilypond[quote,raggedright]
+\score {
+ \notes \transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+ }
+}
@end lilypond
-The score is made by combining all of the music in a @code{\score}
-block, assuming that the other voice is in @code{hornNotes}, in the
-file @file{horn-music.ly}:
+
+The score is made by combining all of the music in a @code{\score}
+block. Assuming that the other voice is in @code{bassoonNotes} in the
+file @file{bassoon-music.ly}, a score is made with
+
@example
-\include "fagot-music.ly"
+\include "bassoon-music.ly"
\include "horn-music.ly"
\score @{
\simultaneous @{
- \context Staff = hornStaff \hornNotes
- \context Staff = fagStaff \fagottoNotes
- @} @}
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+ @}
+@}
@end example
-This would lead to the following output:
+@noindent
+leading to
-@lilypond[singleline]
+@lilypond[quote,raggedright]
\score {
\notes \relative c \simultaneous {
- \context Staff = hornStaff { \time 2/4
- R2*3
- r4 f8 a cis4 f e d }
- \context Staff = fagStaff { \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f }
- } }
-@end lilypond
+ \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 is in the notation manual, in
-@ref{Orchestral music}.
+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
-TODO: shorten.
-
@cindex La@TeX{}, music in
@cindex HTML, music in
@cindex Texinfo, music in
-
-Sometimes you might want to use music examples in a text that you are
-writing (for example a musicological treatise, a songbook, or (like us)
-the LilyPond manual). You can make such texts by hand, simply by
-importing a PostScript figure into your word processor. However,
-there is an automated procedure to reduce the amount of work.
-
-If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
-code. A script called @code{lilypond-book} will extract the music
-fragments, run LilyPond on them, and put back the resulting notation.
-This program is fully described in @ref{lilypond-book manual}. Here
-we show a small example. Since the example also contains explanatory
-text, we will not comment it further.
+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.
+
+A script called @code{lilypond-book} will extract the music fragments,
+run format them, and put back the resulting notation. This program is
+fully described in @ref{lilypond-book manual}. Here we show a small
+example. The example also contains explanatory text, so we will not
+comment on it further
@example
\documentclass[a4paper]@{article@}
\begin@{document@}
-In a lilypond-book document, you can freely mix music and text. For
-example:
+Documents for lilypond-book may freely mix music and text. For
+example,
+
\begin@{lilypond@}
\score @{ \notes \relative c' @{
c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
@} @}
\end@{lilypond@}
-Notice that the music line length matches the margin settings of the
-document.
+If there is no \verb+\score+ block in the fragment,
+\texttt@{lilypond-book@} will supply one
-If you have no \verb+\score+ block in the fragment,
-\texttt@{lilypond-book@} will supply one:
-
-\begin@{lilypond@}
+\begin[quote]@{lilypond@}
c'4
\end@{lilypond@}
-In the example you see here, two things happened: a
+\noindent
+In this example two things happened. A
\verb+\score+ block was added, and the line width was set to natural
-length. You can specify many more options using \LaTeX style options
-in brackets:
+length.
-\begin[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]@{lilypond@}
- c'4 f bes es
-\end@{lilypond@}
-
-The option \texttt@{verbatim@} prints the LilyPond code in addition to
-the graphical score, \texttt@{11pt@} selects the default music size,
-\texttt@{fragment@} adds a score block, \texttt@{relative@} uses
-relative mode for the fragment, and \texttt@{intertext@} specifies
-what to print between the \texttt@{verbatim@} code and the music.
+Options are put in brackets.
-If you want to include large examples into the text, it may be more
-convenient to put the example in a separate file:
+\begin[quote,staffsize=26,verbatim]@{lilypond@}
+ c'4 f16
+\end@{lilypond@}
-\lilypondfile[printfilename]@{screech-boink.ly@}
+Larger examples can be put in a separate file, and introduced with
+\verb+\lilypondfile+.
-The \texttt@{printfilename@} option adds the file name to the output.
+\lilypondfile[quote,noindent]@{screech-boink.ly@}
\end@{document@}
@end example
-Under Unix, you can view the results as follows.
+Under Unix, you can view the results as follows
+
@example
$ cd input/tutorial
$ mkdir -p out/
-$ lilypond-book --outdir=out/ lilbook.tex
-lilypond-book (GNU LilyPond) 1.7.23
-Reading `input/tutorial/lilbook.tex'
-Reading `input/screech-boink6.ly'
+$ lilypond-book --output=out/ lilybook.tex
+lilypond-book (GNU LilyPond) 2.1.19
+Reading `input/tutorial/lilybook.tex'
+Reading `input/screech-boink.ly'
@var{lots of stuff deleted}
-Writing `out/lilbook.latex'
+Writing `out/lilybook.tex'
$ cd out
-$ latex lilbook.latex
+$ latex lilybook
@var{lots of stuff deleted}
-$ xdvi lilbook
+$ xdvi lilybook
@end example
-Running lilypond-book and running latex creates a lot of temporary
-files, and you would not want those to clutter up your working
-directory. The @code{outdir} option to lilypond-book creates the
-temporary files in a separate subdirectory @file{out}.
+To convert the file into a nice PDF document, run the following
+commands
-The result looks more or less like this:
+@example
+$ dvips -Ppdf -u +lilypond lilybook
+$ ps2pdf lilybook.ps
+@end example
-@separate
+Running lilypond-book and running latex creates a lot of temporary
+files, which would clutter up the working directory. To remedy this,
+use the @code{--output=@var{dir}} option. It will create the files in
+a separate subdirectory @file{dir}.
-In a lilypond-book document, you can freely mix music and text. For
-example:
-@lilypond
-\score {
- \notes \relative c' {
- c2 g'2 \times 2/3 { f8 e d } c'2 g4
- }
- \paper {
- raggedright = ##t
- }
-}
-@end lilypond
+Finally the result of the La@TeX{} example shown above.@footnote{Note
+that in this tutorial the example is processed with Texinfo. This gives
+slightly different results in layout.} This finishes the tutorial
+section.
-Notice that the music line length matches the margin settings of the
-document.
+@page
-If you have no @code{\score} block in the fragment,
-@code{lilypond-book} will supply one:
+Documents for lilypond-book may freely mix music and text. For
+example,
@lilypond
- c'4
+\score { \notes \relative c' {
+ c2 g'2 \times 2/3 { f8 e d } c'2 g4
+} }
@end lilypond
-In the example you see here, a number of things happened: a
-@code{\score} block was added, and the line width was set to natural
-length. You can specify many more options using La@TeX{} style options
-in brackets:
+If there is no @code{\score} block in the fragment,
+@code{lilypond-book} will supply one
-@lilypond[verbatim,11pt,singleline,
- fragment,relative,intertext="hi there!"]
- c'4 f bes es
+@lilypond[fragment,quote]
+c'4
@end lilypond
-The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
-the default music size, @code{fragment} adds a score block,
-@code{relative} uses relative mode for the fragment, and
-@code{intertext} specifies what to print between the
-@code{verbatim} code and the music.
+@noindent
+In this example two things happened. A
+@code{score} block was added, and the line width was set to natural
+length.
-If you include large examples into the text, it may be more convenient
-to put the example in a separate file:
+Options are put in brackets.
-@lilypondfile[printfilename]{screech-boink.ly}
+@lilypond[fragment,quote,staffsize=26,verbatim]
+c'4 f16
+@end lilypond
-The @code{printfilename} option adds the file name to the output.
+Larger examples can be put in a separate file, and introduced with
+@code{\lilypondfile}.
+@lilypondfile[quote,noindent]{screech-boink.ly}
projects / lilypond.git / blobdiff