X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftutorial.itely;h=a196918529f4fd2c0cf9c6af2aa7820889b402f2;hb=74c01f58ad993e9b0907a174740030d8a2e13af9;hp=4d22f1df827d781d4dce903f6442f988db99ef11;hpb=2d4e8705a5431c9e30d274490245d4e450cddd11;p=lilypond.git

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 4d22f1df82..a196918529 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,
@@ -30,7 +36,8 @@ c-\markup { \bold \huge { Click here.  } }
 @end lilypond
 @end ifhtml
 
-By cutting and pasting the full input into a test file, you have a
+By cutting and pasting everything from the @qq{Start cut-&-pastable section},
+to the end of the file, you have a
 starting template for experiments.  If you like learning in this way,
 you will probably want to print out or bookmark
 @ifhtml
@@ -40,8 +47,9 @@ the
 commands for quick reference.
 
 @menu
-* First steps::                 
-* Blah::                        
+* First steps (compiling a file)::  
+* Simple notation::             
+* Working on text files::       
 * More about pitches::          
 * Entering ties::               
 * Automatic and manual beams::  
@@ -63,65 +71,69 @@ commands for quick reference.
 @end menu
 
 
-@node First steps
-@section First steps
+@node First steps (compiling a file)
+@section First steps (compiling a file)
 
-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
+The first example demonstrates how to start working with LilyPond.  To
+create sheet music, we write a text file that specifies the
+notation.  For example, if we write
 
 @example
 @{
-c' d' e' f' g' a' b' c''
+  c' e' g' e'
 @}
 @end example
 
 @noindent
 the result looks like this
 
-@lilypond[quote]
+@lilypond[quote,ragged-right]
 {
-c' d' e' f' g' a' b' c''
+  c' e' g' e'
 }
 @end lilypond
 
-@emph{Warning:}  Every piece of LilyPond input needs to have
-@{curly braces@} placed around the input.  Don't forget them!
+@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ 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 some 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.
-
+In addition, LilyPond input is @strong{case sensitive}.  @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
 
+@sp 1
 
 @unnumberedsubsec Entering music and viewing output
 
 In this section we will explain what commands to run
 and how to view or print the output.
 
-@unnumberedsubsec MacOS X
+@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.
+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".
 
-@unnumberedsubsec Windows
+@unnumberedsubsubsec 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
+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'' }
+{
+  c' e' g' e'
+}
 @end verbatim
 
 Save it on the desktop as @file{test.ly} and make sure that it is not
@@ -129,18 +141,22 @@ called @file{test.ly.TXT}.  Double clicking @file{test.ly} will process
 the file and show the resulting PDF file.
 
 
-@unnumberedsubsec Unix
+@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
+installed already, refer to the file @file{INSTALL.txt}.  These
+easiest editing environment is @file{LilyPondTool}.  See
+@ref{Editor support} for more information.}.  In your
 text editor, enter the following input and save the file as
 @file{test.ly}
 
 @verbatim
-{ c' e' g' c'' }
+{
+  c' e' g' e'
+}
 @end verbatim
 
 @noindent
@@ -165,9 +181,9 @@ Layout output to `test.ps'...
 Converting to `test.pdf'...
 @end example
 
-@cindex DVI file
+@cindex PDF 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
@@ -176,142 +192,188 @@ your system does not have any tools installed, you can try
 available package for viewing and printing PDF and PostScript files.}
 
 
-@node Second steps
-@section Second steps
+@node Simple notation
+@section Simple notation
 
-@emph{Remember:} 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!
+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.
 
