Doc: add Steps to OSX and command-line instructions.

[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.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Tutorial
@chapter Tutorial

This chapter gives a basic introduction to working with LilyPond.

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

@node Compiling a file
@section Compiling a file

FIXME: insert text

@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

@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
@{
  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{@code{@{ c d e @}}} is valid input; @w{@code{@{ C D E @}}} will
produce an error message.


@smallspace

@subheading Producing output

@c TODO: move index entries
@cindex PDF file
@cindex viewing music
@cindex text editors
@cindex running LilyPond under MacOS X
@cindex MacOS X, running LilyPond
@cindex running LilyPond under Windows
@cindex Windows, running LilyPond
@cindex running LilyPond under Unix
@cindex Unix, running LilyPond

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{Alternate input}.

@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

@warning{These instructions assume that you are using the LilyPond 
application.  If you are using any of the programs described in
@rweb{Alternate input}, please consult the documentation for
those programs if you have any problems.}


@subsubheading Step 1. Create your @file{.ly} file

Double click the @command{LilyPond.app}, an example file will open.

@sourceimage{Learning_Macos_welcome,,,}

From the menus along the top left of your screen, select
@w{@code{File > Save}}.

@sourceimage{Learning_Macos_Save_menu,,,}

Choose a name for your file, for example @file{test.ly}.

@sourceimage{Learning_Macos_Save_file_with_name,,,}


@subsubheading Step 2. Compile (with LilyPad)

From the same menus, select
@w{@code{Compile > Tyepset}}.

@sourceimage{Learning_Macos_Typeset_menu,,,}

A new window will open showing a progress log of the compilation 
of the file you have just saved.

@sourceimage{Learning_Macos_Compiling_log,,,}


@subsubheading Step 3. View output

Once the compilation has finished, a PDF file will be created with
the same name as the original file and will be automatically
opened in the default PDF viewer and displayed on your screen.

@sourceimage{Learning_Macos_pdf_output,,,}


@subsubheading Other commands

To create new files for LilyPond, begin by selecting
@w{@code{File > New}}

@sourceimage{Learning_Macos_New_menu,,,}

or @w{@code{File > Open}} to open and edit existing files you have 
saved previously.

@sourceimage{Learning_Macos_Open_menu,,,}

You must save any new edits you make to your file before you 
@w{@code{Compile > Tyepset}} and if the PDF file is not displayed
check the window with the progress log for any errors.

If you are not using the defualt Preview PDF viewer that comes 
with the Mac Operating system and you have the PDF file generated 
from a previous compilation open, then any further compilations 
may fail to generate an update PDF until you close the original.


@node Windows
@subsection Windows

@warning{These instructions assume that you are using the built-in
LilyPad editor.  If you are using any of the programs described in
@rweb{Alternate input}, please consult the documentation for
those programs if you have any problems compiling a file.}


@subsubheading Step 1. Create your @file{.ly} file

Double-click the @command{LilyPond.app}, an example file will open.

@sourceimage{Learning_Win7_Welcome_File_Whole,,,}

From the menus that appear alonbg the top of the example file,
select @w{@code{File > Save as}}. Do not use the @w{@code{File > Save}}
for the example file as this will not work until you have given it a
valid Lilypong file name.

@sourceimage{Learning_Win7_Save_Menu,,,}

Choose a name for your file, for example @file{test.ly}.

@sourceimage{Learning_Win7_Save_File_With_Name,,,}


@subsubheading Step 2a. Compile (with drag-and-drop)

Depending on what you prefer, to compile your file either:

Drag-and-drop the file directly onto the LilyPond icon.

@sourceimage{Learning_Win7_Open_Dragndrop,,,}

Right-click on the file and from the pop-up context menu choose
@w{@code{Open with > LilyPond}}.

@sourceimage{Learning_Win7_Open_Context_Menu,,,}


@subsubheading Step 2b. Compile (with double-clicking)

Or simply double-click the @file{test.ly}.


@subsubheading Step 3. View output

During the compilation of the @file{test.ly} file, a command window
will, very briefly open and then close. Three additional files will
have been created during this process.

@sourceimage{Learning_Win7_All_Files_Created,,,}

The PDF file contains the engraved @file{test.ly} file.

@sourceimage{Learning_Win7_Pdf_Output,,,}


@subsubheading Other commands

To create a new file, begin by selecting @w{@code{File > New}} from
within any previously created file.

@sourceimage{Learning_Win7_New_Menu,,,}

@noindent
or @w{@code{File > Open}} to open and edit any files you have saved
before.

@sourceimage{Learning_Win7_Open_Menu,,,}

You must save any new edits you make before you compile it and if the
PDF file is not created, check the log file that will have been created
during the compilation attempt, for any errors.

@sourceimage{Learning_Win7_Log_File,,,}

This log file is overwritten each time you compile your LilyPond file.

The PS file is used internally by LilyPond to create the PDF file and
can be ignored. It also gets overwritten each time you compile your
file.

If you are viewing your file in a PDF viewer, then you must close the
PDF if you wish to make a new compilation as it may fail to create
the new PDF while it is still being viewed.


@node Command-line
@subsection Command-line

@warning{These instructions assume that you are familiar with
command-line programs.  If you are using any of the programs
described in @rweb{Alternate input}, please consult the
documentation for those programs if you have any problems
compiling a file.}


@subsubheading Step 1. Create your @file{.ly} file

Create a text file called @file{test.ly} and enter:

@example
@{
  c' e' g' e'
@}
@end example


@subsubheading Step 2. Compile (with command-line)

To process @file{test.ly}, proceed as follows:

@example
lilypond test.ly
@end example

@noindent
You will see something resembling:

@example
lilypond test.ly
GNU LilyPond @version{}
Processing `test.ly'
Parsing...
Interpreting music...
Preprocessing graphical objects...
Finding the ideal number of pages...
Fitting music on 1 page...
Drawing systems...
Layout output to `test.ps'...
Converting to `test.pdf'...
@end example

@subsubheading Step 3. View output

You may view or print the resulting @file{text.pdf}.


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

FIXME: insert text

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


@node Simple notation
@subsection Simple notation

@cindex simple notation
@cindex notation, simple

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.


@subheading 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]
% set the starting point to middle C
\relative c' {
  c d e f
  g a b c
}
@end lilypond

The initial note is @notation{middle 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 c' {
  d f a g
  c b f d
}
@end lilypond

@noindent
It is not necessary for the first note of the melody to start on
the note which specifies the starting pitch.  In the previous
example, the first note -- the @code{d} -- is the closest D to
middle C.

By adding (or removing) quotes @code{'} or commas @code{,} from
the @code{@w{\relative c' @{}} command, we can change the starting
octave:

@lilypond[verbatim,quote]
% one octave above middle C
\relative c'' {
  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 c'' {
  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 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{@w{\relative c'}} may also be modified like
this.
@c " - keeps quotes in order for context-sensitive editor -td

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

@lilypond[verbatim,quote]
\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

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 c'' {
  a a a4. a8
  a8. a16 a a8. a8 a4.
}
@end lilypond


@subheading 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 c'' {
  a r r2
  r8 a r4 r4. r8
}
@end lilypond


@subheading 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 c'' {
  \time 3/4
  a4 a a
  \time 6/8
  a4. a
  \time 4/4
  a4 a a a
}
@end lilypond


@subheading 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 c' {
  \clef treble
  c1
  \clef alto
  c1
  \clef tenor
  c1
  \clef bass
  c1
}
@end lilypond


@subheading All together

Here is a small example showing all these elements together:

@lilypond[verbatim,quote]
\relative c, {
  \time 3/4
  \clef bass
  c2 e8 c' g'2.
  f4 e d c4 c, r4
}
@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

@funindex { ... }
@funindex %
@funindex %@{ ... %@}

LilyPond input files are similar to source files in many common
programming languages.  They are case sensitive, and white-space
is generally ignored.  Expressions are formed with curly braces
@{ @}, and comments are denoted with @code{%} or
@w{@code{%@{ ... %@}}}.

If the previous sentences sound like nonsense, don't worry!  We'll
explain what all these terms mean:

@itemize

@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{@code{@{ c d e @}}} is valid input;
@w{@code{@{ 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{@code{@{ c d e @}}} means the same thing as
@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:

@example
@{ c                        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 either a tab or two spaces:

@example
@{
  c 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 it cannot be @emph{eliminated}.  As 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{@{ curly
braces @}} 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 @w{@code{\relative @{ @}}}) 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.

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

@end itemize


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

FIXME: fluff here

@menu
* Omitting braces::             
* Clickable examples::          
* Keyboard navigation::         
* Overview of manuals::         
@end menu


@node Omitting braces
@subsection Omitting braces


@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 @{ @} marks or a
@code{@w{\relative c'' @{ ... @}}}, 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 you @strong{must} add the
@code{@w{\relative c'' @{ @}}} like this:

@example
\relative c'' @{
  ... example goes here...
@}
@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 @code{@w{\relative c'' @{ @}}} --
you should not place a @code{\relative} inside another
@code{\relative}!  If we included @code{@w{\relative c'' @{ @}}}
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.


@node Clickable examples
@subsection Clickable examples

@warning{This features 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'' {
  c-\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.


@node Keyboard navigation
@subsection 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.


@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 Usage document's
@rprogram{Suggestions for writing files}.

@end itemize