Merge branch 'master' of /home/lilycvs/git/lily/

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

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index eee42edf36c931903cca77068e23f7670c55c6b5..119092e3e4d16f87146dd669c0da9eab3340d039 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -31,8 +31,9 @@ Tutorial guidelines:  (different from policy.txt!)
 @chapter Tutorial
 
 This tutorial starts with an introduction to the LilyPond music
 @chapter Tutorial
 
 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.
+language and explains how to produce printed music.  After this first
+contact we will explain how to create beautiful printed music 
+containing common musical notation.

 
 @menu
 * First steps::                 
 
 @menu
 * First steps::                 


@@ -59,7 +60,11 @@ This section gives a basic introduction to working with LilyPond.
 @node Compiling a file
 @subsection Compiling a file
 
 @node Compiling a file
 @subsection Compiling a file
 

-The first example demonstrates how to start working with LilyPond.
+@qq{Compiling} is the term used for processing an input text file
+in LilyPond format to produce a file which can be printed and
+(optionally) a MIDI file which can be played.  The first example
+shows what a simple input text file looks like.
+

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


@@ -79,8 +84,8 @@ the result looks like this:
 }
 @end lilypond
 
 }
 @end lilypond
 

-@warning{Every piece of LilyPond input needs to have
-@strong{@{ curly braces @}} placed around the input.  The braces
+@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
 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


@@ -106,7 +111,7 @@ Note that there are several other text editors available with
 better support for LilyPond.  For more information, see
 @rprogram{Text editor support}.
 
 better support for LilyPond.  For more information, see
 @rprogram{Text editor support}.
 

-@warning{the first time you ever run LilyPond, it may take a
+@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!}
 
 minute or two because all of the system fonts have to be analyzed
 first.  After this, LilyPond will be much faster!}
 


@@ -138,16 +143,19 @@ 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
 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.
+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.
 
 
 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.
 

-@subsubheading Unix
+@subsubheading UNIX

 
 

