LilyPond input that was used to generate that image.
Try it on this image
-@lilypond[fragment,quote,ragged-right,relative=2]
-c-\markup { \bold \huge { Click here. } }
+@c no verbatim here
+@lilypond[quote,ragged-right]
+\relative c'' {
+ c-\markup { \bold \huge { Click here. } }
+}
@end lilypond
-By cutting and pasting everything from the @qq{Start cut-&-pastable-section}
-to the end of the file, you have a
+By cutting and pasting everything in the @qq{ly snippet} section, you have a
starting template for experiments. If you like learning in this way,
you will probably want to print out or bookmark the
@ref{Cheat sheet}, which is a table listing of the most common
@menu
* First steps::
-* Notation for one note at once FIXME name::
+* Single staff notation::
* Multiple notes at once::
* Songs::
* Final touches::
-* FIXME merge with chapter 3::
@end menu
@noindent
the result looks like this
+@c in this case we don't want verbatim
@lilypond[quote,ragged-right]
{
c' e' g' e'
@end lilypond
@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
-braces @}} placed around the input. The braces should be also be
+braces @}} placed around the input. The braces should also be
surrounded by a space unless they are at the beginning or end of a
line to avoid ambiguities. These may be omitted in some examples in this
manual, but don't forget them in your own music!
@cindex Case sensitive
-In addition, LilyPond input is @strong{case sensitive}. @code{ @{ c d e @} }
-is valid input; @code{ @{ C D E @} } will produce an error message.
+In addition, LilyPond input is @strong{case sensitive}. @code{ @{c d e @}}
+is valid input; @code{@{ C D E @}} will produce an error message.
@sp 1
@subsubheading MacOS X
-If you double click LilyPond.app, it will open with an example
-file. Save it, for example, to @file{test.ly} on your Desktop, and
+If you double click @code{LilyPond.app}, it will open with an example
+file. Save it, for example, to @file{test.ly} on your Desktop, and
then process it with the menu command @samp{Compile > Typeset File}.
The resulting PDF file will be displayed on your screen.
-Be warned that the first time you ever run lilypond will take a minute
+Be warned that the first time you ever run LilyPond, it will take a minute
or two because all of the system fonts have to be analyzed first.
-For future use of LilyPond, you should begin by selecting "New"
-or "Open".
+For future use of LilyPond, you should begin by selecting @q{New}
+or @q{Open}. You must save your file before typesetting it. If any errors
+occur in processing, please see the log window.
@subsubheading Windows
-On Windows, start up a text-editor@footnote{Any simple or
-programmer-oriented editor with UTF-8 support will do, for example
-Notepad. Do not use a word processor, since these insert formatting
-codes that will confuse LilyPond.} and enter
+On Windows, if you double-click in the LilyPond icon on the Desktop, it
+will open a simple text editor with an example file. Save it, for
+example, to @file{test.ly} on your Desktop and then double-click on the
+file to process it (the file icon looks like a note). After some
+seconds, you will get a file @file{test.pdf}
+on your desktop. Double-click on this PDF file to view the typeset
+score. An alternative method to process the @file{test.ly} file
+is to drag and drop it onto the LilyPond icon using your mouse pointer.
-@verbatim
-{
- c' e' g' e'
-}
-@end verbatim
+To edit an existing @file{.ly} file, right-click on it and select
+@qq{Edit source}. To get an empty file to start from, run the editor
+as described above and use @qq{New} in the @qq{File} menu.
-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.
+Double-clicking the file does not only result in a PDF file, but also
+produces a @file{.log} file that contains some information on what LilyPond
+has done to the file. If any errors occur, please examine this file.
+Note that there are several other text editors available, with better
+support for LilyPond, see @rprogram{Editor support}, for more information.
@subsubheading Unix
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 they have not been
-installed already, refer to the file @file{INSTALL.txt}. These
+installed already, refer to the file @file{INSTALL.txt}. The
easiest editing environment is @file{LilyPondTool}. See
-@ref{Editor support} for more information.}. In your
+@rprogram{Editor support}, for more information.}. In your
text editor, enter the following input and save the file as
@file{test.ly}
@noindent
The result is the file @file{test.pdf} which you can print or view
with the standard facilities of your operating system.@footnote{If
-your system does not have any tools installed, you can try
+your system does not have any such tools installed, you can try
@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
available package for viewing and printing PDF and PostScript files.}
If you do not specify a duration, the previous duration is used
for the next note. The duration of the first note defaults to a quarter.
-To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.
+To create @rglos{dotted note}s, add a dot @samp{.} to the duration number.
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
\clef treble
c1
\clef alto
- c1
+ c1
\clef tenor
c1
\clef bass
@quotation
@table @asis
@item Entering pitches and durations
-see @ref{Pitches} and @ref{Durations}.
+see @ref{Pitches}, and @ref{Durations}.
@item Rests
see @ref{Rests}.
@item Time signatures and other timing commands
@node Working on text files
@subsection Working on text files
-LilyPond input files are treated like files in most programming languages:
-they are case sensitive, white-space insensitive, expressions are
+LilyPond input files are similar to source files in many common programming languages.
+They are case sensitive, and white-space is generally equivalent. Expressions are
formed with curly braces @{ @}, and comments are denoted with @code{%} or
-@code{%@{ .. %@}}.
+@code{%@{ ... %@}}.
If the previous sentence sounds like nonsense, don't worry! We'll explain
what all these terms mean:
@item @strong{Case sensitive}:
it matters whether you enter a letter
in lower case (i.e. @code{a, b, s, t}) or upper case (i.e.
-@code{A, B, S, T}). Notes are lower case: @code{ @{ c d e @} }
-is valid input; @code{ @{ C D E @} } will produce an error message.
+@code{A, B, S, T}). Notes are lower case: @code{@{ c d e @}}
+is valid input; @code{@{ C D E @}} will produce an error message.
@item @strong{Whitespace insensitive}:
it does not matter how many
-spaces (or new lines) you add. @code{ @{ c d e @}} means the same thing
-as @code{ @{ c @ @ @ @ @ d e @} } and
+spaces (or new lines) you add. @code{@{ c d e @}} means the same thing
+as @code{@{ c @tie{} @tie{} @tie{} d e @}} and
@example
@{
c d
be surrounded by a space unless they are at the beginning or end of a
line to avoid ambiguities.
-A function (such as @code{\relative @{ @}} ) also counts as a single
+A function (such as @code{\relative @{ @}}) also counts as a single
music expression.
@cindex comments
introduces a line comment; anything after @samp{%} on that line is
ignored. A block comment marks a whole section of music
input as a comment. Anything that is enclosed in @code{%@{} and @code{%@}} is
-ignored. The following fragment shows possible uses for comments
+ignored. (Comments do not nest.) The following fragment shows possible uses for comments
@example
% notes for twinkle twinkle follow
of your own.
-@node Notation for one note at once FIXME name
-@section Notation for one note at once FIXME name
+@node Single staff notation
+@section Single staff notation
-This section introduces common notation that is used for a single
-staff.
+This section introduces common notation that is used for one voice
+on one staff.
@menu
* Relative note names::
@subheading Warning: key signatures and pitches
To determine whether to print an accidental, LilyPond examines the
-pitches and the key signature. The key signature only effects
+pitches and the key signature. The key signature only affects
the @emph{printed} accidentals, not the actual pitches! This is a
feature that often causes confusion to newcomers, so let us explain it
in more detail.
Adding all alterations explicitly might require a little more effort
when typing, but the advantage is that transposing is easier, and
accidentals can be printed according to different conventions. See
-@ref{Automatic accidentals} for some examples how accidentals can be printed
+@ref{Automatic accidentals}, for some examples how accidentals can be printed
according to different rules.
@moreinfo
@quotation
@table @asis
@item Accidentals
-see @ref{Accidentals} and @ref{Automatic accidentals}.
+see @ref{Accidentals}, and @ref{Automatic accidentals}.
@item Key signature
see @ref{Key signature}.
@end table
@cindex phrasing slurs
@subheading Phrasing slurs
-@cindex phrasing slurs
Slurs to indicate longer phrasing can be entered with @code{\(} and
@code{\)}. You can have both legato slurs and phrasing slurs at the
same time, but you cannot have simultaneous slurs or simultaneous
@cindex staccato
@subheading Articulations
-@c FIXME: change to @rglos once the term is added (articulations)
-Common articulations can be added to a note using a dash (@samp{-}) and a
-single character:
+Common @rglos{articulation}s can be added to a note using a dash @samp{-}
+and a single character:
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
c-. c-- c-> c-^ c-+ c-_
@cindex partial measure
@subheading Partial measure
-@c FIXME: glossary "anacrusis".
-A pickup (or @q{anacrusis}) is entered with the keyword @code{\partial}. It
-is followed by a duration: @code{\partial 4} is a quarter note pickup
-and @code{\partial 8} an eighth note.
+A pickup (or @rglos{anacrusis}) is entered with the keyword
+@code{\partial}. It is followed by a duration: @code{\partial 4} is
+a quarter note pickup and @code{\partial 8} an eighth note.
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\partial 8
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\times 2/3 { f8 g a }
\times 2/3 { c r c }
-\times 2/3 { f,8 g16 a g a }
+\times 2/3 { f,8 g16[ a g a] }
\times 2/3 { d4 a8 }
@end lilypond
keyword @code{\appoggiatura} or @code{\acciaccatura}
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-c2 \grace { a32 b} c2
+c2 \grace { a32[ b] } c2
c2 \appoggiatura b16 c2
c2 \acciaccatura b16 c2
@end lilypond
@end lilypond
Putting a group of music expressions (e.g. notes) in braces means that
-are in sequence (i.e. each one follows the previous one). The result
+they are in sequence (i.e. each one follows the previous one). The result
is another music expression:
@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
This technique is useful for polyphonic music. To enter music
with more voices or more staves, we combine expressions in
-parallel. To indicate that two voices should play at the same time
-simple enter a simultaneous combination of music expressions. A
+parallel. To indicate that two voices should play at the same time,
+simply enter a simultaneous combination of music expressions. A
@q{simultaneous} music expression is formed by enclosing expressions inside
@code{<<} and @code{>>}. In the following example, three sequences (all
containing two separate notes) are combined simultaneously:
is at the beginning of a line, but indenting LilyPond code like this makes
it much easier for humans to read.
+@strong{Warning}: each note is relative to the
+previous note in the input, not relative to the @code{c''} in the
+initial @code{\relative} command.
+
+
@subheading Simultaneous music expressions: single staff
To determine the number of staves in a piece, LilyPond looks at the first
-exression. If it is a single note, there is one staff; if there is a
+expression. If it is a single note, there is one staff; if there is a
simultaneous expression, there is more than one staff.
@lilypond[quote,ragged-right,verbatim]
Time signatures entered in one staff affects all other staves, but
the key signature of one staff does @emph{not} affect other
staves@footnote{This behavior may be changed if desired; see
-@ref{Changing defaults} for details.}.
+@ref{Changing defaults}, for details.}.
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
@end lilypond
You can combine markings like beams and ties with chords. They must
-be placed outside the angled brackets
+be placed outside the angle brackets
@lilypond[quote,fragment,verbatim,relative=2,fragment]
r4 <c e g>8[ <c f a>]~ <c f a>2
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
- a4 e c r4
- b2 c4( d)
+ a4 e c8 e r4
+ b2 c4( d)
}
@end lilypond
@lilypond[quote,ragged-right,verbatim]
<<
\relative c'' {
- a4 e c r4
- b2 c4( d)
+ a4 e c8 e r4
+ b2 c4( d)
}
\addlyrics { One day this shall be free }
>>
@lilypond[quote,ragged-right,verbatim]
<<
\relative c'' {
- a4 e c r4
- b2 c4( d)
+ a4 e c8 e r4
+ b2 c4( d)
}
\addlyrics { One day this shall be free __ }
>>
Similarly, hyphens between words can be entered as two dashes,
resulting in a centered hyphen between two syllables
-@example
-A -- le gri -- a
-@end example
-
@c no ragged-right here because otherwise the hypens get lost.
@lilypond[quote,verbatim]
<<
\time 2/4
f4 f c c
}
- \addlyrics { A -- le gri -- a }
+ \addlyrics { A -- le -- gri -- a }
>>
@end lilypond
@cindex chords
@cindex chord names
-@c TODO: revise this, \chords { } is shorter and more intuitive.
-@c I need help for this. -gp
-
In popular music it is common to denote accompaniment with chord names.
Such chords can be entered like notes,
\chordmode { c2 f4. g8 }
@end lilypond
-@noindent
Now each pitch is read as the root of a chord instead of a note.
-This mode is switched on with @code{\chordmode}
-
-Other chords can be created by adding modifiers after a colon. The
-following example shows a few common modifiers
+This mode is switched on with @code{\chordmode}. Other chords can be
+created by adding modifiers after a colon. The
+following example shows a few common modifiers:
@lilypond[quote,verbatim,ragged-right]
\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
line for themselves. This is achieved by using @code{\chords} instead
of @code{\chordmode}. This uses the same syntax as @code{\chordmode},
but renders the notes in a @code{ChordNames} context, with the
-following result.
+following result:
@lilypond[quote,verbatim,ragged-right]
\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
@cindex lead sheet
When put together, chord names, lyrics and a melody form
-a lead sheet, for example,
+a lead sheet,
@lilypond[quote,verbatim,ragged-right]
-% this melody needs to be changed. See my new example in 2.4.1. -gp
<<
- \chords { r2 c:sus4 f }
- \relative {
- r4 c' \times 2/3 { f g g }
- \times 2/3 { g4( a2) }
+ \chords { c2 g:sus4 f e }
+ \relative c'' {
+ a4 e c8 e r4
+ b2 c4( d)
}
- \addlyrics { I want to break free __ }
+ \addlyrics { One day this shall be free __ }
>>
@end lilypond
+
+@moreinfo
+@quotation
A complete list of modifiers and other options for layout can be found
in @ref{Chords}.
+@end quotation
@node Final touches
* Version number::
* Adding titles::
* Absolute note names::
+* Organizing pieces with identifiers::
* After the tutorial::
* How to read the manual::
@end menu
was written. To mark a file for version 2.10.1, place
@example
-\version "2.10.1"
+\version "2.11.23"
@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{Updating files with convert-ly}), and it uses
+@file{convert-ly} (see @rprogram{Updating files with convert-ly}), and it uses
@code{\version} to determine what rules to apply.
the @ref{Version number}.
@example
-\version "2.10.1"
+\version "2.11.23"
\header @{
title = "Symphony"
composer = "Me"
is extremely useful for computer-generated LilyPond files.
-@node After the tutorial
-@subsection After the tutorial
-
-After finishing the tutorial, you should probably try writing a
-piece or two. Start with one of the @ref{Example templates} and
-add notes. If you need any notation that was not covered in the
-tutorial, look at the Notation Reference, starting with
-@ref{Basic notation}. If you want to write for an instrument
-ensemble which is not covered in the @ref{Example templates},
-take a look at @ref{Extending the templates}.
-
-Once you have written a few short pieces, read the rest of
-the Learning Manual (chapters 3-5). There's nothing wrong
-with reading them now, of course! However, the rest of the
-Learning Manual assumes that you are familiar with
-LilyPond input. You may wish to skim these chapters right
-now, and come back to them after you have more experience.
-
-
-@node How to read the manual
-@subsection How to read the manual
-
-As we saw in @ref{How to read the tutorial}, many examples in the
-tutorial omitted a @code{\relative c'' @{ ... @}} around the printed
-example.
-
-In the rest of the manual, we are much more lax about the
-printed examples: sometimes they may have omitted a
-@code{\relative c'' @{ ... @}}, but in other times a different initial
-pitch may be used (such as @code{c'} or @code{c,,}), and in some cases
-the whole example is in absolute note mode! However, ambiguities like
-this only exist where the pitches are not important. In any example
-where the pitch matters, we have explicitly stated our @code{\relative}
-our our absolute-mode @code{@{ @}}.
-
-If you are still confused about the exact LilyPond input that was
-used in an example, read the HTML version (if you are not already doing
-so) and click on the picture of the music. This will display the exact
-input that LilyPond used to generate this manual.
-
-
-
-@c zz
-
-@node FIXME merge with chapter 3
-@section FIXME merge with chapter 3
-
-@menu
-* Organizing larger pieces::
-* An orchestral part::
-@end menu
-
-
-
-@node Organizing larger pieces
-@subsection Organizing larger pieces
+@node Organizing pieces with identifiers
+@subsection Organizing pieces with identifiers
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 music,
-more deeply nested. Such large expressions can become unwieldy.
+larger files, the music expressions get a lot bigger. In polyphonic
+music with many staves, the input files can become very confusing. We can
+reduce this confusion by using @emph{identifiers}.
-By using variables, also known as identifiers, it is possible to break
-up complex music expressions. An identifier is assigned as follows
+With identifiers (also known as variables or macros), we can break up
+complex music expressions. An identifier is assigned as follows
@example
namedMusic = @{ @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}.
-In the next example, a two-note motive is repeated two times by using
-variable substitution
-
-@lilypond[quote,ragged-right,verbatim,nofragment]
-seufzer = {
- e'4( dis'4)
+The contents of the music expression @code{namedMusic} can be used
+later by placing a backslash in front of the name
+(@code{\namedMusic}, just like a normal LilyPond command). Identifiers
+must be defined @emph{before} the main music expression.
+
+@lilypond[quote,verbatim,ragged-right]
+violin = \new Staff { \relative c'' {
+ a4 b c b
+}}
+cello = \new Staff { \relative c {
+ \clef bass
+ e2 d
+}}
+{
+ <<
+ \violin
+ \cello
+ >>
}
-{ \seufzer \seufzer }
@end lilypond
-The name of an identifier should have alphabetic characters only: no
-numbers, underscores, or dashes. The assignment should be outside of
-running music.
+@noindent
+The name of an identifier must have alphabetic characters only: no
+numbers, underscores, or dashes.
It is possible to use variables for many other types of objects in the
input. For example,
@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
\paper @{
@{ c4^\name @}
@end example
-More information on the possible uses of identifiers is given in the
-technical manual, in @ref{Input variables and Scheme}.
-@c fixme: the ref is too technical.
-
-
-@node An orchestral part
-@subsection An orchestral part
-
-In orchestral music, all notes are printed twice. Once in a part for
-the musicians, and once 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 full score.
-
-It is convenient to define the notes in a special file. For example,
-suppose that the file @file{horn-music.ly} contains the following part
-of a horn/@/bassoon duo
-
-@example
-hornNotes = \relative c @{
- \time 2/4
- r4 f8 a cis4 f e d
-@}
-@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"
-@}
-
-@{
- \transpose f c' \hornNotes
-@}
-@end example
-
-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 upwards. Sounding
-@samp{f} is denoted by notated @code{c'}, which corresponds with the
-tuning of a normal French Horn in@tie{}F. The transposition can be seen
-in the following output
-
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- r4 f8 a cis4 f e d
-}
-@end lilypond
-
-In ensemble pieces, one of the voices often does not play for many
-measures. This is denoted by a special rest, the multi-measure
-rest. It is entered with a capital @samp{R} followed by a duration
-(@code{1}@tie{}for a whole note, @code{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
-@end example
-
-When printing the part, multi-rests
-must be condensed. This is done by setting a run-time variable
-
-@example
-\set Score.skipBars = ##t
-@end example
-
-@noindent
-This command sets the property @code{skipBars} in the
-@code{Score} context to true (@code{##t}). Prepending the rest and
-this option to the music above, leads to the following result
-
-@lilypond[quote,ragged-right]
-\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 together. Assuming
-that the other voice is in @code{bassoonNotes} in the file
-@file{bassoon-music.ly}, a score is made with
+@node After the tutorial
+@subsection After the tutorial
-@example
-\include "bassoon-music.ly"
-\include "horn-music.ly"
+After finishing the tutorial, you should probably try writing a
+piece or two. Start with one of the @ref{Templates}, and
+add notes. If you need any notation that was not covered in the
+tutorial, look at the Notation Reference, starting with
+@ref{Basic notation}. If you want to write for an instrument
+ensemble that is not covered in the templates,
+take a look at @ref{Extending the templates}.
-<<
- \new Staff \hornNotes
- \new Staff \bassoonNotes
->>
-@end example
+Once you have written a few short pieces, read the rest of
+the Learning Manual (chapters 3-5). There's nothing wrong
+with reading it now, of course! However, the rest of the
+Learning Manual assumes that you are familiar with
+LilyPond input. You may wish to skim these chapters right
+now, and come back to them after you have more experience.
-@noindent
-leading to
-@lilypond[quote,ragged-right]
-\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}.
+@node How to read the manual
+@subsection How to read the manual
-Setting run-time variables (@q{properties}) is discussed in
-@ref{Changing context properties on the fly}.
+As we saw in @ref{How to read the tutorial}, many examples in the
+tutorial omitted a @code{\relative c'' @{ ... @}} around the printed
+example.
+In the rest of the manual, we are much more lax about the
+printed examples: sometimes they may have omitted a
+@code{\relative c'' @{ ... @}}, but other times a different initial
+pitch may be used (such as @code{c'} or @code{c,,}), and in some cases
+the whole example is in absolute note mode! However, ambiguities like
+this only exist where the pitches are not important. In any example
+where the pitch matters, we have explicitly stated @code{\relative}
+or absolute-mode @code{@{ @}}.
+If you are still confused about the exact LilyPond input that was
+used in an example, read the HTML version (if you are not already doing
+so) and click on the picture of the music. This will display the exact
+input that LilyPond used to generate this manual.
projects / lilypond.git / blobdiff