Doc-fr: updates NR-Staff

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

diff --git a/Documentation/learning/tutorial.itely b/Documentation/learning/tutorial.itely
index ce20863b0fa7e9c6a9fe0a4fa823168f31395995..27084f32eab12e95ac29cef38e2cda32ea92edcc 100644 (file)
--- a/Documentation/learning/tutorial.itely
+++ b/Documentation/learning/tutorial.itely
@@ -4,10 +4,13 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     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.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..

 @end ignore
 
 @end ignore
 

-@c \version "2.12.0"
+@include included/generating-output.itexi
+
+@c \version "2.19.21"

 
 @node Tutorial
 @chapter Tutorial
 
 @node Tutorial
 @chapter Tutorial


@@ -15,9 +18,10 @@
 This chapter gives a basic introduction to working with LilyPond.
 
 @menu
 This chapter gives a basic introduction to working with LilyPond.
 
 @menu

-* Compiling a file::            
-* How to write input files::    
-* How to read the manuals::     
+* Compiling a file::
+* How to write input files::
+* Dealing with errors::
+* How to read the manuals::

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


@@ -27,10 +31,10 @@ This section introduces @qq{compiling}---the processing of
 LilyPond input files (written by you) to produce output files.
 
 @menu
 LilyPond input files (written by you) to produce output files.
 
 @menu

-* Entering input::              
-* MacOS X::                     
-* Windows::                     
-* Command-line::                
+* Entering input::
+* MacOS X::
+* Windows::
+* Command-line::

 @end menu
 
 @node Entering input
 @end menu
 
 @node Entering input


@@ -41,6 +45,10 @@ LilyPond input files (written by you) to produce output files.
 @cindex example, first
 @cindex case sensitive
 
 @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
 @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


@@ -49,6 +57,7 @@ PNG (for online use).  LilyPond input files are simple text files.
 This example shows a simple input file:
 
 @example
 This example shows a simple input file:
 
 @example

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

 @{
   c' e' g' e'
 @}
 @{
   c' e' g' e'
 @}


@@ -72,24 +81,18 @@ 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}.
 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
 
 produce an error message.
 
 
 @smallspace
 

-@subheading Producing output
+@node Producing output
+@unnumberedsubsubsec Producing output

 
 

-@c TODO: move index entries

 @cindex PDF file
 @cindex viewing music
 @cindex text editors
 @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.
 
 The method of producing output depends on your operating system
 and the program(s) you use.


@@ -116,7 +119,7 @@ and the program(s) you use.
 
 There are several other text editors available with specific
 support for LilyPond.  For more information, see
 
 There are several other text editors available with specific
 support for LilyPond.  For more information, see

-@rweb{Alternate input}.
+@rweb{Easier editing}.

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


@@ -126,211 +129,28 @@ first.  After this, LilyPond will be much faster!}
 @node MacOS X
 @subsection MacOS X
 
 @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.
+@cindex running LilyPond under MacOS X
+@cindex MacOS X, running LilyPond

 
 

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

 
 
 @node Windows
 @subsection Windows
 
 
 
 @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.
+@cindex running LilyPond under Windows
+@cindex Windows, running LilyPond

 
 

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

 
 
 @node Command-line
 @subsection Command-line
 
 
 
 @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}.
+@cindex running LilyPond under Unix
+@cindex Unix, running LilyPond

 
 

+@lilypadCommandLine

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


@@ -339,8 +159,8 @@ This section introduces some basic LilyPond syntax to help get you
 started writing input files.
 
 @menu
 started writing input files.
 
 @menu

-* Simple notation::             
-* Working on input files::      
+* Simple notation::
+* Working on input files::

 @end menu
 
 
 @end menu
 
 


@@ -350,6 +170,16 @@ started writing input files.
 @cindex simple notation
 @cindex notation, simple
 
 @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.
 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.


@@ -365,7 +195,8 @@ This behavior may be altered, but in most cases these automatic
 values are useful.
 
 
 values are useful.
 
 

-@subheading Pitches
+@node Pitches
+@unnumberedsubsubsec Pitches

 
 @cindex pitches
 @cindex relative mode
 
 @cindex pitches
 @cindex relative mode