-Create a file (such as @file{test.ly}) and enter:
+Create a text file called @file{test.ly} and enter:

 
 @example
 @{
 
 @example
 @{


@@ -252,7 +260,7 @@ 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
 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 F it will be assumed to be
+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,ragged-right]
 above the B, and an A, G or F will be assumed to be below.
 
 @lilypond[verbatim,quote,ragged-right]


@@ -260,9 +268,9 @@ above the B, and an A, G or F will be assumed to be below.
   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 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 4 up or 3 down, so is the a below
+  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 g  % g is 5 up or 2 down, so is the g below

-  b f  % f is 6 up or 1 down, so is the f below
+  b f  % f is 4 up or 3 down, so is the f below

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -290,7 +298,7 @@ To change a note by two (or more!) octaves, we use multiple
 quotes @code{''} and not one double quote @code{"}@tie{}!  The
 initial value in @code{\relative c'} may also be modified like
 this.
 quotes @code{''} and not one double quote @code{"}@tie{}!  The
 initial value in @code{\relative c'} may also be modified like
 this.

-
+@c " - keeps quotes in order for context-sensitive editor -td

 
 @subheading Durations (rhythms)
 
 
 @subheading Durations (rhythms)
 


@@ -407,7 +415,7 @@ Notation Reference: @ruser{Writing pitches},
 
 LilyPond input files are similar to source files in many common
 programming languages.  They are case sensitive, and white-space
 
 LilyPond input files are similar to source files in many common
 programming languages.  They are case sensitive, and white-space

-is generally equivalent.  Expressions are formed with curly braces
+is generally ignored.  Expressions are formed with curly braces

 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
 %@}}.
 
 @{ @}, and comments are denoted with @code{%} or @code{%@{ ...
 %@}}.
 


@@ -454,8 +462,9 @@ that the input is a single music expression, just like parentheses
 space unless they are at the beginning or end of a line to avoid
 ambiguities.
 
 space unless they are at the beginning or end of a line to avoid
 ambiguities.
 

-A function (such as @code{\relative @{ @}}) also counts as a
-single music expression.
+A LilyPond command followed by a simple expression in braces (such
+as @code{\relative @{ @}}) also counts as a single music 
+expression.

 
 @cindex comments
 @cindex line comment
 
 @cindex comments
 @cindex line comment


@@ -466,10 +475,22 @@ 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
 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.  A block comment marks a whole section of
-music input as a comment.  Anything that is enclosed in @code{%@{}
-and @code{%@}} is ignored.  (Comments do not nest.)  The following
-fragment shows possible uses for comments:
+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
 
 @example
 % notes for twinkle twinkle follow


@@ -538,7 +559,8 @@ cut-&-pastable section} to the bottom of the file.
 
 
 There are more tips for constructing input files in
 
 
 There are more tips for constructing input files in

-@ref{Suggestions for writing LilyPond files}.
+@ref{Suggestions for writing LilyPond files}.  But it might be
+best to read through the rest of the tutorial first.

 
 
 
 
 
 


@@ -609,7 +631,7 @@ note's @notation{pitch}!  This is a feature that often causes
 confusion to newcomers, so let us explain it in more detail.
 
 LilyPond makes a sharp distinction between musical content and
 confusion to newcomers, so let us explain it in more detail.
 
 LilyPond makes a sharp distinction between musical content and

-layout.  The alteration (@notation{flat}, @notation{natural} or
+layout.  The alteration (@notation{flat}, @notation{natural sign} or

 @notation{sharp}) of a note is part of the pitch, and is therefore
 musical content.  Whether an accidental (a @emph{printed} flat,
 natural or sharp sign) is printed in front of the corresponding
 @notation{sharp}) of a note is part of the pitch, and is therefore
 musical content.  Whether an accidental (a @emph{printed} flat,
 natural or sharp sign) is printed in front of the corresponding


@@ -627,8 +649,8 @@ d cis fis
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-No note has a printed accidental, but you must still add the
-@code{is} to @code{cis} and @code{fis}.
+No note has a printed accidental, but you must still add
+@code{is} and type @code{cis} and @code{fis} in the input file.

 
 The code @code{e} does not mean @qq{print a black dot just below
 the first line of the staff.}  Rather, it means @qq{there is a
 
 The code @code{e} does not mean @qq{print a black dot just below
 the first line of the staff.}  Rather, it means @qq{there is a


@@ -689,12 +711,12 @@ d4( c16) cis( d e c cis d) e( d4)
 @cindex phrasing slurs
 @subheading Phrasing slurs
 
 @cindex phrasing slurs
 @subheading Phrasing slurs
 

-Music Glossary: @rglos{phrasing}, @rglos{legato}.
+Music Glossary: @rglos{slurs}, @rglos{phrasing}.

 
 Slurs to indicate longer @notation{phrasing} can be entered with
 
 Slurs to indicate longer @notation{phrasing} can be entered with

-@code{\(} and @code{\)}.  You can have both @notation{legato}
-slurs and phrasing slurs at the same time, but you cannot have
-simultaneous legato slurs or simultaneous phrasing slurs.
+@code{\(} and @code{\)}.  You can have both @notation{slurs}
+and phrasing slurs at the same time, but you cannot have
+simultaneous slurs or simultaneous phrasing slurs.

 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a8(\( ais b c) cis2 b'2 a4 cis,\)
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 a8(\( ais b c) cis2 b'2 a4 cis,\)


@@ -780,8 +802,8 @@ c\ff c\mf c\p c\pp
 @cindex crescendo
 
 @notation{Crescendi} and @notation{decrescendi} are started with
 @cindex crescendo
 
 @notation{Crescendi} and @notation{decrescendi} are started with

-the commands @code{\<} and @code{\>}.  An ending dynamic, for
-example @code{\f}, will finish the (de)crescendo, or the command
+the commands @code{\<} and @code{\>}.  The next dynamics sign, for
+example @code{\f}, will end the (de)crescendo, or the command

 @code{\!} can be used:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 @code{\!} can be used:
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]


@@ -790,7 +812,7 @@ c2\< c2\ff\> c2 c2\!
 
 @seealso
 
 
 @seealso
 

-Notation Reference: @ruser{Articulations},
+Notation Reference: @ruser{Articulations and ornamentations},

 @ruser{Fingering instructions}, @ruser{Dynamics}.
 
 
 @ruser{Fingering instructions}, @ruser{Dynamics}.
 
 


@@ -887,7 +909,7 @@ Triplets make notes occupy 2/3 of their notated duration, so a
 @cindex appoggiatura
 @subheading Grace notes
 
 @cindex appoggiatura
 @subheading Grace notes
 

-Music Glossary: @rglos{grace notes}, @rglos{acciacccatura},
+Music Glossary: @rglos{grace notes}, @rglos{acciaccatura},

 @rglos{appoggiatura}.
 
 @notation{Grace notes} are created with the @code{\grace} command,
 @rglos{appoggiatura}.
 
 @notation{Grace notes} are created with the @code{\grace} command,


@@ -958,8 +980,8 @@ one).  The result is another music expression:
 
 This mechanism is similar to mathematical formulas: a big formula
 is created by composing small formulas.  Such formulas are called
 
 This mechanism is similar to mathematical formulas: a big formula
 is created by composing small formulas.  Such formulas are called

-expressions, and they can contain other music expressions, so you
-can make arbitrarily complex and large expressions.  For example,
+expressions, and they can contain other expressions, so you can
+make arbitrarily complex and large expressions.  For example,

 
 @example
 1
 
 @example
 1


@@ -1010,15 +1032,15 @@ LilyPond code like this makes it much easier for humans to read.
 
 @warning{each note is relative to the previous note in
 the input, not relative to the @code{c''} in the initial
 
 @warning{each note is relative to the previous note in
 the input, not relative to the @code{c''} in the initial

-@code{\\relative} command.}
+@code{@bs{}relative} command.}

 
 
 @subheading Simultaneous music expressions: single staff
 
 To determine the number of staves in a piece, LilyPond looks at
 
 
 @subheading Simultaneous music expressions: single staff
 
 To determine the number of staves in a piece, LilyPond looks at

-the first expression.  If it is a single note, there is one staff;
-if there is a simultaneous expression, there is more than one
-staff.
+the beginning of the first expression.  If is a single note, there
+is one staff; if there is a simultaneous expression, there is more
+than one staff.

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -1065,13 +1087,11 @@ creates a bigger music expression.  In this way it resembles the
 minus sign in mathematics.  The formula @math{(4+5)} is an
 expression, so @math{-(4+5)} is a bigger expression.
 
 minus sign in mathematics.  The formula @math{(4+5)} is an
 expression, so @math{-(4+5)} is a bigger expression.
 

-Time signatures entered in one staff affect all other
-staves@footnote{This behavior may be changed if desired; for
-details, see @ruser{Polymetric notation}.}.  On the other hand,
-the key signature of one staff does @emph{not} affect other
-staves.  This different default behaviour is because scores with
-transposing instruments are more common than polyrhythmic
-scores.
+Time signatures entered in one staff affects all other staves by
+default.  On the other hand, the key signature of one staff does
+@emph{not} affect other staves.  This different default behavior
+is because scores with transposing instruments are more common
+than polyrhythmic scores.

 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {
 
 @lilypond[verbatim,quote,ragged-right]
 \relative c'' {


@@ -1124,7 +1144,7 @@ scores, and @code{\new ChoirStaff,} suitable for
 vocal scores.  These staff groups each form another
 type of context, one that generates the brace at the
 left end of every system and also controls the extent
 vocal scores.  These staff groups each form another
 type of context, one that generates the brace at the
 left end of every system and also controls the extent

-of barlines.
+of bar lines.

 
 @seealso
 
 
 @seealso
 


@@ -1139,10 +1159,12 @@ Notation Reference: @ruser{Piano music},
 
 Music Glossary: @rglos{chord}.
 
 
 Music Glossary: @rglos{chord}.
 

-@notation{Chords} can be made by surrounding pitches with single
-angle brackets.  Note that all the notes in a chord must have the
-same duration, and that duration is placed after the closing 
-bracket. 
+We saw earlier how notes can be combined into @notation{chords} by
+indicating they are simultaneous by enclosing them in double angle
+brackets.  However, the normal way of indicating a chord is to
+surround the pitches with @emph{single} angle brackets.  Note that
+all the notes in a chord must have the same duration, and that the
+duration is placed after the closing bracket.

 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 r4 <c e g>4 <c f a>2
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 r4 <c e g>4 <c f a>2


@@ -1150,16 +1172,13 @@ r4 <c e g>4 <c f a>2
 
 Think of chords as almost equivalent to single notes:
 almost everything you can attach to a single note can be attached
 
 Think of chords as almost equivalent to single notes:
 almost everything you can attach to a single note can be attached

-to a chord, and everything must go @emph{outside} the angle 
-brackets.  For example, you can combine markings like beams and 
+to a chord, and everything must go @emph{outside} the angle
+brackets.  For example, you can combine markings like beams and

 ties with chords.  They must be placed outside the angle brackets.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 r4 <c e g>8[ <c f a>]~ <c f a>2
 ties with chords.  They must be placed outside the angle brackets.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
 r4 <c e g>8[ <c f a>]~ <c f a>2

-@end lilypond
-
-@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
+r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)

 @end lilypond
 
 
 @end lilypond
 
 


@@ -1328,7 +1347,7 @@ Here we have also used manual beaming (the square brackets @code{[
 (see @ref{Automatic and manual beams}).
 
 As an alternative to using slurs, the melismata may be indicated
 (see @ref{Automatic and manual beams}).
 
 As an alternative to using slurs, the melismata may be indicated

-just in the lyrics by using an underscore, @code{_}, for each
+in just the lyrics by using an underscore, @code{_}, for each

 note that should be included in the melisma:
 
 @lilypond[verbatim,quote,ragged-right]
 note that should be included in the melisma:
 
 @lilypond[verbatim,quote,ragged-right]


@@ -1455,7 +1474,7 @@ example from Handel's Judas Maccabæus:
 @noindent
 but scores any more complex than this simple example are
 better produced by separating out the staff structure
 @noindent
 but scores any more complex than this simple example are
 better produced by separating out the staff structure

-from the notes and lyrics with variables.  These
+from the notes and lyrics with variables.  These are

 discussed in @ref{Organizing pieces with variables}.
 
 @seealso
 discussed in @ref{Organizing pieces with variables}.
 
 @seealso


@@ -1565,7 +1584,7 @@ The @code{\version} statement records the version of LilyPond that
 was used to write the file:
 
 @example
 was used to write the file:
 
 @example

-\version "2.11.23"
+\version @w{"@version{}"}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1587,7 +1606,7 @@ main music expression; the @code{\header} block is usually placed
 underneath the @ref{Version number}.
 
 @example
 underneath the @ref{Version number}.
 
 @example

-\version "2.11.23"
+\version @w{"@version{}"}

 \header @{
   title = "Symphony"
   composer = "Me"
 \header @{
   title = "Symphony"
   composer = "Me"


@@ -1702,3 +1721,4 @@ you have more experience.
 
 
 
 
 
 

+