X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=ee0ee87abe533fe4a032da4def61b059b6bfe5e3;hb=87eedcd59f4082cb0841528ad5bc82cb1d1191e3;hp=17196d435a771f3b71e0e299dabdb1f095bfce44;hpb=d3fc38579755043ae89ce4c12a28d8a2adc2da7d;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 17196d435a..ee0ee87abe 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1,5 +1,11 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
+@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 TODO:
 @c   * more details about running lilypond; error messages,
@@ -14,10 +20,9 @@
 @node Tutorial
 @chapter Tutorial
 
-This tutorial starts with a short introduction to the LilyPond music
-language.  After this first contact we will show you how to produce
-printed output.  Then you will be able to create and print your own
-sheets of music.
+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.
 
 @ifhtml
 Many people learn programs by trying and fiddling around with the
@@ -37,12 +42,12 @@ you will probably want to print out or bookmark
 @ifhtml
 the
 @end ifhtml
-@ref{Cheat sheet}, which is a table listing all commands for quick
-reference.
+@ref{Cheat sheet}, which is a table listing of the most common
+commands for quick reference.
 
 @menu
 * First steps::                 
-* Running LilyPond for the first time::  
+* Second steps::                
 * More about pitches::          
 * Entering ties::               
 * Automatic and manual beams::  
@@ -68,34 +73,143 @@ reference.
 @section First steps
 
 The first example demonstrates how to enter the most elementary piece
-of music, a @rglos{scale}.  A @rglos{note} can be entered by typing its
-name, from @samp{a} through @samp{g}.  So, if you enter
+of music, a @rglos{scale}.  A @rglos{note} can be entered by typing
+its name, from @samp{a} through @samp{g}.  So, if you enter
 
 @example
 @{
-c d e f g a b
+c' d' e' f' g' a' b' c''
 @}
 @end example
 
 @noindent
 the result looks like this
 
-@lilypond[fragment,quote,notime,relative=1]
-c d e f g a b
+@lilypond[quote]
+{
+c' d' e' f' g' a' b' c''
+}
 @end lilypond
 
