Second phase of tutorial rewrite.

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index d80f22207d3ebabbb57556b25c4e4605d4a53671..a196918529f4fd2c0cf9c6af2aa7820889b402f2 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -49,6 +49,7 @@ commands for quick reference.
 @menu
 * First steps (compiling a file)::  
 * Simple notation::             
 @menu
 * First steps (compiling a file)::  
 * Simple notation::             

+* Working on text files::       

 * More about pitches::          
 * Entering ties::               
 * Automatic and manual beams::  
 * More about pitches::          
 * Entering ties::               
 * Automatic and manual beams::  


@@ -73,22 +74,22 @@ commands for quick reference.
 @node First steps (compiling a file)
 @section First steps (compiling a file)
 
 @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
 @{
 
 @example
 @{

-c' e' g' c''
+  c' e' g' e'

 @}
 @end example
 
 @noindent
 the result looks like this
 
 @}
 @end example
 
 @noindent
 the result looks like this
 

-@lilypond[quote]
+@lilypond[quote,ragged-right]

 {
 {

-c' e' g' c''
+  c' e' g' e'

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -130,7 +131,9 @@ Notepad.  Do not use a word processor, since these insert formatting
 codes that will confuse LilyPond.} and enter
 
 @verbatim
 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
 @end verbatim
 
 Save it on the desktop as @file{test.ly} and make sure that it is not


@@ -151,7 +154,9 @@ text editor, enter the following input and save the file as
 @file{test.ly}
 
 @verbatim
 @file{test.ly}
 
 @verbatim

-{ c' e' g' c'' }
+{
+  c' e' g' e'
+}

 @end verbatim
 
 @noindent
 @end verbatim
 
 @noindent


@@ -190,143 +195,185 @@ available package for viewing and printing PDF and PostScript files.}
 @node Simple notation
 @section Simple notation
 
 @node Simple notation
 @section Simple notation
 

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

 
 

-@cindex Case sensitive
-In addition, LilyPond input is @strong{case sensitive}.  @code{ @{ c d e @} }
-is valid input; @code{ @{ C D E @} } will produce an error message.
+@lilypond[quote,ragged-right,verbatim]
+{
+  c' e' g' e'
+}
+@end lilypond
+
+@noindent
+This behavior may be altered, but in most cases these automatic values
+are useful.
+
+
+@unnumberedsubsec Pitches
+
+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}.
+
+@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[quote,ragged-right,verbatim]
+\relative c' {
+  d f a g
+  c b f d
+}
+@end lilypond

 
 

+@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.
+
+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[quote,ragged-right,verbatim]
+\relative c'' {
+  a a, c' f,
+  g g'' a,, f'
+}
+@end lilypond

 
 

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

 
 

-@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 Durations (rhythms)

 
 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},
 
 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
-
-@example
-a1 a2 a4 a16 a32
-@end example
+@samp{4} for a @rglos{quarter note} and so on.  Beams are added
+automatically.

 
 

-@lilypond[fragment,quote,notime,relative=2]
-\set Staff.autoBeaming = ##f
-{ a1 a2 a4 a16 a32 s16_" " }
+@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
 
 @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
+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
-a a8 a a2 a
-@end example
+To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.

 
 

-@lilypond[fragment,quote,notime,relative=2]
-{ a a8 a a2 a s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a a a4. a8
+  a8. a16 a a8. a8 a4.
+}

 @end lilypond
 
 
 @end lilypond
 
 

-A @rglos{rest} is entered just like a note, but with the name @samp{r}
+@unnumberedsubsec Rests

 
 

-@example
-r2 r4 r8 r16
-@end example
+A @rglos{rest} is entered just like a note with the name @samp{r}:

 
 

-@lilypond[fragment,quote,notime]
-r2 r4 r8 r16 s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  a r r2
+  r8 a r4 r4. r8
+}

 @end lilypond
 
 @end lilypond
 

-Add a dot @samp{.} after the duration to get a @rglos{dotted note}

 
 

-@example
-a2. a4 a8. a16
-@end example
+@unnumberedsubsec Time signature
+
+The @rglos{time signature}) can be set with the @code{\time} command:

 
 

-@lilypond[fragment,quote,notime,relative=1]
-{ a2. a4 a8. a16 s16_" " }
+@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
 
 @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 Clef

 
 

-@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_" "
+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
 
 @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 All together

 
 

-@lilypond[fragment,quote,notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
+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
 
 @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
-@end lilypond
+@node Working on text files
+@section Working on text files

 
 

-For more information on
+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

 
 

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

 
 
 @node More about pitches
 
 
 @node More about pitches


@@ -1427,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.
 
 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
+