Doc: first pass at rearranging the beginning of Learning.

[lilypond.git] / Documentation / learning / generating.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 Generating output
@chapter Generating output

This chapter gives a basic introduction to working with LilyPond.

@menu
* Compiling a file::            
* Alternate editors::           
* 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 a file which can be printed and
(optionally) a MIDI file which can be played.  LilyPond input
files are simple text files.  The first example
shows what a simple input file looks like.

To create sheet music, we write an input file that specifies the
notation.  For example, if we write:

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

@noindent
the result looks like this:

@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 @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.  The braces 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 Entering music and viewing output

@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

In this section we will explain what commands to run and how to
view or print the output.

Note that there are several other text editors available with
better support for LilyPond.  For more information, see
@ref{Alternate editors}.

@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

If you double click @command{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
@w{@code{Compile > Typeset File}}.  The resulting PDF file will be
displayed on your screen.

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.


@node Windows
@subsection Windows

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.

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, or right-click on the desktop and select
@qq{New..Text Document}, change its name to a name of your choice
and change the file extension to @code{.ly}.  Double-click the
icon to type in your LilyPond source code as before.

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.


@node Command-line
@subsection Command-line

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

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

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



@node Alternate editors
@section Alternate editors



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

@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

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


@subheading Clickable examples

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.


@seealso
There are more tips for constructing input files in
@ref{Suggestions for writing LilyPond input files}.  But it might be
best to read through the rest of the tutorial first.