X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftutorial.itely;h=27084f32eab12e95ac29cef38e2cda32ea92edcc;hb=90e4d7057f3857da049dfda3d130017d4719bd6b;hp=df1456d7a685e840ee7ac982f6ce28e34fe5e557;hpb=335d0e8adacbc2c31909aa51d705519718c58e2a;p=lilypond.git

diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely
index df1456d7a6..27084f32ea 100644
--- a/Documentation/learning/tutorial.itely
+++ b/Documentation/learning/tutorial.itely
@@ -10,7 +10,7 @@
 
 @include included/generating-output.itexi
 
-@c \version "2.12.0"
+@c \version "2.19.21"
 
 @node Tutorial
 @chapter Tutorial
@@ -20,6 +20,7 @@ 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
 
@@ -44,6 +45,10 @@ LilyPond input files (written by you) to produce output files.
 @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
@@ -76,13 +81,14 @@ 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
+@w{@samp{@{ c d e @}}} is valid input; @w{@samp{@{ C D E @}}} will
 produce an error message.
 
 
 @smallspace
 
-@subheading Producing output
+@node Producing output
+@unnumberedsubsubsec Producing output
 
 @cindex PDF file
 @cindex viewing music
@@ -164,6 +170,16 @@ started writing input files.
 @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.
@@ -179,7 +195,8 @@ This behavior may be altered, but in most cases these automatic
 values are useful.
 
 
-@subheading Pitches
+@node Pitches
+@unnumberedsubsubsec Pitches
 
 @cindex pitches
 @cindex relative mode
@@ -189,7 +206,6 @@ values are useful.
 @cindex relative mode, and accidentals
 
 @funindex \relative
-@funindex relative
 @funindex '
 @funindex ,
 
@@ -197,6 +213,16 @@ Music Glossary: @rglos{pitch}, @rglos{interval},
 @rglos{scale}, @rglos{middle C}, @rglos{octave},
 @rglos{accidental}.
 
