Revert "unstaged change from master"

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

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 266e89236686162056735199f1464a459e3412eb..0bd1a99c4ff0d4517d0de97d0e54fd1cbe565b54 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -7,6 +7,8 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

+@c \version "2.11.38"
+

 @ignore
 Tutorial guidelines:  (different from policy.txt!)
 - unless you have a really good reason, use either
 @ignore
 Tutorial guidelines:  (different from policy.txt!)
 - unless you have a really good reason, use either


@@ -52,18 +54,22 @@ This section gives a basic introduction to working with LilyPond.
 @menu
 * Compiling a file::            
 * Simple notation::             
 @menu
 * Compiling a file::            
 * Simple notation::             

-* Working on text files::       
-* How to read the manual::      
+* Working on input files::
+* How to read the manual::

 @end menu
 
 
 @node Compiling a file
 @subsection Compiling a file
 
 @end menu
 
 
 @node Compiling a file
 @subsection Compiling a file
 

-@qq{Compiling} is the term used for processing an input text file
+@qq{Compiling} is the term used for processing an input file

 in LilyPond format to produce a file which can be printed and
 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.
+(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
 @{
 
 @example
 @{


@@ -81,8 +87,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


@@ -150,7 +156,7 @@ 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.
 
 what LilyPond has done to the file.  If any errors occur, please
 examine this file.
 

-@subsubheading Unix
+@subsubheading UNIX

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


@@ -257,7 +263,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]


@@ -407,8 +413,8 @@ Notation Reference: @ruser{Writing pitches},
 @ruser{Time signature}, @ruser{Clef}.
 
 
 @ruser{Time signature}, @ruser{Clef}.
 
 

-@node Working on text files
-@subsection Working on text files
+@node Working on input files
+@subsection Working on input files

 
 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


@@ -472,13 +478,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.  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:
+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


@@ -500,7 +515,7 @@ fragment shows possible uses for comments:
 @subsection How to read the manual
 
 LilyPond input must be surrounded by @{ @} marks or a
 @subsection How to read the manual
 
 LilyPond input must be surrounded by @{ @} marks or a

-@code{\relative c'' @{ ... @}}, as we saw in @ref{Working on text
+@code{\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{\relative c''
 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{\relative c''


@@ -547,7 +562,7 @@ 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}.  But it might be
+@ref{Suggestions for writing LilyPond input files}.  But it might be

 best to read through the rest of the tutorial first.
 
 
 best to read through the rest of the tutorial first.
 
 


@@ -619,7 +634,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


@@ -699,7 +714,7 @@ 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{slurs}, @rglos{phrasing}.
+Music Glossary: @rglos{slur}, @rglos{phrasing}.

 
 Slurs to indicate longer @notation{phrasing} can be entered with
 @code{\(} and @code{\)}.  You can have both @notation{slurs}
 
 Slurs to indicate longer @notation{phrasing} can be entered with
 @code{\(} and @code{\)}.  You can have both @notation{slurs}


@@ -1018,18 +1033,17 @@ different amount of space.  LilyPond does not care how much (or
 little) space there is at the beginning of a line, but indenting
 LilyPond code like this makes it much easier for humans to read.
 
 little) space there is at the beginning of a line, but indenting
 LilyPond code like this makes it much easier for humans to read.
 

-@c FIXME: number of backslashes?!  works in html but not pdf.

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


@@ -1078,7 +1092,7 @@ expression, so @math{-(4+5)} is a bigger expression.
 
 Time signatures entered in one staff affects all other staves by
 default.  On the other hand, the key signature of one staff does
 
 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 behaviour
+@emph{not} affect other staves.  This different default behavior

 is because scores with transposing instruments are more common
 than polyrhythmic scores.
 
 is because scores with transposing instruments are more common
 than polyrhythmic scores.
 


@@ -1133,7 +1147,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
 


@@ -1148,10 +1162,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


@@ -1159,8 +1175,8 @@ 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]
 ties with chords.  They must be placed outside the angle brackets.
 
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]


@@ -1571,7 +1587,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


@@ -1593,7 +1609,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"


@@ -1708,3 +1724,4 @@ you have more experience.
 
 
 
 
 
 

+