@@ -375,7 +206,6 @@ values are useful.
 @cindex relative mode, and accidentals
 
 @funindex \relative
 @cindex relative mode, and accidentals
 
 @funindex \relative

-@funindex relative

 @funindex '
 @funindex ,
 
 @funindex '
 @funindex ,
 


@@ -383,6 +213,16 @@ Music Glossary: @rglos{pitch}, @rglos{interval},
 @rglos{scale}, @rglos{middle C}, @rglos{octave},
 @rglos{accidental}.
 
 @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
 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


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

-% one octave above middle C
-\relative c'' {
-  e c a c
+\relative {
+  e'' c a c

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -438,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]
 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
   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


@@ -460,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]
 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
   g g'' a,, f'
 }
 @end lilypond


@@ -469,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
 @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
 
 @c " - keeps quotes in order for context-sensitive editor -td
 

-@subheading Durations (rhythms)
+@node Durations (rhythms)
+@unnumberedsubsubsec Durations (rhythms)

 
 @cindex note durations
 @cindex durations
 
 @cindex note durations
 @cindex durations


@@ -496,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
 
 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]
 
 @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
 }
   a2 a4 a8 a
   a16 a a a a32 a a a a64 a a a a a a a a2
 }


@@ -511,14 +347,14 @@ duration number.  The duration of a dotted note must be stated
 explicitly (i.e., with a number).
 
 @lilypond[verbatim,quote]
 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
 
   a8. a16 a a8. a8 a4.
 }
 @end lilypond
 

-
-@subheading Rests
+@node Rests
+@unnumberedsubsubsec Rests

 
 @cindex rest
 @cindex notating rests
 
 @cindex rest
 @cindex notating rests


@@ -529,19 +365,19 @@ A @notation{rest} is entered just like a note with the name
 @code{r}@tie{}:
 
 @lilypond[verbatim,quote]
 @code{r}@tie{}:
 
 @lilypond[verbatim,quote]

-\relative c'' {
-  a r r2
+\relative {
+  a'4 r r2

   r8 a r4 r4. r8
 }
 @end lilypond
 
 
   r8 a r4 r4. r8
 }
 @end lilypond
 
 

-@subheading Time signature
+@node Time signature
+@unnumberedsubsubsec Time signature

 
 @cindex time signature
 
 @funindex \time
 
 @cindex time signature
 
 @funindex \time

-@funindex time

 
 Music Glossary: @rglos{time signature}.
 
 
 Music Glossary: @rglos{time signature}.
 


@@ -549,9 +385,9 @@ The @notation{time signature} can be set with the @code{\time}
 command:
 
 @lilypond[verbatim,quote]
 command:
 
 @lilypond[verbatim,quote]

-\relative c'' {
+\relative {

   \time 3/4
   \time 3/4

-  a4 a a
+  a'4 a a

   \time 6/8
   a4. a
   \time 4/4
   \time 6/8
   a4. a
   \time 4/4


@@ -559,8 +395,36 @@ command:
 }
 @end lilypond
 
 }
 @end lilypond
 

+@node Tempo marks
+@unnumberedsubsubsec Tempo marks
+
+@cindex tempo marks
+@cindex metronome marks
+
+@funindex \tempo

 
 

-@subheading Clef
+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
+  \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
+
+
+@node Clef
+@unnumberedsubsubsec Clef

 
 @cindex clef
 @cindex treble
 
 @cindex clef
 @cindex treble


@@ -569,36 +433,39 @@ command:
 @cindex bass
 
 @funindex \clef
 @cindex bass
 
 @funindex \clef

-@funindex clef

 
 Music Glossary: @rglos{clef}.
 
 The @notation{clef} can be set using the @code{\clef} command:
 
 @lilypond[verbatim,quote]
 
 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
   c1

-  \clef tenor
+  \clef "tenor"

   c1
   c1

-  \clef bass
+  \clef "bass"

   c1
 }
 @end lilypond
 
 
   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]
 
 Here is a small example showing all these elements together:
 
 @lilypond[verbatim,quote]