+LilyPond uses lower-case letters for pitches.  The letters
+@code{c} through@tie{}@code{b} denote pitches in the
+@q{small octave} below @notation{middle C}.  Added @code{'}
+or@tie{}@code{,} suffixes indicate higher or lower octaves.
+Here is a scale starting on @notation{middle C}, and an arpeggio:
+
+@lilypond[verbatim,quote]
+{ c' d' e' f' g' a' b' c'' g c' e' g' c'' e'' g'' c''' }
+@end lilypond
+
 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
@@ -206,40 +232,37 @@ 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
+\relative {
+  c' d e f
   g a b c
 }
 @end lilypond
 
-The initial note is @notation{middle C}.  Each successive note is
+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 c' {
-  d f a g
+\relative {
+  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.
+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 @code{@w{\relative c' @{}} command, we can change the starting
-octave:
+the first note, we can change the starting octave:
 
 @lilypond[verbatim,quote]
-% one octave above middle C
-\relative c'' {
-  e c a c
+\relative {
+  e'' c a c
 }
 @end lilypond
 
@@ -252,8 +275,8 @@ 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
+\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
@@ -274,8 +297,8 @@ 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,
+\relative {
+  a' a, c' f,
   g g'' a,, f'
 }
 @end lilypond
@@ -283,12 +306,11 @@ comma @code{,} to the note name.
 @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.
+quotes @code{''} and not one double quote @code{"}@tie{}!
 @c " - keeps quotes in order for context-sensitive editor -td
 
-@subheading Durations (rhythms)
+@node Durations (rhythms)
+@unnumberedsubsubsec Durations (rhythms)
 
 @cindex note durations
 @cindex durations
@@ -310,11 +332,11 @@ 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.
+quarter note.
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  a1
+\relative {
+  a'1
   a2 a4 a8 a
   a16 a a a a32 a a a a64 a a a a a a a a2
 }
@@ -325,14 +347,14 @@ 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
+\relative {
+  a'4 a a4. a8
   a8. a16 a a8. a8 a4.
 }
 @end lilypond
 
-
-@subheading Rests
+@node Rests
+@unnumberedsubsubsec Rests
 
 @cindex rest
 @cindex notating rests
@@ -343,19 +365,19 @@ A @notation{rest} is entered just like a note with the name
 @code{r}@tie{}:
 
 @lilypond[verbatim,quote]
-\relative c'' {
-  a r r2
+\relative {
+  a'4 r r2
   r8 a r4 r4. r8
 }
 @end lilypond
 
 
-@subheading Time signature
+@node Time signature
+@unnumberedsubsubsec Time signature
 
 @cindex time signature
 
 @funindex \time
-@funindex time
 
 Music Glossary: @rglos{time signature}.
 
@@ -363,18 +385,46 @@ The @notation{time signature} can be set with the @code{\time}
 command:
 
 @lilypond[verbatim,quote]
-\relative c'' {
+\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
+
+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
-  a4 a a
+  \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
 
 
-@subheading Clef
+@node Clef
+@unnumberedsubsubsec Clef
 
 @cindex clef
 @cindex treble
@@ -383,36 +433,39 @@ command:
 @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
+\relative {
+  \clef "treble"
+  c'1
+  \clef "alto"
   c1
-  \clef tenor
+  \clef "tenor"
   c1
-  \clef bass
+  \clef "bass"
   c1
 }
 @end lilypond
 
 
-@subheading All together
+@node All together
+@unnumberedsubsubsec All together
 
 Here is a small example showing all these elements together:
 
 @lilypond[verbatim,quote]
-\relative c, {
+\relative {
+  \clef "bass"
   \time 3/4
-  \clef bass
-  c2 e8 c' g'2.
-  f4 e d c4 c, r4
+  \tempo "Andante" 4 = 120
+  c,2 e8 c'
+  g'2.
+  f4 e d
+  c4 c, r
 }
 @end lilypond
 
@@ -446,11 +499,10 @@ Notation Reference: @ruser{Writing pitches},
 @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
-@{ @}, and comments are denoted with @code{%} or
-@w{@code{%@{ ... %@}}}.
+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:
@@ -481,50 +533,51 @@ 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{@code{@{ c d e @}}} is valid input;
-@w{@code{@{ C D E @}}} will produce an error message.
+@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{@code{@{ c d e @}}} means the same thing as
-@w{@code{@{ c @tie{}} @tie{} @tie{} d e @}} and:
+@w{@samp{@{ c4 d e @}}} means the same thing as
+@w{@samp{@{ c4 @tie{} @tie{} @tie{} d e @}}} and:
 
 @example
-@{ c                        d
+@{ 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 either a tab or two spaces:
+thumb is to indent code blocks with two spaces:
 
 @example
 @{
-  c d e
+  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 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.
+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{@{ 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.
+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 @w{@code{\relative @{ @}}}) also counts as a single music
-expression.
+as @q{@w{@code{@bs{}relative @{ @dots{} @}}}}) also counts as a
+single music expression.
 
 @cindex comments
 @cindex line comment
@@ -560,13 +613,50 @@ comments:
   This line, and the notes below are ignored,
   since they are in a block comment.
 
-  f f e e d d c2
+  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
 
@@ -577,7 +667,6 @@ online version.
 @menu
 * Omitted material::
 * Clickable examples::
-* Keyboard navigation::
 * Overview of manuals::
 @end menu
 
@@ -596,33 +685,23 @@ online version.
 @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:
+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,
+some short examples will omit this.  To replicate these examples,
+you can copy displayed input, but paste it between @code{@{}
+and @code{@}} in your input file.
 
 @example
-\relative c'' @{
-  ... example goes here...
+@{
+  @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 @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.
-
-Also, remember that every LilyPond file should have a @code{@bs{}version}
-statement.  Because the examples in the manuals are snippets, not files,
-the @code{@bs{}version} statement is omitted.  But you should make a
-practice of including them in your files.
+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
@@ -637,8 +716,8 @@ this image:
 
 @c no verbatim here
 @lilypond[quote]
-\relative c'' {
-  c-\markup { \bold \huge { Click here.  } }
+\relative {
+  c''4-\markup { \bold \huge { Click here. } }
 }
 @end lilypond
 
@@ -648,15 +727,18 @@ 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
+@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
@@ -688,8 +770,8 @@ may want to look in relevant sections of the
 Learning manual's @ref{Tweaking output}.
 
 @item
-@strong{Before undertaking a large project}: read Usage document's
-@rprogram{Suggestions for writing files}.
+@strong{Before undertaking a large project}: read the Usage
+document's @rprogram{Suggestions for writing files}.
 
 @end itemize