Doc: NR Update information for modern-cautionary

[lilypond.git] / Documentation / learning / tutorial.itely

@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

@include included/generating-output.itexi

@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

This section introduces @qq{compiling}---the processing of
LilyPond input files (written by you) to produce output files.

@menu
* Entering input::
* MacOS X::
* Windows::
* Command-line::
@end menu

@node Entering input
@subsection Entering input

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

@menu
* Producing output::
@end menu

@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

The graphical output is:

@c  in this case we don't want verbatim
@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 @}}} will
produce an error message.


@smallspace

@node Producing output
@unnumberedsubsubsec Producing output

@cindex PDF file
@cindex viewing music
@cindex text editors

The method of producing output depends on your operating system
and the program(s) you use.

@itemize

@item
@ref{MacOS X, @sourceimage{logo-macosx,,,}}
@ref{MacOS X, MacOS X} (graphical)

@item
@ref{Windows, @sourceimage{logo-windows,,,}}
@ref{Windows, Microsoft Windows} (graphical)

@item
@ref{Command-line, @sourceimage{logo-linux,,,}
@sourceimage{logo-freebsd,,,}
@sourceimage{logo-macosx,,,}
@sourceimage{logo-windows,,,}
}
@ref{Command-line, All operating systems} (command-line)

@end itemize

There are several other text editors available with specific
support for LilyPond.  For more information, see
@rweb{Easier editing}.

@warning{The first time you ever run LilyPond, it may take a
minute or two because all of the system fonts have to be analyzed
first.  After this, LilyPond will be much faster!}


@node MacOS X
@subsection MacOS X

@cindex running LilyPond under MacOS X
@cindex MacOS X, running LilyPond

@lilypadOSX


@node Windows
@subsection Windows

@cindex running LilyPond under Windows
@cindex Windows, running LilyPond

@lilypadWindows


@node Command-line
@subsection Command-line

@cindex running LilyPond under Unix
@cindex Unix, running LilyPond

@lilypadCommandLine

@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 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[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 relative
@funindex '
@funindex ,

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

The easiest way to enter notes is by using @code{\relative} mode.
In this mode, the octave is chosen automatically by assuming the
following note is always to be placed closest to the previous
note, i.e., it is to be placed in the octave which 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

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
@code{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, still using only @code{\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
@code{'}-mark -- is the D in the octave starting from middle C
and going up to B.

By adding (or removing) quotes @code{'} or commas @code{,} 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 B, which is on the middle line
in a treble clef, you can reach a C, D and E within 3 staff spaces
going up, and an A, G and F within 3 staff spaces going down.  So
if the note following a B is a C, D or E it will be assumed to be
above the B, and an A, G or F will be 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 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 @code{'} (or
apostrophe) to the note name.  We can lower the octave by adding a
comma @code{,} 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 @code{"}@tie{}!
@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:  @code{1} for a @notation{whole note}, @code{2} for
a @notation{half note}, @code{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 @code{.} 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
@code{r}@tie{}:

@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
@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
@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
@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


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


@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 white-space is generally ignored.  Expressions are
formed with curly braces @w{@code{@{ @}}}, and comments are
denoted with @code{%} or @w{@code{%@{ @dots{} %@}}}@tie{}.

If the previous sentences sound like nonsense, don't worry!  We'll
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 "@w{@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 will print
a warning during the compilation of the file.

@item
@strong{Case sensitive}:
it matters whether you enter a letter in lower case (e.g.
@w{@code{a, b, s, t}}) or upper case (e.g. @w{@code{A, B, S, T}}).
Notes are lower case: @w{@samp{@{ c d e @}}} is valid input;
@w{@samp{@{ C D E @}}} will produce an error message.

@item
@strong{Whitespace insensitive}:
it does not matter how many spaces (or tabs or new lines) you add.
@w{@samp{@{ c4 d e @}}} means the same thing as
@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:

@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@tie{}braces@tie{}@}} placed around the
input.  These braces tell LilyPond that the input is a single
music expression, just like parentheses @code{()} 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 @q{@w{@code{@bs{}relative @{ @dots{} @}}}}) 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
@code{%} introduces a line comment; anything after @code{%} 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 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{@{ @}} marks or a
@q{@w{@code{@bs{}relative @{ @dots{} @}}}}, as we saw in
@ref{Working on input files}.  For the rest of this manual, most
examples will omit this.  To replicate the examples, you may copy
and paste the displayed input, but to put the pitches in the same
octaves as seen in the manual you @strong{must} add a particular
form of @code{@bs{}relative} with an explicit starting pitch
@code{c''} like this:

@example
\relative c'' @{
  @dots{}example goes here@dots{}
@}
@end example

Why omit the braces?  Most examples in this manual can be inserted
into the middle of a longer piece of music.  For these examples,
it does not make sense to add
@q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} -- you should not
place a @code{\relative} inside another @code{\relative}!  If we
included @q{@w{@code{@bs{}relative c'' @{ @dots{} @}}}} around
every example, you would not be able to copy a small documentation
example and paste it inside a longer piece of your own.  Most
people want to add material to an existing piece, so we format the
manual this way.

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

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}}: read the Learning
manual's @ref{Tutorial}, and @ref{Common notation}.  If you
encounter musical terms which you do not recognize, please look
them up in the @rglosnamed{Top, Glossary}.

@item
@strong{Before trying to write a complete piece of music}: read
the Learning manual's @ref{Fundamental concepts}.  After that, you
may want to look in relevant sections of the
@rusernamed{Top, Notation reference}.

@item
@strong{Before trying to change the default output}: read the
Learning manual's @ref{Tweaking output}.

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

@end itemize