@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
@c TODO:
@c * more details about running lilypond; error messages,
@node Tutorial
@chapter Tutorial
-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.
+This tutorial starts with an introduction to the LilyPond music
+language and how to produce printed music. After this first contact we
+will explain how to create common musical notation.
@ifhtml
Many people learn programs by trying and fiddling around with the
@end lilypond
@end ifhtml
-By cutting and pasting the full input into a test file, you have a
+By cutting and pasting everything from the @qq{Start cut-&-pastable section},
+to the end of the 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
commands for quick reference.
@menu
-* First steps::
-* Running LilyPond for the first time::
+* First steps (compiling a file)::
+* Simple notation::
+* Working on text files::
* More about pitches::
* Entering ties::
* Automatic and manual beams::
@end menu
-@node First steps
-@section First steps
+@node First steps (compiling a file)
+@section First steps (compiling a file)
-The first example demonstrates how to enter the most elementary piece
-of music, a @rglos{scale}. A @rglos{note} can be entered by typing its
-name, from @samp{a} through @samp{g}. So, if you enter
+The first example demonstrates how to start working with LilyPond. To
+create sheet music, we write a text file that specifies the
+notation. For example, if we write
@example
@{
-c d e f g a b
+ c' e' g' e'
@}
@end example
@noindent
the result looks like this
-@lilypond[fragment,quote,notime,relative=1]
-c d e f g a b
+@lilypond[quote,ragged-right]
+{
+ c' e' g' e'
+}
@end lilypond
-Every piece of LilyPond input needs to have @{curly braces@} placed
-around the input. For the rest of this manual, most examples will
-omit these braces, but don't forget them in your own music!
-
-In addition, many examples use @code{relative} mode. This is explained
-in @ref{Octave entry}; for now simply be aware that some examples
-should be placed inside @code{\relative @{ @emph{...music...} @}}.
-Many example have also been compressed horizontally to save
-space, using @code{\paper @{ ragged-right = ##t @}}.
+@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
+braces @}} placed around the input. The braces should be 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
-Finally, LilyPond input is case sensitive. @code{ @{ c d e @} } is
-valid input; @code{ @{ C D E @} } will produce an error message.
-
-The @rglos{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[fragment,quote,notime,relative=2]
-\set Staff.autoBeaming = ##f
-{ a1 a2 a4 a16 a32 s16_" " }
-@end lilypond
-
-If you do not specify a duration, the duration last entered is used
-for the next notes. The duration of the first note in input defaults
-to a quarter
-
-@example
-a a8 a a2 a
-@end example
-
-@lilypond[fragment,quote,notime,relative=2]
-{ a a8 a a2 a s16_" " }
-@end lilypond
-
-
-A @rglos{rest} is entered just like a note, but with the name @samp{r}
-
-@example
-r2 r4 r8 r16
-@end example
-
-@lilypond[fragment,quote,notime]
-r2 r4 r8 r16 s16_" "
-@end lilypond
-
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}
-
-@example
-a2. a4 a8. a16
-@end example
-
-@lilypond[fragment,quote,notime,relative=1]
-{ a2. a4 a8. a16 s16_" " }
-@end lilypond
-
-The (or @rglos{time signature}) can be set with the @code{\time}
-command
-
-@example
-\time 3/4
-\time 6/8
-\time 4/4
-@end example
-
-@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
-s4_" "
-\time 4/4
-s16_" "
-@end lilypond
-
-The @rglos{clef} can be set using the @code{\clef} command
-
-@example
-\clef treble
-\clef bass
-\clef alto
-\clef tenor
-@end example
-
-@lilypond[fragment,quote,notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
-@end lilypond
-
-Remember to enclose the notes and commands in curly braces
-@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
-
-@c @li lypond[fragment,quote,noindent,line-width=55\staff-space]
-@lilypond[fragment,quote,noindent,verbatim]
-\time 3/4
-\clef bass
-c2 e4 g2.
-f4 e d c2 r4
-@end lilypond
-
-For more 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
+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
-@node Running LilyPond for the first time
-@section Running LilyPond for the first time
+@unnumberedsubsec Entering music and viewing output
-@c cheesy title to avoid clash with chapter name.
+In this section we will explain what commands to run
+and how to view or print the output.
-In the last section we explained what kind of things you can enter in
-a LilyPond file. In this section we will explain what commands to run
-and how to view or print the output. If you have not used LilyPond
-before, want to test your setup, or want to run an example file
-yourself, read this section.
-
-@unnumberedsubsec MacOS X
+@unnumberedsubsubsec 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
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-ever run will take a minute or two, because
-all of the system fonts have to be analyzed first.
+Be warned that the first time you ever run lilypond 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".
-@unnumberedsubsec Windows
+@unnumberedsubsubsec Windows
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, since these insert formatting codes that will confuse
-LilyPond.} and enter
+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
@verbatim
-{ c'4 e' g' }
+{
+ c' e' g' e'
+}
@end verbatim
Save it on the desktop as @file{test.ly} and make sure that it is not
the file and show the resulting PDF file.
-@unnumberedsubsec Unix
+@unnumberedsubsubsec Unix
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
+@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}.} In your
+installed already, refer to the file @file{INSTALL.txt}. These
+easiest editing environment is @file{LilyPondTool}. See
+@ref{Editor support} for more information.}. In your
text editor, enter the following input and save the file as
@file{test.ly}
@verbatim
-{ c'4 e' g' }
+{
+ c' e' g' e'
+}
@end verbatim
@noindent
@example
lilypond test.ly
-GNU LilyPond 2.6.0
+GNU LilyPond 2.10.0
Processing `test.ly'
Parsing...
Interpreting music... [1]
Converting to `test.pdf'...
@end example
-@cindex DVI file
+@cindex PDF file
@cindex Viewing music
-@cindex xdvi
+
@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
@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
available package for viewing and printing PDF and PostScript files.}
+
+@node Simple notation
+@section Simple notation
+
+LilyPond will add some notation elements automatically. In the next
+example, we have only specified four pitches, but LilyPond has
+added a clef, time signature, and rhythms.
+
+@lilypond[quote,ragged-right,verbatim]
+{
+ c' e' g' e'
+}
+@end lilypond
+
+@noindent
+This behavior may be altered, but in most cases these automatic values
+are useful.
+
+
+@unnumberedsubsec Pitches
+
+The easiest way to enter notes is by using @code{\relative} mode. In
+this mode, the @rglos{interval} between the previous note and the
+current note is assumed to be within a @rglos{fourth}. We begin by
+entering the most elementary piece of music, a @rglos{scale}.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ c d e f
+ g a b c
+}
+@end lilypond
+
+The initial note is @rglos{middle C}. Each successive note
+is within a fourth of the previous note -- in other words, the first
+@samp{c} is the closest C to middle C. This is followed by the closest
+D to the previous note. We can create melodies which have larger intervals:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ d f a g
+ c b f d
+}
+@end lilypond
+
+@noindent
+As you may notice, this example does not start on middle C. The first
+note -- the @samp{d} -- is the closest D to middle C.
+
+To add intervals that are larger than a fourth, we can raise the octave
+by adding a single quote @code{'} (or apostrophe) to the note name. We can
+lower the octave by adding a comma @code{,} to the note name.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a a, c' f,
+ g g'' a,, f'
+}
+@end lilypond
+
+@noindent
+To change a note by two (or more!) octaves, we use multiple @code{''} or
+@code{,,} -- but be careful that you use two single quotes @code{''} and
+not one double quote @code{"}@tie{}! The initial value in
+@code{\relative c'} may also be modified like this.
+
+
+@unnumberedsubsec Durations (rhythms)
+
+The @rglos{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. Beams are added
+automatically.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a1
+ a2 a4 a8 a
+ a16 a a a a32 a a a a64 a a a a a a a a2
+}
+@end lilypond
+
+@noindent
+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.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a a a4. a8
+ a8. a16 a a8. a8 a4.
+}
+@end lilypond
+
+
+@unnumberedsubsec Rests
+
+A @rglos{rest} is entered just like a note with the name @samp{r}:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a r r2
+ r8 a r4 r4. r8
+}
+@end lilypond
+
+
+@unnumberedsubsec Time signature
+
+The @rglos{time signature}) can be set with the @code{\time} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ \time 3/4
+ a4 a a
+ \time 6/8
+ a4. a
+ \time 4/4
+ a4 a a a
+}
+@end lilypond
+
+
+@unnumberedsubsec Clef
+
+The @rglos{clef} can be set using the @code{\clef} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ \clef treble
+ c1
+ \clef alto
+ c1
+ \clef tenor
+ c1
+ \clef bass
+ c1
+}
+@end lilypond
+
+
+@unnumberedsubsec All together
+
+Here is a small example showing all these elements together:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c, {
+ \time 3/4
+ \clef bass
+ c2 e8 c' g'2.
+ f4 e d c4 c, r4
+}
+@end lilypond
+
+
+@node Working on text files
+@section Working on text files
+
+LilyPond input files are treated like files in most programming languages:
+they are case sensitive, white-space insensitive, and expressions are
+formed with curly braces @{ @}.
+
+If the previous sentence sounds like nonsense, don't worry! We'll explain
+what all these terms mean:
+
+@itemize
+@item
+@strong{Remember:} Every piece of LilyPond input needs to have
+@strong{@{ curly braces @}} placed around the input. The braces should
+be surrounded by
+a space unless they are at the beginning or end of a line to avoid
+ambiguities. For the rest of this manual, most examples will omit
+these braces, but don't forget them in your own music!
+
+@cindex Case sensitive
+@item
+In addition, LilyPond input is @strong{case sensitive}. @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
+
+@c End of current re-write; more material coming in a few days. -gp
+@end itemize
+
+
+
@node More about pitches
@section More about pitches
-A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
-the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}. As
+A @rglos{sharp} pitch is made by adding @samp{is} to
+the name, a @rglos{flat} 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,
@end example
@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
+The code @samp{d} does not mean @qq{print a black dot just below the
+staff.} Rather, it means: @qq{a note with pitch D-natural.} In the key
of A-flat major, it does get an accidental
@lilypond[quote,notime,fragment,relative=1,verbatim]
@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{,}
+To raise a note by an octave, add a high quote @samp{'} (apostrophe) to
+the note name, to lower a note one octave, add a @q{low quote} @samp{,}
(comma). Middle C is @code{c'}
@lilypond[quote,notime,fragment,verbatim]
@noindent
This example shows that music in a high register needs lots of quotes.
This makes the input less readable, and it is a source of errors. The
-solution is to use `relative octave' mode. This is the
+solution is to use @q{relative octave} mode. This is the
most convenient way to copy existing music.
-In relative mode, a note without octavation quotes (i.e. the @code{'}
-or @code{,} after a note) is chosen so that it is closest to the
+In relative mode, a note without octavation quotes (i.e., the @samp{'}
+or @samp{,} after a note) is chosen so that it is closest to the
previous one. For example, @samp{c f} goes up while @samp{c g} goes
down.
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'
+as a simultaneous combination of two sequences. A @q{simultaneous}
music expression is formed by enclosing expressions in @code{<<} and
@code{>>}. In the following example, three sequences (all containing
two separate notes) are combined simultaneously
@end lilypond
-The command @code{\new} introduces a `notation context.' A notation
+The command @code{\new} introduces a @q{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 automatically. For more complex pieces, it
A comment is a remark for the human reader of the music input; it is
ignored while parsing, so it has no effect on the printed output.
There are two types of comments. The percent symbol @samp{%}
-introduces a line comment; after @code{%} the rest of the line is
+introduces a line comment; after @samp{%} the rest of the line is
ignored. A block comment 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
There is a special statement that is a kind of comment. The @code{\version}
statement marks for which version of LilyPond the file was written.
-To mark a file for version 2.6.0, use
+To mark a file for version 2.10.1, use
@example
-\version "2.6.0"
+\version "2.10.1"
@end example
@noindent
@cindex melisma
@cindex extender line
@c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (`free')
+This melody ends on a @rglos{melisma}, a single syllable (@q{free})
sung to more than one note. This is indicated with an @emph{extender
line}. It is entered as two underscores, i.e.,
resulting in a centered hyphen between two syllables
@example
-Twin -- kle twin -- kle
+A -- le gri -- a
@end example
-@lilypond[fragment,quote,ragged-right]
+@c no ragged-right here, because otherwise the hypens get lost.
+@lilypond[fragment,quote]
<<
\relative {
\time 2/4
f4 f c' c
}
- \addlyrics { Twin -- kle twin -- kle }
+ \addlyrics { A -- le gri -- a }
>>
@end lilypond
For polyphonic music typesetting, spacer rests can also be convenient;
these are rests that do not print. They are useful for filling up
voices that temporarily do not play. Here is the same example with a
-spacer rest (@code{s}) instead of a normal rest (@code{r}),
+spacer rest (@samp{s}) instead of a normal rest (@samp{r}),
@lilypond[quote,verbatim,relative=2,fragment]
<< { a4 g2 f4~ f4 } \\
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
+Setting run-time variables (@q{properties}) is discussed in
@ref{Changing context properties on the fly}.
LilyPond input. You may wish to skim these chapters right
now, and come back to them after you have more experience.
+@ignore
+For more information on
+
+@q uotation
+@t able @asis
+@i tem Entering pitches and durations
+see
+@r ef{Pitches}, and @ref{Durations}.
+@i tem Clefs
+see @ref{Clef}.
+@i tem Rests
+see @ref{Rests}.
+@i tem Time signatures and other timing commands
+see @ref{Time signature}.
+@e nd table
+@e nd quotation
+@end ignore
+
projects / lilypond.git / blobdiff