@c -*- coding: utf-8; mode: texinfo; -*-

@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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.21"

@node Tutorial
@chapter Tutorial

This chapter gives a basic introduction to working with LilyPond.

@menu
* Compiling a file::
* How to write input files::
* Dealing with errors::
* How to read the manuals::
@end menu

@node Compiling a file
@section Compiling a file

@cindex compiling
@cindex first example
@cindex example, first
@cindex case sensitive

@qq{Compiling} is the term used for processing an input file in
LilyPond format to produce output file(s).  Output files are
generally PDF (for printing or viewing), MIDI (for playing), and
PNG (for online use).  LilyPond input files are simple text files.

This example shows a simple input file:

@example
\version "@w{@version{}}"
@{
  c' e' g' e'
@}
@end example

@noindent
The graphical output is:

@c No 'verbatim' option here.
@lilypond[quote]
{
  c' e' g' e'
}
@end lilypond

@warning{Notes and lyrics in LilyPond input must always be
surrounded by @w{@strong{@{ curly braces @}}}.  The braces
should also be surrounded by a space unless they are at the
beginning or end of a line to avoid ambiguities.  They may
be omitted in some examples in this manual, but don't forget them
in your own music!  For more information about the display of
examples in the manual, see @ref{How to read the manuals}.}

In addition, LilyPond input is @strong{case sensitive}.
@w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}}
produces an error message.


@node How to write input files
@section How to write input files

This section introduces some basic LilyPond syntax to help get you
started writing input files.

@menu
* Simple notation::
* Working on input files::
@end menu


@node Simple notation
@subsection Simple notation

@cindex simple notation
@cindex notation, simple

@menu
* Pitches::
* Durations (rhythms)::
* Rests::
* Time signature::
* Tempo marks::
* Clef::
* All together::
@end menu

LilyPond adds some notation elements automatically.  In the next
example, we have only specified four pitches, but LilyPond has
added a clef, a time signature, and rhythms.

@lilypond[verbatim,quote]
{
  c' e' g' e'
}
@end lilypond

@noindent
This behavior may be altered, but in most cases these automatic
values are useful.


@node Pitches
@unnumberedsubsubsec Pitches

@cindex pitches
@cindex relative mode
@cindex quote, single
@cindex comma
@cindex accidentals and relative mode
@cindex relative mode, and accidentals

@funindex \relative
@funindex '
@funindex ,

Music Glossary:
@rglos{pitch},
@rglos{interval},
@rglos{scale},
@rglos{middle C},
@rglos{octave},
@rglos{accidental}.