-Every piece of LilyPond input needs to have @{curly braces@} placed
-around the input.  For the rest of this manual, most examples will
-omit these braces, but don't forget them in your own music!
+@emph{Warning:} Every piece of LilyPond input needs to have @{curly
+braces@} placed around the input.  The braces should be also be
+surrounded by a space unless they are at the beginning or end of a
+line to avoid ambiguities.  These may be omitted in examples in this
+manual, but don't forget them in your own music!
+
+@cindex Case sensitive
+In addition, LilyPond input is case sensitive.  @code{ @{ c d e @} } is
+valid input; @code{ @{ C D E @} } will produce an error message.
+
+
+
+@unnumberedsubsec Entering music and viewing output
+
+In this section we will explain what commands to run
+and how to view or print the output.
+
+@unnumberedsubsubsec MacOS X
+
+If you double click 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 @samp{Compile > Typeset File}.
+The resulting PDF file will be displayed on your screen.
+
+Be warned that the first time you ever run lilypond will take a minute
+or two, because all of the system fonts have to be analyzed first.
+
+For future use of LilyPond, you should begin by selecting "New"
+or "Open".
+
+@unnumberedsubsubsec Windows
+
+On Windows, start up a text-editor@footnote{Any simple or
+programmer-oriented editor with UTF-8 support will do, for example
+Notepad.  Do not use a word processor, since these insert formatting
+codes that will confuse LilyPond.} and enter
+
+@verbatim
+{ c' e' g' c'' }
+@end verbatim
+
+Save it on the desktop as @file{test.ly} and make sure that it is not
+called @file{test.ly.TXT}.  Double clicking @file{test.ly} will process
+the file and show the resulting PDF file.
+
+
+@unnumberedsubsubsec Unix
+
+Begin by opening a terminal window and starting a text editor.  For
+example, you could open an xterm and execute
+@code{joe}@footnote{There are macro files for VIM addicts, and there
+is a @code{LilyPond-mode} for Emacs addicts.  If they have not been
+installed already, refer to the file @file{INSTALL.txt}.}.  In your
+text editor, enter the following input and save the file as
+@file{test.ly}
+
+@verbatim
+{ c' e' g' c'' }
+@end verbatim
+
+@noindent
+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 2.10.0
+Processing `test.ly'
+Parsing...
+Interpreting music... [1]
+Preprocessing graphical objects...
+Calculating line breaks... [2]
+Layout output to `test.ps'...
+Converting to `test.pdf'...
+@end example
+
+@cindex PDF file
+@cindex Viewing music
+
+@noindent
+The result is the file @file{test.pdf} which you can print or view
+with the standard facilities of your operating system.@footnote{If
+your system does not have any tools installed, you can try
+@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
+available package for viewing and printing PDF and PostScript files.}
+
 
+@node Second steps
+@section Second steps
+
+@emph{Remember:} Every piece of LilyPond input needs to have @{curly
+braces@} placed around the input.  The braces should be surrounded by
+a space unless they are at the beginning or end of a line to avoid
+ambiguities.  For the rest of this manual, most examples will omit
+these braces, but don't forget them in your own music!
+
+@c will be removed once the tutorial either explains \relative or
+@c examples are fixed so they don't use it.  -gp
 In addition, many examples use @code{relative} mode.  This is explained
 in @ref{Octave entry}; for now simply be aware that some examples
-should be placed inside @code{\relative @{ @emph{...music...} @}}
+should be placed inside @code{\relative @{ @emph{...music...} @}}.
+Many example have also been compressed horizontally to save
+space, using @code{\paper @{ ragged-right = ##t @}}.
 
 @cindex Case sensitive
 Finally, LilyPond input is case sensitive.  @code{ @{ c d e @} } is
 valid input; @code{ @{ C D E @} } will produce an error message.
 
+@c  End of latest re-write.  Since I have no life, I may do more
+@c  work on this, but I'd really like to have a Doc Helper take
+@c  over this task.  -gp
+
+
 The @rglos{duration} of a note is specified by a number after the note
 name.  @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
 @samp{4} for a @rglos{quarter note} and so on
@@ -153,7 +267,7 @@ command
 
 @c A clef here may lead to confusion, remove it.
 @lilypond[fragment,quote]
-\override Staff.Clef #'transparent = ##t 
+\override Staff.Clef #'transparent = ##t
 \time 3/4
 s4_" "
 \time 6/8
@@ -185,7 +299,6 @@ s16_" "
 Remember to enclose the notes and commands in curly braces
 @code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
 
-@c @li lypond[fragment,quote,noindent,line-width=55\staff-space]
 @lilypond[fragment,quote,noindent,verbatim]
 \time 3/4
 \clef bass
@@ -198,106 +311,23 @@ For more information on
 @quotation
 @table @asis
 @item Entering pitches and durations
-see 
+see
 @ref{Pitches}, and @ref{Durations}.
 @item Clefs
 see @ref{Clef}.
 @item Rests
-see @ref{Rests}.  
+see @ref{Rests}.
 @item Time signatures and other timing commands
 see @ref{Time signature}.
 @end table
 @end quotation
 
 
-@node Running LilyPond for the first time
-@section Running LilyPond for the first time
-
-@c cheesy title to avoid clash with chapter name.
-
-In the last section we explained what kind of things you can enter in
-a LilyPond file.  In this section we will explain what commands to run
-and how to view or print the output.  If you have not used LilyPond
-before, want to test your setup, or want to run an example file
-yourself, read this section.
-
-@unnumberedsubsec MacOS X
-
-If you double click 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 @samp{Compile > Typeset File}.
-The resulting PDF file will be displayed on your screen.
-
-Be warned that the first-ever run will take a minute or two, because
-all of the system fonts have to be analyzed first.
-
-@unnumberedsubsec Windows
-
-On Windows, start up a text-editor@footnote{Any simple or
-programmer-oriented editor will do, for example Notepad.  Do not use a
-word processor, since these insert formatting codes that will confuse
-LilyPond.} and enter
-
-@verbatim
-{ c'4 e' g' }
-@end verbatim
-
-Save it on the desktop as @file{test.ly} and make sure that it is not
-called @file{test.ly.TXT}.  Double clicking @file{test.ly} will process
-the file and show the resulting PDF file.
-
-
-@unnumberedsubsec Unix
-
-Begin by opening a terminal window and starting a text editor.  For
-example, you could open an xterm and execute
-@code{joe}.@footnote{There are macro files for VIM addicts, and there
-is a @code{LilyPond-mode} for Emacs addicts.  If they have not been
-installed already, refer to the file @file{INSTALL.txt}.}  In your
-text editor, enter the following input and save the file as
-@file{test.ly}
-
-@verbatim
-{ c'4 e' g' }
-@end verbatim
-
-@noindent
-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 2.6.0
-Processing `test.ly'
-Parsing...
-Interpreting music... [1]
-Preprocessing graphical objects... 
-Calculating line breaks... [2]
-Layout output to `test.ps'...
-Converting to `test.pdf'...
-@end example
-
-@cindex DVI file
-@cindex Viewing music
-@cindex xdvi
-@noindent
-The result is the file @file{test.pdf} which you can print or view
-with the standard facilities of your operating system.@footnote{If
-your system does not have any tools installed, you can try
-@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
-available package for viewing and printing PDF and PostScript files.}
-
 @node More about pitches
-@section More about pitches 
+@section More about pitches
 
-A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
-the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}.  As
+A @rglos{sharp} pitch is made by adding @samp{is} to
+the name, a @rglos{flat} pitch by adding @samp{es}.  As
 you might expect, a @rglos{double sharp} or @rglos{double flat} is
 made by adding @samp{isis} or @samp{eses}@footnote{This syntax
 derived from note naming conventions in Nordic and Germanic languages,
@@ -362,8 +392,8 @@ d cis fis
 @end example
 
 @noindent
-The code @samp{d} does not mean `print a black dot just below the
-staff.'  Rather, it means: `a note with pitch D-natural.'  In the key
+The code @samp{d} does not mean @qq{print a black dot just below the
+staff.}  Rather, it means: @qq{a note with pitch D-natural.}  In the key
 of A-flat major, it does get an accidental
 
 @lilypond[quote,notime,fragment,relative=1,verbatim]
@@ -408,7 +438,7 @@ For more information on Ties see @ref{Ties}.
 @node Automatic and manual beams
 @section Automatic and manual beams
 
-@cindex beams, by hand 
+@cindex beams, by hand
 All @rglos{beam}s are drawn automatically
 
 @lilypond[quote,fragment,relative=2,verbatim]
@@ -463,9 +493,9 @@ according to standard notation conventions.
 @c tie) examples...
 
 @c better to have this just before the `octaves are bad' snipped
-@c but we'd need to remove the ', from \key and tie 
-To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a `low quote' @code{,}
+@c but we'd need to remove the ', from \key and tie
+To raise a note by an octave, add a high quote @samp{'} (apostrophe) to
+the note name, to lower a note one octave, add a @q{low quote} @samp{,}
 (comma).  Middle C is @code{c'}
 
 @lilypond[quote,notime,fragment,verbatim]
@@ -478,17 +508,17 @@ An example of the use of quotes is in the following Mozart fragment
 \key a \major
 \time 6/8
 cis''8. d''16 cis''8 e''4 e''8
-b'8. cis''16 b'8 d''4 d''8 
+b'8. cis''16 b'8 d''4 d''8
 @end lilypond
 
 @noindent
 This example shows that music in a high register needs lots of quotes.
 This makes the input less readable, and it is a source of errors.  The
-solution is to use `relative octave' mode.   This is the
+solution is to use @q{relative octave} mode.   This is the
 most convenient way to copy existing music.
 
-In relative mode, a note without octavation quotes (i.e. the @code{'}
-or @code{,} after a note) is chosen so that it is closest to the
+In relative mode, a note without octavation quotes (i.e., the @samp{'}
+or @samp{,} after a note) is chosen so that it is closest to the
 previous one.  For example, @samp{c f} goes up while @samp{c g} goes
 down.
 
@@ -545,7 +575,7 @@ and @ref{Octave check}.
 
 
 In input files, music is represent by so-called @emph{music
-expression}s.  We have already seen some in the previous examples; 
+expression}s.  We have already seen some in the previous examples;
 a single note is a music expression
 
 @lilypond[fragment,quote,verbatim,relative=3]
@@ -566,13 +596,13 @@ Here, the expression from the previous example is combined with two
 notes
 
 @lilypond[fragment,quote,verbatim,relative=3]
-{ { a4 g } f g } 
+{ { a4 g } f g }
 @end lilypond
 
 This technique is useful for non-monophonic music.  To enter music
 with more voices or more staves, we also combine expressions in
 parallel.  Two voices that should play at the same time, are entered
-as a simultaneous combination of two sequences.  A `simultaneous'
+as a simultaneous combination of two sequences.  A @q{simultaneous}
 music expression is formed by enclosing expressions in @code{<<} and
 @code{>>}.  In the following example, three sequences (all containing
 two separate notes) are combined simultaneously
@@ -615,7 +645,7 @@ example begins with a single note.  To determine the number of staves,
 LilyPond looks at the first element.  If it is a single note, there is one
 staff; if there is a simultaneous expression, there is more than one staff.
 
-@lilypond[fragment,quote,verbatim,relative=2] 
+@lilypond[fragment,quote,verbatim,relative=2]
 {
   c <<c e>>
   << { e f } { c <<b d>> } >>
@@ -660,7 +690,7 @@ staff is marked by adding @code{\new Staff} before it.  These
 @end lilypond
 
 
-The command @code{\new} introduces a `notation context.'  A notation
+The command @code{\new} introduces a @q{notation context.}  A notation
 context is an environment in which musical events (like notes or
 @code{\clef} commands) are interpreted.  For simple pieces, such
 notation contexts are created automatically.  For more complex pieces, it
@@ -684,10 +714,10 @@ We can now typeset a melody with two staves
 \relative <<
   \new Staff {
     \time 3/4
-    \clef treble 
-    
+    \clef treble
+
     e'2 d4 c2 b4 a8[ a]
-    b[ b] g[ g] a2. 
+    b[ b] g[ g] a2.
   }
   \new Staff {
      \clef bass
@@ -897,7 +927,7 @@ see @ref{Partial measures}.
 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 @samp{%}
-introduces a line comment; after @code{%} the rest of the line is
+introduces a line comment; after @samp{%} the rest of the line is
 ignored.  A block comment marks a whole section of music
 input.  Anything that is enclosed in @code{%@{} and @code{%@}} is
 ignored.  The following fragment shows possible uses for comments
@@ -911,7 +941,7 @@ ignored.  The following fragment shows possible uses for comments
     are ignored, since they are in a
     block comment.
 
-    g g f f e e d d c2 
+    g g f f e e d d c2
 %@}
 @end example
 
@@ -923,10 +953,10 @@ ignored.  The following fragment shows possible uses for comments
 
 There is a special statement that is a kind of comment.  The @code{\version}
 statement marks for which version of LilyPond the file was written.
-To mark a file for version 2.6.0, use
+To mark a file for version 2.10.1, use
 
 @example
-\version "2.6.0"
+\version "2.10.1"
 @end example
 
 @noindent
@@ -975,13 +1005,13 @@ The lyrics can be set to these notes, combining both with the
 @cindex melisma
 @cindex extender line
 @c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (`free')
+This melody ends on a @rglos{melisma}, a single syllable (@q{free})
 sung to more than one note.  This is indicated with an @emph{extender
 line}.  It is entered as two underscores, i.e.,
 
 @example
 @{ I want to break free __ @}
-@end example 
+@end example
 
 @lilypond[fragment,quote,ragged-right]
 <<
@@ -997,16 +1027,17 @@ Similarly, hyphens between words can be entered as two dashes,
 resulting in a centered hyphen between two syllables
 
 @example
-Twin -- kle twin -- kle
+A -- le gri -- a
 @end example
 
-@lilypond[fragment,quote,ragged-right]
+@c no ragged-right here, because otherwise the hypens get lost.
+@lilypond[fragment,quote]
 <<
   \relative {
     \time 2/4
     f4 f c' c
   }
-  \addlyrics { Twin -- kle twin -- kle }
+  \addlyrics { A -- le gri -- a }
 >>
 @end lilypond
 
@@ -1046,7 +1077,7 @@ line for themselves.  This is achieved by using @code{\chords} instead
 of @code{\chordmode}.  This uses the same syntax as @code{\chordmode},
 but renders the notes in a @code{ChordNames} context, with the
 following result.
- 
+
 @lilypond[quote,verbatim,ragged-right]
 \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
 @end lilypond
@@ -1066,7 +1097,7 @@ a lead sheet, for example,
 
 @lilypond[quote,ragged-right]
 <<
-  \chords { r2 c:sus4 f } 
+  \chords { r2 c:sus4 f }
   \relative {
     r4 c' \times 2/3 { f g g }
     \times 2/3 { g4( a2) }
@@ -1088,9 +1119,9 @@ entered as an assignment, within @code{\header
 @{@tie{}@dots{}@tie{}@}}.  The @code{\header} block is usually put at
 the top of the file.  For example,
 
-@example 
+@example
 \header @{
-  title = "Miniature" 
+  title = "Miniature"
   composer = "Igor Stravinsky"
 @}
 
@@ -1126,7 +1157,7 @@ voices with @code{\\}
 For polyphonic music typesetting, spacer rests can also be convenient;
 these are rests that do not print.  They are useful for filling up
 voices that temporarily do not play.  Here is the same example with a
-spacer rest (@code{s}) instead of a normal rest (@code{r}),
+spacer rest (@samp{s}) instead of a normal rest (@samp{r}),
 
 @lilypond[quote,verbatim,relative=2,fragment]
 << { a4 g2 f4~ f4 } \\
@@ -1151,7 +1182,7 @@ Again, these expressions can be nested arbitrarily
 @end lilypond
 
 More features of polyphonic typesetting are described in this manual
-in section @ref{Polyphony}.
+in section @ref{Basic polyphony}.
 
 
 @node Piano staves
@@ -1184,7 +1215,7 @@ Here is a small example
 >>
 @end lilypond
 
-More information on formatting piano music is given in @ref{Piano music}.  
+More information on formatting piano music is given in @ref{Piano music}.
 
 
 @node Organizing larger pieces
@@ -1327,7 +1358,7 @@ this option to the music above, leads to the following result
 @lilypond[quote,ragged-right]
 \transpose f c' \relative c {
   \time 2/4
-  \set Score.skipBars = ##t 
+  \set Score.skipBars = ##t
   R2*3
   r4 f8 a cis4 f e d
 }
@@ -1349,7 +1380,7 @@ that the other voice is in @code{bassoonNotes} in the file
 @end example
 
 @noindent
-leading to 
+leading to
 
 @lilypond[quote,ragged-right]
 \relative c <<
@@ -1368,7 +1399,7 @@ leading to
 More in-depth information on preparing parts and scores can be found
 in the notation manual; see @ref{Orchestral music}.
 
-Setting run-time variables (`properties') is discussed in
+Setting run-time variables (@q{properties}) is discussed in
 @ref{Changing context properties on the fly}.