-@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...} @}}.
-Many example have also been compressed horizontally to save
-space, using @code{\paper @{ ragged-right = ##t @}}.
+@lilypond[quote,ragged-right,verbatim]
+{
+  c' e' g' e'
+}
+@end lilypond
 
-@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.
+@noindent
+This behavior may be altered, but in most cases these automatic values
+are useful.
 
-@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
 
+@unnumberedsubsec Pitches
 
-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
+The easiest way to enter notes is by using @code{\relative} mode.  In
+this mode, the @rglos{interval} between the previous note and the
+current note is assumed to be within a @rglos{fourth}.  We begin by
+entering the most elementary piece of music, a @rglos{scale}.
 
-@example
-a1 a2 a4 a16 a32
-@end example
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  c d e f
+  g a b c
+}
+@end lilypond
+
+The initial note is @rglos{middle C}.  Each successive note
+is within a fourth of the previous note -- in other words, the first
+@samp{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:
 
-@lilypond[fragment,quote,notime,relative=2]
-\set Staff.autoBeaming = ##f
-{ a1 a2 a4 a16 a32 s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  d f a g
+  c b f d
+}
 @end lilypond
 
-If you do not specify a duration, the duration last entered is used
-for the next notes.  The duration of the first note in input defaults
-to a quarter
+@noindent
+As you may notice, this example does not start on middle C.  The first
+note -- the @samp{d} -- is the closest D to middle C.
 
-@example
-a a8 a a2 a
-@end example
+To add intervals that are larger than a fourth, we can raise the octave
+by adding a single quote @code{'} (or apostrophe) to the note name.  We can
+lower the octave by adding a comma @code{,} to the note name.
 
-@lilypond[fragment,quote,notime,relative=2]
-{ a a8 a a2 a s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a a, c' f,
+  g g'' a,, f'
+}
 @end lilypond
 
+@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{\relative c'} may also be modified like this.
 
-A @rglos{rest} is entered just like a note, but with the name @samp{r}
 
-@example
-r2 r4 r8 r16
-@end example
+@unnumberedsubsec Durations (rhythms)
 
-@lilypond[fragment,quote,notime]
-r2 r4 r8 r16 s16_" "
+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.  Beams are added
+automatically.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a1
+  a2 a4 a8 a
+  a16 a a a a32 a a a a64 a a a a a a a a2
+}
 @end lilypond
 
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}
+@noindent
+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.
 
-@example
-a2. a4 a8. a16
-@end example
+To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.
 
-@lilypond[fragment,quote,notime,relative=1]
-{ a2. a4 a8. a16 s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a a a4. a8
+  a8. a16 a a8. a8 a4.
+}
 @end lilypond
 
-The (or @rglos{time signature}) can be set with the @code{\time}
-command
 
-@example
-\time 3/4
-\time 6/8
-\time 4/4
-@end example
+@unnumberedsubsec Rests
 
-@c A clef here may lead to confusion, remove it.
-@lilypond[fragment,quote]
-\override Staff.Clef #'transparent = ##t
-\time 3/4
-s4_" "
-\time 6/8
-s4_" "
-\time 4/4
-s16_" "
+A @rglos{rest} is entered just like a note with the name @samp{r}:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a r r2
+  r8 a r4 r4. r8
+}
 @end lilypond
 
-The @rglos{clef} can be set using the @code{\clef} command
 
-@example
-\clef treble
-\clef bass
-\clef alto
-\clef tenor
-@end example
+@unnumberedsubsec Time signature
 
-@lilypond[fragment,quote,notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
+The @rglos{time signature}) can be set with the @code{\time} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  \time 3/4
+  a4 a a
+  \time 6/8
+  a4. a
+  \time 4/4
+  a4 a a a
+}
 @end lilypond
 
-Remember to enclose the notes and commands in curly braces
-@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
 
-@lilypond[fragment,quote,noindent,verbatim]
-\time 3/4
-\clef bass
-c2 e4 g2.
-f4 e d c2 r4
+@unnumberedsubsec Clef
+
+The @rglos{clef} can be set using the @code{\clef} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+  \clef treble
+  c1
+  \clef alto
+	c1
+  \clef tenor
+  c1
+  \clef bass
+  c1
+}
 @end lilypond
 
-For more information on
 
-@quotation
-@table @asis
-@item Entering pitches and durations
-see
-@ref{Pitches}, and @ref{Durations}.
-@item Clefs
-see @ref{Clef}.
-@item Rests
-see @ref{Rests}.
-@item Time signatures and other timing commands
-see @ref{Time signature}.
-@end table
-@end quotation
+@unnumberedsubsec All together
+
+Here is a small example showing all these elements together:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c, {
+  \time 3/4
+  \clef bass
+  c2 e8 c' g'2.
+  f4 e d c4 c, r4
+}
+@end lilypond
+
+
+@node Working on text files
+@section Working on text files
+
+LilyPond input files are treated like files in most programming languages:
+they are case sensitive, white-space insensitive, and expressions are
+formed with curly braces @{ @}.
+
+If the previous sentence sounds like nonsense, don't worry!  We'll explain
+what all these terms mean:
+
+@itemize
+@item
+@strong{Remember:} Every piece of LilyPond input needs to have
+@strong{@{ 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!
+
+@cindex Case sensitive
+@item
+In addition, LilyPond input is @strong{case sensitive}.  @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
+
+@c  End of current re-write; more material coming in a few days.  -gp
+@end itemize
+
 
 
 @node More about pitches
@@ -383,8 +445,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]
@@ -485,8 +547,8 @@ according to standard notation conventions.
 
 @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{,}
+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]
@@ -505,11 +567,11 @@ b'8. cis''16 b'8 d''4 d''8
 @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.
 
@@ -593,7 +655,7 @@ notes
 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
@@ -681,7 +743,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
@@ -918,7 +980,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
@@ -996,7 +1058,7 @@ 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.,
 
@@ -1148,7 +1210,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 } \\
@@ -1390,7 +1452,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}.
 
 
@@ -1412,4 +1474,22 @@ Learning Manual assumes that you are familiar with
 LilyPond input.  You may wish to skim these chapters right
 now, and come back to them after you have more experience.
 
+@ignore
+For more information on
+
+@q uotation
+@t able @asis
+@i tem Entering pitches and durations
+see
+@r ef{Pitches}, and @ref{Durations}.
+@i tem Clefs
+see @ref{Clef}.
+@i tem Rests
+see @ref{Rests}.
+@i tem Time signatures and other timing commands
+see @ref{Time signature}.
+@e nd table
+@e nd quotation
+@end ignore
+