LilyPond uses lowercase letters for pitches.  Note names in all
examples in this section use the Dutch naming system (white piano
keys are c, d, e, f, g, a,@tie{}b).  However, LilyPond supports
many different naming schemes like @q{English} or @q{Fixed-Do}
(do, re, mi, @dots{}).  See @ruser{Note names in other languages}.
The letters @samp{c} through @samp{b} denote pitches in the
@q{small octave} below @notation{middle C}.  Added @samp{'} or
@samp{,} suffixes indicate higher or lower octaves.  Here is a
scale starting on @notation{middle C}, and an arpeggio:

@lilypond[verbatim,quote]
{ c' d' e' f' g' a' b' c''
  g c' e' g' c'' e'' g'' c''' }
@end lilypond

The easiest way to enter notes is by using @code{\relative} mode.
In this mode, the octave is chosen automatically by assuming that
the following note is always to be placed closest to the previous
note, i.e., it is to be placed in the octave that is within three
staff spaces of the previous note.  We begin by entering the most
elementary piece of music, a @notation{scale}, in which every note
is within just one staff space of the previous note.

@lilypond[verbatim,quote]
\relative {
  c' d e f
  g a b c
}
@end lilypond

@noindent
The initial note is @notation{middle C}, denoted by @code{c'}.
Each successive note is placed closest to the previous note -- in
other words, the first @samp{c} is the closest@tie{}C to
middle@tie{}C.  This is followed by the closest@tie{}D to the
previous note.  We can create melodies that have larger intervals,
still using only relative mode:

@lilypond[verbatim,quote]
\relative {
  d' f a g
  c b f d
}
@end lilypond

@noindent
In the previous example, the first note -- the @code{d'} with one
@samp{'} mark -- is the D in the octave starting from
middle@tie{}C and going up to@tie{}B.

By adding (or removing) quotes (@samp{'}) or commas (@samp{,})
from the first note, we can change the starting octave:

@lilypond[verbatim,quote]
\relative {
  e'' c a c
}
@end lilypond

Relative mode can be confusing initially, but is the easiest way
to enter most melodies.  Let us see how this relative calculation
works in practice.  Starting from a@tie{}B, which is on the middle
line in a treble clef, you can reach a C, D and@tie{}E within
3@tie{}staff spaces going up, and an A, G and@tie{}F within
3@tie{}staff spaces going down.  So if the note following a@tie{}B
is a C, D or@tie{}E it is assumed to be above the@tie{}B, and an
A, G or@tie{}F is assumed to be below.

@lilypond[verbatim,quote]
\relative {
  b' c % c is 1 staff space up, so is the c above
  b d  % d is 2 up or 5 down, so is the d above
  b e  % e is 3 up or 4 down, so is the e above
  b a  % a is 6 up or 1 down, so is the a below
  b g  % g is 5 up or 2 down, so is the g below
  b f  % f is 4 up or 3 down, so is the f below
}
@end lilypond

Exactly the same happens even when any of these notes are
sharpened or flattened.  @notation{Accidentals} are
@strong{totally ignored} in the calculation of the relative
position.  Precisely the same staff space counting is done from a
note at any other position on the staff.

To add intervals that are larger than three staff spaces, we can
raise the @notation{octave} by adding a single quote @samp{'} (or
apostrophe) to the note name.  We can lower the octave by adding a
comma @samp{,} to the note name.

@lilypond[verbatim,quote]
\relative {
  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 @samp{"}!
@c " - keeps quotes in order for context-sensitive editor -td


@node Durations (rhythms)
@unnumberedsubsubsec Durations (rhythms)

@cindex note durations
@cindex durations
@cindex rhythms
@cindex whole note
@cindex half note
@cindex quarter note
@cindex dotted note
@cindex notating durations

Music Glossary:
@rglos{beam},
@rglos{duration},
@rglos{whole note},
@rglos{half note},
@rglos{quarter note},
@rglos{dotted note}.

The @notation{duration} of a note is specified by a number after
the note name: @samp{1} for a @notation{whole note}, @samp{2} for
a @notation{half note}, @samp{4} for a @notation{quarter note} and
so on.  @notation{Beams} are added automatically.

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 note.

@lilypond[verbatim,quote]
\relative {
  a'1
  a2 a4 a8 a
  a16 a a a a32 a a a a64 a a a a a a a a2
}
@end lilypond

To create @notation{dotted notes}, add a dot (@samp{.}) to the
duration number.  The duration of a dotted note must be stated
explicitly (i.e., with a number).

@lilypond[verbatim,quote]
\relative {
  a'4 a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond


@node Rests
@unnumberedsubsubsec Rests

@cindex rest
@cindex notating rests

Music Glossary:
@rglos{rest}.

A @notation{rest} is entered just like a note with the name
@samp{r}.

@lilypond[verbatim,quote]
\relative {
  a'4 r r2
  r8 a r4 r4. r8
}
@end lilypond


@node Time signature
@unnumberedsubsubsec Time signature

@cindex time signature

@funindex \time

Music Glossary:
@rglos{time signature}.

The @notation{time signature} can be set with the @code{\time}
command:

@lilypond[verbatim,quote]
\relative {
  \time 3/4
  a'4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond


@node Tempo marks
@unnumberedsubsubsec Tempo marks

@cindex tempo marks
@cindex metronome marks

@funindex \tempo

Music Glossary:
@rglos{tempo indication},
@rglos{metronome}.

The @notation{tempo indication} and @notation{metronome mark} can be
set with the @code{\tempo} command:

@lilypond[verbatim,quote]
\relative {
  \time 3/4
  \tempo "Andante"
  a'4 a a
  \time 6/8
  \tempo 4. = 96
  a4. a
  \time 4/4
  \tempo  "Presto" 4 = 120
  a4 a a a
}
@end lilypond


@node Clef
@unnumberedsubsubsec Clef

@cindex clef
@cindex treble
@cindex alto
@cindex tenor
@cindex bass

@funindex \clef

Music Glossary:
@rglos{clef}.

The @notation{clef} can be set using the @code{\clef} command:

@lilypond[verbatim,quote]
\relative {
  \clef treble
  c'1
  \clef alto
  c1
  \clef tenor
  c1
  \clef bass
  c1
}
@end lilypond


@node All together
@unnumberedsubsubsec All together

Here is a small example showing all these elements together:

@lilypond[verbatim,quote]
\relative {
  \clef bass
  \time 3/4
  \tempo "Andante" 4 = 120
  c,2 e8 c'
  g'2.
  f4 e d
  c4 c, r
}
@end lilypond

@morerefs
Notation Reference:
@ruser{Writing pitches},
@ruser{Writing rhythms},
@ruser{Writing rests},
@ruser{Time signature},
@ruser{Clef}.
@endmorerefs


@node Working on input files
@subsection Working on input files

@cindex curly braces
@cindex braces, curly
@cindex comments
@cindex line comment
@cindex comment, line
@cindex block comment
@cindex comment, line
@cindex case sensitive
@cindex whitespace insensitive
@cindex expressions
@cindex versioning
@cindex version
@cindex version number

@funindex \version
@funindex { ... }
@funindex %
@funindex %@{ ... %@}

LilyPond input files are similar to source files in many common
programming languages.  They contain a version statement, are case
sensitive, and whitespace is generally ignored.  Expressions are
formed with curly braces @w{@code{@{ @}}}, and comments are
denoted with @samp{%} or @w{@samp{%@{ @dots{} %@}}}.

If the previous sentences sound like nonsense, don't worry!  We
are now going to explain what all these terms mean.

@itemize

@item
@strong{Version statement}:
Every LilyPond file should contain a version statement.  A version
statement is a line that describes the version of LilyPond for which
the file was written, as in the following example:

@example
\version "@version{}"
@end example

By convention, the version statement is placed at the top of the
LilyPond file.

The version statement is important for at least two reasons.  First,
it allows automatic updating of the input file as LilyPond syntax
changes.  Second, it describes the version of LilyPond needed to
compile the file.

If the version statement is omitted from an input file, LilyPond
prints a warning during the compilation of the file.

@item
@strong{Case sensitive}:
It matters whether you enter a letter in lowercase (e.g.,
@samp{a}, @samp{b}, @samp{s}, @samp{t}) or uppercase (e.g.,
@samp{A}, @samp{B}, @samp{S}, @samp{T}).  Notes are lowercase:
@samp{@{@tie{}c d e@tie{}@}} is valid input; @samp{@{@tie{}C D
E@tie{}@}} produces an error message.

@item
@strong{Whitespace insensitive}:
It does not matter how many spaces (or tabs, or new lines) you
add.

@example
@{ c4 d e@}
@end example

@noindent
means the same thing as

@example
@{ c4       d e @}
@end example

@noindent
or

@example
@{ c4                       d
                   e   @}
@end example

@noindent
Of course, the previous example is hard to read.  A good rule of
thumb is to indent code blocks with two spaces:

@example
@{
  c4 d e
@}
@end example

However, whitespace @emph{is} required to separate many
syntactical elements from others.  In other words, whitespace can
always be @emph{added}, but not always @emph{eliminated}.  Since
missing whitespace can give rise to strange errors, it is
advisable to always insert whitespace before and after every
syntactic element, for example, before and after every curly
brace.

@item
@strong{Expressions}:
Every piece of LilyPond input needs to have @strong{@{@tie{}curly
braces@tie{}@}} placed around the input.  These braces tell
LilyPond that the input is a single music expression, just like
parentheses @q{()} in mathematics.  The braces should be
surrounded by a space unless they are at the beginning or end of a
line to avoid ambiguities.

A LilyPond command followed by a simple expression in braces (such
as @samp{\relative @{ @dots{}@tie{}@}}) also counts as a single
music expression.

@cindex comments
@cindex line comment
@cindex block comment
@item
@strong{Comments}:
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; anything after @samp{%} on
that line is ignored.  By convention, a line comment is placed
@emph{above} the code it refers to.

@example
a4 a a a
% this comment refers to the next line with the two bs
b2 b
@end example

A block comment marks a whole section of music input as a comment.
Anything that is enclosed in @code{%@{} and @code{%@}} is ignored.
However, block comments do not @q{nest}.  This means that you
cannot place a block comment inside another block comment.  If you
try, the first @code{%@}} will terminate @emph{both} block
comments.  The following fragment shows possible uses for
comments.

@example
% notes for twinkle twinkle follow
c4 c g' g a a g2

%@{
  This line, and the notes below are ignored,
  since they are in a block comment.

  f4 f e e d d c2
%@}
@end example

@end itemize


@node Dealing with errors
@section Dealing with errors

@cindex troubleshooting

Sometimes LilyPond doesn't produce the output you expect.  This
section provides some links to help you solve the problems you
might encounter.

@menu
* General troubleshooting tips::
* Some common errors::
@end menu


@node General troubleshooting tips
@subsection General troubleshooting tips

Troubleshooting LilyPond problems can be challenging for
people who are used to a graphical interface, because invalid
input files can be created.  When this happens, a logical approach
is the best way to identify and solve the problem.  Some guidelines
to help you learn to do this are provided in @rprogram{Troubleshooting}.


@node Some common errors
@subsection Some common errors

@cindex common errors
@cindex errors, common

There are a few common errors that are difficult to troubleshoot
based simply on the error messages that are displayed.  These are
described in @rprogram{Common errors}.


@node How to read the manuals
@section How to read the manuals

This section shows how to read the documentation efficiently, and
also introduces some useful interactive features available in the
online version.

@menu
* Omitted material::
* Clickable examples::
* Overview of manuals::
@end menu


@node Omitted material
@subsection Omitted material

@cindex how to read the manual
@cindex manual, reading
@cindex reading the manual
@cindex examples, clickable
@cindex clickable examples
@cindex tips for constructing files
@cindex templates
@cindex constructing files, tips
@cindex files, tips for constructing

LilyPond input must be surrounded by @code{@{@tie{}@}} marks or
@q{@code{\relative @{ @dots{}@tie{}@}}} (@pxref{Working on input
files}).  For the rest of this manual, some short examples omit
this.  To replicate these examples, you can copy displayed input,
but paste it between @samp{@{} and @samp{@}} in your input file.

@example
@{
  @dots{}example goes here@dots{}
@}
@end example

Also, remember that every LilyPond file should have a
@code{\version} statement.  Because the examples in the manuals
are snippets, not files, the @code{\version} statement is omitted.
But you should make a practice of including them in your files.


@node Clickable examples
@subsection Clickable examples

@warning{This feature is only available in the HTML manuals.}

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:

@c no verbatim here
@lilypond[quote]
\relative {
  c''4-\markup { \bold \huge { Click here. } }
}
@end lilypond

@noindent
By cutting and pasting everything in the @qq{ly snippet} section,
you have a starting template for experiments.  To see exactly the
same output (line-width and all), copy everything from @qq{Start
cut-&-pastable section} to the bottom of the file.


@ignore
This is item 825

@n ode Keyboard navigation
@s ubsection Keyboard navigation

@warning{This features is only available in the HTML manuals.}

@c TODO: once this is figured out, insert it here.

We are currently working on this feature.
@end ignore


@node Overview of manuals
@subsection Overview of manuals

There is a lot of documentation for LilyPond.  New users are
sometimes confused about what part(s) they should read, and
occasionally skip over reading vital portions.

@warning{Please do not skip over important parts of the
documentation.  You will find it much harder to understand later
sections.}

@itemize

@item
@strong{Before trying to do @emph{anything}}: @pxref{Tutorial},
and @ref{Common notation} of this manual.  If you encounter
musical terms which you do not recognize, please look them up in
the @rglos{Top}.

@item
@strong{Before trying to write a complete piece of music}:
@pxref{Fundamental concepts} of this manual.  After that, you may
want to look into relevant sections of the @ruser{Top}.

@item
@strong{Before trying to change the default output}:
@pxref{Tweaking output} in this manual.

@item
@strong{Before undertaking a large project}: read the Usage
document's @rprogram{Suggestions for writing files}.

@end itemize