-\relative c, {
+\relative {
+  \clef "bass"

   \time 3/4
   \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
 
 }
 @end lilypond
 


@@ -622,69 +489,95 @@ Notation Reference: @ruser{Writing pitches},
 @cindex case sensitive
 @cindex whitespace insensitive
 @cindex expressions
 @cindex case sensitive
 @cindex whitespace insensitive
 @cindex expressions

+@cindex versioning
+@cindex version
+@cindex version number

 
 

+@funindex \version

 @funindex { ... }
 @funindex %
 @funindex %@{ ... %@}
 
 LilyPond input files are similar to source files in many common
 @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{%@{ ... %@}}}.
+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:
 
 @itemize
 
 
 If the previous sentences sound like nonsense, don't worry!  We'll
 explain what all these terms mean:
 
 @itemize
 

+@item
+@strong{Version statement}:
+Every LilyPond file should contain a version statement.  A version
+statement is a line that describes the version of LilyPond for which
+the file was written, as in the following example:
+
+@example
+\version "@w{@version{}}"
+@end example
+
+By convention, the version statement is placed at the top of the
+LilyPond file.
+
+The version statement is important for at least two reasons.  First,
+it allows automatic updating of the input file as LilyPond syntax
+changes.  Second, it describes the version of LilyPond needed to
+compile the file.
+
+If the version statement is omitted from an input file, LilyPond will print
+a warning during the compilation of the file.
+

 @item
 @strong{Case sensitive}:
 it matters whether you enter a letter in lower case (e.g.
 @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.
 
 @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
 
 @example

-@{ c                        d
+@{ c4                       d

                    e   @}
 @end example
 
 @noindent
 Of course, the previous example is hard to read.  A good rule of
                    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
 @{
 
 @example
 @{

-  c d e
+  c4 d e

 @}
 @end example
 
 @}
 @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}:
 
 @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
 
 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
 
 @cindex comments
 @cindex line comment


@@ -720,13 +613,50 @@ comments:
   This line, and the notes below are ignored,
   since they are in a block comment.
 
   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
 
 
 %@}
 @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
 
 @node How to read the manuals
 @section How to read the manuals
 


@@ -735,15 +665,14 @@ also introduces some useful interactive features available in the
 online version.
 
 @menu
 online version.
 
 @menu

-* Omitting braces::             
-* Clickable examples::          
-* Keyboard navigation::         
-* Overview of manuals::         
+* Omitted material::
+* Clickable examples::
+* Overview of manuals::

 @end menu
 
 
 @end menu
 
 

-@node Omitting braces
-@subsection Omitting braces
+@node Omitted material
+@subsection Omitted material

 
 
 @cindex how to read the manual
 
 
 @cindex how to read the manual


@@ -756,34 +685,28 @@ online version.
 @cindex constructing files, tips
 @cindex files, tips for constructing
 
 @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
 
 @example

-\relative c'' @{
-  ... example goes here...
+@{
+  @dots{}example goes here@dots{}

 @}
 @end example
 
 @}
 @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{\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
 
 
 @node Clickable examples
 @subsection Clickable examples
 

-@warning{This features is only available in the HTML manuals.}
+@warning{This feature 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
 
 Many people learn programs by trying and fiddling around with the
 program.  This is also possible with LilyPond.  If you click on a


@@ -793,8 +716,8 @@ this image:
 
 @c no verbatim here
 @lilypond[quote]
 
 @c no verbatim here
 @lilypond[quote]

-\relative c'' {
-  c-\markup { \bold \huge { Click here.  } }
+\relative {
+  c''4-\markup { \bold \huge { Click here. } }

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -804,15 +727,18 @@ same output (line-width and all), copy everything from @qq{Start
 cut-&-pastable section} to the bottom of the file.
 
 
 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.
 
 @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
 
 @node Overview of manuals
 @subsection Overview of manuals


@@ -844,8 +770,8 @@ may want to look in relevant sections of the
 Learning manual's @ref{Tweaking output}.
 
 @item
 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
 
 
 @end itemize