From: fred <fred>
Date: Tue, 26 Mar 2002 22:41:27 +0000 (+0000)
Subject: lilypond-1.2.13
X-Git-Tag: release/1.5.59~2056
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=4ff5845bda125967e10ac6488c93b3c94dbffb85;p=lilypond.git

lilypond-1.2.13
---

diff --git a/Documentation/user/GNUmakefile b/Documentation/user/GNUmakefile
index 10ddca981f..24cc5c5cc4 100644
--- a/Documentation/user/GNUmakefile
+++ b/Documentation/user/GNUmakefile
@@ -9,7 +9,8 @@ DOC_FILES = $(wildcard *.doc)
 
 DVI_FILES = $(addprefix $(outdir)/,$(DOC_FILES:.doc=.dvi)  $(TELY_FILES:.tely=.dvi))
 
-EXTRA_DIST_FILES= $(DOC_FILES) $(DATA_FILES) 
+EXTRA_DIST_FILES= $(DOC_FILES) $(DATA_FILES)  $(wildcard *.itexi *.itely)
+
 HTML_FILES = $(addprefix $(outdir)/, $(TELY_FILES:.tely=.html))
 
 PS_FILES = $(DVI_FILES:.dvi=.ps)  $(OUTDOC_FILES:.doc=.ps) $(OUTTEX_FILES:.tex=.ps)
@@ -32,7 +33,7 @@ GENHTMLS = engraving colorado glossary computer-notation
 OUTGENHTMLS = $(addprefix $(outdir)/, $(GENHTMLS:%=%.html))
 
 local-WWW: $(HTML_FILES)   $(datafiles) $(PS_GZ_FILES)
-	$(PYTHON) $(step-bindir)/ls-latex.py --title 'User documentation about LilyPond' \
+	$(PYTHON) $(step-bindir)/ls-latex.py --title 'User documentation' \
 	   $(DOC_FILES) $(TEX_FILES) $(TELY_FILES) \
 	  | sed "s!$(outdir)/!!g" > $(outdir)/index.html
 	$(footify) $(outdir)/index.html
@@ -41,4 +42,4 @@ $(outdir)/%.bib: %.bib
 	ln -f $< $@
 
 localclean:
-	rm -f fonts.aux fonts.log feta*.tfm feta*.*pk
+	rm -f fonts.aux fonts.log feta*.tfm feta*.*pk 
diff --git a/Documentation/user/properties.itely b/Documentation/user/properties.itely
new file mode 100644
index 0000000000..c750b3af9c
--- /dev/null
+++ b/Documentation/user/properties.itely
@@ -0,0 +1,546 @@
+@node Properties, , , Top
+
+@cindex properties!Lyrics
+
+@table @samp
+  @item @code{textStyle}@indexcode{textStyle}  
+    Set the font for lyrics.  The available font choices are
+    @code{roman}, @code{italic}, @code{bold}, @code{large}, @code{Large},
+    @code{typewriter}, and @code{finger}.  The @code{finger} font can
+    only display numbers.  Note also that you must be careful when
+    using @code{\property} in Lyrics mode, because of the way strings
+    are parsed.  Either put quotes around the arguments to
+    @code{\property} or be sure to leave a space on both sides of the
+    dot.
+@end table
+
+
+@cindex properties!Thread
+
+@table @samp
+  @item @code{noteheadStyle}@indexcode{noteheadStyle}  
+    Selects type of note head.  Choices are @code{cross},
+    @code{diamond}, @code{harmonic}, @code{transparent}, and @code{""}. 
+    They are shown in that order below.
+
+    @mudela[center]
+
+      \score {
+        \notes { 
+          \property Staff.barNonAuto = 1
+          \property Voice.noteHeadStyle = cross 
+          a'
+          \property Voice.noteHeadStyle = diamond
+          a'
+          \property Voice.noteHeadStyle = harmonic
+          a'
+          \property Voice.noteHeadStyle = transparent
+          a' 
+          \property Voice.noteHeadStyle = ""
+          a'
+        }
+        \paper {
+          linewidth = -1.;
+        }
+      }
+    
+@end mudela
+@end table
+
+@subsubheading Grace properties
+
+@cindex properties!Grace
+
+ 
+@table @samp  
+  @item @code{stemStyle}@indexcode{stemStyle}  
+    By default set to @code{"grace"} meaning that all unbeamed 
+    notes with flags are typeset with a slash through the flag. 
+    Setting to @code{""} gives standard flags.
+@end table
+
+
+@subsubheading Voice properties
+
+@cindex properties!Voice
+
+@table @samp  
+  @item @code{abbrev}@indexcode{abbrev}  
+    Set length for tremolo to be used if no length is explicitly
+    specified. 
+
+  @item @code{articulationScriptPadding}@indexcode{articulationScriptPadding}
+     
+    Determines the extra space added between articulation marks, such
+    as staccato, tenuto, trill, up/down bow or fermata, and the
+    closest staff line or note.
+
+  @item @code{articulationScriptVerticalDirection}
+    @indexcode{articulationScriptVerticalDirection}  
+    Determines the location of articulation marks.  Set to @code{\up}
+    to print marks above the staff; set to @code{\down} to print marks
+    below the staff.  This property does not override explicit
+    directions marked with `@code{^}' or `@code{_}' in the mudela file.
+    
+  @item @code{noAutoBeaming}@indexcode{beamAuto}  
+    If set to 1 then beams are not generated automatically.
+
+  @item @code{beamAutoEnd}@indexcode{beamAutoEnd}  
+    Specifies when automatically generated beams can end.  See
+    section XREF-autobeam [FIXME].
+
+  @item @code{beamAutoBegin}@indexcode{beamAutoBegin}  
+    Specifies when automatically generated beams can start.  See
+    section XREF-autobeam [FIXME].
+
+  @item @code{beamquantisation}@indexcode{beamquantisation}  
+    Set to @code{\none} for no quantization.  Set to @code{\normal} to
+    quantize position and slope.  Set to @code{\traditional} to avoid
+    wedges.  These three settings are available via
+    @code{\beamposfree}@keyindex{beamposfree},
+    @code{\beamposnormal}@keyindex{beamposnormal}, and
+    @code{\beampostraditional}@keyindex{beampostraditional}.
+
+  @item @code{beamslopedamping}@indexcode{beamslopedamping}  
+    Set to @code{\none} for undamped beams.  Set to @code{\normal} for
+    damped beams.  Set to @code{\infinity} for beams with zero slope. 
+    The identifiers
+    @code{\beamslopeproportional}@keyindex{beamslopeproportional},
+    @code{\beamslopedamped}@keyindex{beamslopedamped}, and
+    @code{\beamslopezero}@keyindex{beamslopezero} each set the
+    corresponding value.
+
+  @item @code{dynamicDirection}@indexcode{dynamicDirection}  
+    Determines location of dynamic marks.  Set to @code{\up} to print
+    marks above the staff; set to @code{\down} to print marks below
+    the staff.
+
+  @item @code{dynamicStyle}@indexcode{dynamicStyle}  
+    Set the text style for dynamics.  
+
+  @item @code{fontSize}@indexcode{fontSize}  
+    Can be used to select smaller font sizes for music.  The normal
+    font size is 0, and the two smaller sizes are -1
+    and -2.
+
+   @item @code{forceHorizontalShift}@indexcode{forceHorizontalShift}  
+    Force horizontal shift for collision resolution.  It overrides
+    automatic collision resolution.  The value is the shift amount
+    expressed in @code{note_width}, as set in the paper section.
+
+[FIXME: this should be moved]
+
+Lilypond always arranges note heads on alternate sides of a stem (that
+is, within a single voice) as necessary to prevent collisions (note head
+overlaps).  For up stems, the upper note of a colliding pair is placed
+on the right side of the stem, the lower on the left. For down stems,
+the algorithm works in reverse.
+  
+Lily also attempts to prevent collisions of note heads in different
+voices. A situation where chords of two or more voices are played
+simultaneously within one staff.
+
+By default, if only two voices (and both have opposite stem directions)
+are in this 'collision group', the notes both are shifted by @code{0.5
+\quartwidth} if there are unisons or seconds between the voices.
+
+If there are more than two voices in a collision group, shifting is
+inactive by default, since in this case, there are multiple chords with
+the same stem direction. By  distinguish between those chords, LilyPond
+can do collision resolution in these cases as well.  
+
+Distinguishing between voices with the same stem direction, is done by
+setting the property @code{Voice.horizontalNoteShift}.  It must be set
+to a different integer for each voice. Then, all note heads in collision
+groups (not just unisons and seconds) will be offset, one voice relative
+another.  The following fragment of sheet music shows how shifting is
+done, with values of @code{horizontalNoteShift} printed over and under
+the notes. In this case the chords are just simple notes.
+
+@c URG : mudela book bug.
+@mudela[singleline]
+\score {
+        \notes \context Staff <
+        	\context Voice  = VA { \stemup f''4^"0" }
+        	\context Voice  = VB {\stemup
+		\property Voice.horizontalNoteShift = 1 d''4^" 1" }
+        	\context Voice  = VC { \stemup \property
+Voice.horizontalNoteShift = 2 b'4^"  2" }
+        	\context Voice  = VD { \stemdown \property
+Voice.horizontalNoteShift = 1 g'4_"1 " }
+        	\context Voice  = VE { \stemdown e'4_"0" }
+        >
+}
+@end mudela
+
+If you are not satisfied with the collision resolution of LilyPond, you
+can override the horizontal shift value of the chord of one Voice, by
+setting @code{forceHorizontalShift}.  This sets the amount shift,
+measured in black note head widths.
+
+To take complete control of note position shifts in complex passages,
+you have set things up for normal collisions and override all shifts by
+setting @code{forceHorizontalShift} to zero everywhere
+@example
+\property Voice.horizontalNoteShift = <n>
+\property Voice.forceHorizontalShift = "0.0"
+@end example
+
+Then you can set the force property to a suitable value before each note
+that really needs it (unisons and seconds), and reset it to 0.0 after
+the note.  
+
+  @item @code{horizontalNoteShift}@indexcode{horizontalNoteShift}  
+    Enable LilyPond to shift notes horizontally if they collide with
+    other notes.  This is useful when typesetting many voices on one
+    staff.  The identifier @code{\shift}@keyindex{shift} is defined to
+    enable this.  Traditionally, the outer chords (the upmost and
+    downmost voices), should have no @code{horizontalNoteShift}.
+
+  @item @code{markScriptPadding}@indexcode{markScriptPadding}  
+    Determines the extra space added between the mark and the closest
+    staff line or note.
+
+  @item @code{markDirection}@indexcode{markDirection}  
+    Determines if marks should be printed above or below the staff.
+    Set to @code{\up} to print marks above the staff; set to
+    @code{\down} to print marks below the staff.
+
+  @item @code{midiInstrument}@indexcode{midiInstrument}  
+    Sets the instrument for MIDI output.  If this property is not set
+    then LilyPond will use the @code{instrument} property.  This must
+    be set to one of the strings on the list of MIDI instruments that
+    appears in section XREF-midilist [FIXME].  If you use a string which
+    is not listed, LilyPond will silently substitute piano.
+
+  @item @code{oldTieBehavior}@indexcode{oldTieBehavior}  
+    Set to 1 in order to get old tie behavior where ties would
+    connect unequal pitches.  This property is deprecated, and its
+    use is not recommended.
+
+  @item @code{restStyle}@indexcode{restStyle}  
+    Change the layout of rests shorter than quarter notes. 
+    Currently, the standard layout @code{""} and mensural notation
+    @code{"mensural"} are available. Mensural rests of duration
+    32 or shorter are not available.
+    
+  @item @code{scriptHorizontal}@indexcode{scriptHorizontal}  
+    Put scripts left or right of note heads.  Support for this is
+    limited.  Accidentals will collide with scripts.
+    
+  @item @code{slurVerticalDirection}@indexcode{slurVerticalDirection}  
+    Set to @code{\free} for free choice of slur direction, set to
+    @code{\up} to force slurs up, set to @code{\down} to force slurs
+    down.  The shorthands @code{\slurup}@keyindex{slurup},
+    @code{\slurdown}@keyindex{slurdown}, and
+    @code{\slurboth}@keyindex{slurboth} are available.
+
+  @item @code{slurDash}@indexcode{slurDash}  
+    Set to 0 for normal slurs, 1 for dotted slurs, and a
+    larger value for dashed slurs.  Identifiers
+    @code{\slurnormal}@keyindex{slurnormal} and
+    @code{\slurdotted}@keyindex{slurdotted} are predefined to set the
+    first two settings.
+
+@item @code{stemLength}@indexcode{stemLength}  
+    Set length of stems.  Unit is `@code{interline}/2', so
+    @code{stemLength} defaults to 7.
+
+  @item @code{stemLeftBeamCount}@indexcode{stemLeftBeamCount}  
+    Specify the number of beams to draw on the left side of the next
+    note.  Overrides automatic beaming.  The value is only used once,
+    and then it is erased.
+
+  @item @code{stemRightBeamCount}@indexcode{stemRightBeamCount}  
+    Specify the number of beams to draw on the right side of the next
+    note.  Overrides automatic beaming.  The value is only used once,
+    and then it is erased.
+  @item @code{tieVerticalDirection}@indexcode{tieVerticalDirection}  
+    Set to @code{\free} for free choice of tie direction, set to
+    @code{\up} to force ties up, set to @code{\down} to force ties
+    down.
+
+  @item @code{transposing}@indexcode{transposing}  
+    Transpose the MIDI output.  Set this property to the number of
+    half-steps to transpose by.
+
+  
+  @item @code{textEmptyDimension}@indexcode{textEmptyDimension}  
+    If set to 1 then text placed above or below the staff is
+    assumed to have zero width.
+  
+  @item @code{textStyle}@indexcode{textStyle}  
+    Set the text style for superscripts and subscripts.  See above
+    for list of text styles.
+
+  @item @code{textScriptPadding}@indexcode{textScriptPadding}  
+    Determines the extra space added between superscripted resp.
+    subscripted text and the closest staff line or note.
+
+  @item @code{verticalDirection}@indexcode{verticalDirection}  
+    Determines the direction of stems, subscripts, beams, slurs, and
+    ties.  Set to @code{\down} to force them down, @code{\up} to force
+    them up, or @code{\free} to let LilyPond decide.  This can be used
+    to distinguish between voices on the same staff.  The
+    @code{\stemdown}@keyindex{stemdown}, @code{\stemup}@keyindex{stemup},
+    and @code{\stemboth}@keyindex{stemboth} identifiers set this
+    property.
+    
+
+  @item @code{tupletDirection}@indexcode{tupletDirection}  
+    Determines the direction of triplets and other tuplets.  Set to
+    @code{\down} to force them below the staff, @code{\up} to force
+    them above, or @code{\free} to let LilyPond decide.
+
+  @item @code{tupletVisibility}@indexcode{tupletVisibility}  
+    Determines whether tuplets of notes are labelled.  Setting
+    to 0 shows nothing; setting to 1 shows a number;
+    setting to 2 shows a number and a bracket if there is no
+    beam; setting to 3 shows a number, and if there is no beam
+    it adds a bracket; setting to 4 shows both a number and a
+    bracket unconditionally.
+
+@end table
+
+@subsubheading Staff properties
+
+@cindex properties!Staff
+
+@table @samp
+ 
+  @item @code{barNonAuto}@indexcode{barNonAuto}  
+    If set to 1 then bar lines will not be printed
+    automatically; they must be explicitly created with @code{\bar}
+    keywords.  Unlike with the @code{\cadenza} keyword, measures are
+    still counted.  Bar generation will resume according to that
+    count if this property is set to zero.
+
+  @item @code{barNumberDirection}@indexcode{barNumberDirection}  
+    Set to @code{\up} or @code{\down} to put bar numbers above or below
+    the staff.
+
+  @item @code{barNumberHangOnClef}@indexcode{barNumberHangOnClef}  
+    Set to 1 to cause bar numbers to appear above or below the
+    clef instead of on the bar line.  This property is deprecated. 
+    Do not use.
+
+  @item @code{barNumberScriptPadding}@indexcode{barNumberScriptPadding}  
+    Sets extra space between the bar number and the bar it labels.
+
+  @item @code{barSize}@indexcode{barSize}  
+    Specify the height of the bar lines if it should be different
+    than the staff height.
+
+  @item @code{barAtLineStart}@indexcode{barAtLineStart}  
+    Set to 1 to produce a bar line after the clef at the start
+    of each line (but not at the beginning of the music).
+
+  @item @code{clefStyle}@indexcode{clefStyle}  
+    Determines how clefs are typeset.  If set to @code{transparent},
+    the clefs are not printed at all, if set to
+    @code{fullSizeChanges}, clef changes in the middle of a line are
+    typeset with a full size clef.  By default, clef changes are
+    typeset in smaller size.
+
+  @item @code{createKeyOnClefChange}@indexcode{createKeyOnClefChange}  
+    Set to a nonempty string if you want key signatures to be printed
+    when the clef changes.  Set to the empty string if you do not
+    want key signatures printed.
+
+  @item @code{createInitdefaultClef}@indexcode{createInitdefaultClef}  
+    Specify whether clefs are created on default?  (Doesn't seem to
+    do anything.)
+
+  @item @code{defaultClef}@indexcode{defaultClef}  
+    Determines the default clef.  See @code{\clef} keyword.
+
+  @item @code{markHangOnClef}@indexcode{markHangOnClef}  
+    Set to 1 to cause marks to appear by clefs instead of by bar
+    lines.  Deprecated, use is not recommended.
+
+  @item @code{marginDirection}@indexcode{marginDirection}  
+    Set to @code{\left} or @code{\right} to specify location of
+    marginal scripts.
+
+  @item @code{marginScriptPadding}@indexcode{marginScriptPadding}  
+    Specify extra space for marginal scripts.
+
+  @item @code{forgetAccidentals}@indexcode{forgetAccidentals}  
+    Causes accidentals to be printed at every note instead of
+    remembered for the duration of a measure.
+
+  @item @code{noResetKey}@indexcode{noResetKey}  
+    Do not reset the key at the start of a measure.  Accidentals will
+    be printed only once and are in effect until overridden, possibly
+    many measures later.
+
+  @item @code{staffLineLeading}@indexcode{staffLineLeading}  
+    Specifies the distance (in points) between lines of the staff.
+
+  @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}  
+    Specifies the number of staff lines.  The default is 5.
+
+  @item @code{postBreakPadding}@indexcode{postBreakPadding}  
+    Extra space in points to be added after the clef, time signature
+    and key signature on the staff.  Deprecated, do not use.
+
+  @item @code{noVoltaBraces}@indexcode{noVoltaBraces}  
+    Set to true to suppress the printing of brackets over alternate
+    endings specified by the command @code{\alternative}.
+
+  @item @code{numberOfStaffLines}@indexcode{numberOfStaffLines}  
+    Sets the number of lines that the staff has.
+ 
+  @item @code{barAlways}@indexcode{barAlways}  
+    If set to 1 a bar line is drawn after each note.
+
+  @item @code{defaultBarType}@indexcode{defaultBarType}  
+    Sets the default type of bar line. See Section XREF-barlines [FIXME] 
+    for a list of available bar types.
+
+  @item @code{instrument}, @code{instr}
+    @indexcode{instrument}@indexcode{instr}  
+    If @code{Staff_margin_engraver}
+@cindex Staff_margin_engraver
+ is
+    added to the Staff translator, then the @code{instrument} property
+    is used to label the first line of the staff and the @code{instr}
+    property is used to label subsequent lines.  If the
+    @code{midiInstrument} property is not set, then @code{instrument}
+    is used to determine the instrument for MIDI output.
+
+  @item @code{keyOctaviation}@indexcode{keyOctaviation}  
+    If set to 1, then keys are the same in all octaves.  If set
+    to 0 then the key signature for different octaves can be
+    different and is specified independently:
+
+    @example
+      \keysignature bes fis'
+    @end example
+
+    The default value is 1.  Can be set to zero with
+    @code{\specialkey} or reset to 1 with @code{\normalkey}.
+
+  @item @code{timeSignatureStyle}@indexcode{timeSignatureStyle}  
+    Changes the default two-digit layout for time signatures.  The
+    following values are recognized:
+
+    @table @samp
+      @item @code{C}@indexcode{C}  
+        4/4 and 2/2 are typeset as C and struck C, respectively.  All
+        other time signatures are written with two digits.
+
+      @item @code{old}@indexcode{old}  
+        2/2, 3/2, 2/4, 3/4, 4/4, 6/4, 9/4, 4/8, 6/8 and 9/8 are
+        typeset with old-style mensuration marks.  All other time
+        signatures are written with two digits.
+
+      @item @code{1}@indexcode{1}  
+        All time signatures are typeset with a single
+        digit, e.g. 3/2 is written as 3.
+
+      @item @indexcode{CM/N}@code{C}@var{M}@code{/}@var{N}, 
+      @indexcode{oldM/N}@code{old}@var{M}@code{/}@var{N} or
+      @code{old6/8alt}@indexcode{old6/8alt}  
+        Tells LilyPond to use a specific symbol as time signature.
+    @end table
+
+    The different time signature characters are shown below with its
+    names:
+
+    @mudela[center]
+
+      \score {
+        \notes\relative c'' {
+          \property Voice.textStyle = typewriter
+          \property Staff.timeSignatureStyle = "C2/2"
+          \time 2/2; a2^"C2/2" a2 
+          \property Staff.timeSignatureStyle = "C4/4"
+          \time 2/2; a2^"C4/4" a2 
+          \property Staff.timeSignatureStyle = "old2/2"
+          \time 2/2; a2^"old2/2" a2 
+          \property Staff.timeSignatureStyle = "old3/2"
+          \time 2/2; a2^"old3/2" a2 
+          \property Staff.timeSignatureStyle = "old2/4"
+          \time 2/2; a2^"old2/4" a2 
+          \property Staff.timeSignatureStyle = "old4/4"
+          \time 2/2; a2^"old4/4" a2 
+          \property Staff.timeSignatureStyle = "old6/4"
+          \time 2/2; a2^"old6/4" a2 
+          \property Staff.timeSignatureStyle = "old9/4"
+          \time 2/2; a2^"old9/4" a2 
+          \property Staff.timeSignatureStyle = "old4/8"
+          \time 2/2; a2^"old4/8" a2 
+          \property Staff.timeSignatureStyle = "old6/8"
+          \time 2/2; a2^"old6/8" a2 
+          \property Staff.timeSignatureStyle = "old6/8alt"
+          \time 2/2; a2^"old6/8alt" a2 
+          \property Staff.timeSignatureStyle = "old9/8"
+          \time 2/2; a2^"old9/8" a2 
+        }
+        \paper {
+          linewidth = 4.5 \in;
+        }
+      }
+    
+@end mudela
+
+  @item @code{voltaSpannerDuration}@indexcode{voltaSpannerDuration}  
+    Set to an integer to control the size of the brackets printed by
+    @code{\alternative}.  The integer specifies the number of whole
+    notes duration to use for the brackets.  It is rounded to the
+    nearest measure.  This can be used to shrink the length of
+    brackets in the situation where one alternative is very large. 
+    It may have odd effects if the specified duration is longer than
+    the music given in an @code{\alternative}.
+@end table
+   
+
+@cindex properties!GrandStaff
+
+@table @samp 
+  @item @code{alignmentReference}@indexcode{alignmentReference}  
+    Set to @code{\center} for vertical alignment reference point to be
+    in the center of the vertical group.  Set to @code{\up} to put the
+    reference point at the top of the group.
+
+  @item @code{maxVerticalAlign}@indexcode{maxVerticalAlign}  
+    Set the maximum vertical distance between staffs.
+
+  @item @code{minVerticalAlign}@indexcode{minVerticalAlign}  
+    Set the minimum vertical distance between staffs.  
+@end table
+
+
+@cindex properties!Score
+
+@table @samp
+  @item @code{skipBars}@indexcode{skipBars}  
+    Set to 1 to skip the empty bars that are produced by
+    multimeasure notes and rests.  These bars will not appear on the
+    printed output.  Set to zero (the default) to expand multimeasure
+    notes and rests into their full length, printing the appropriate
+    number of empty bars so that synchronization with other voices is
+    preserved.
+
+    @quotation
+
+@mudela[fragment,verbatim,center]
+r1 r1*3 R1*3\property Score.skipBars=1 r1*3 R1*3
+
+@end mudela
+    @end quotation
+
+@end table
+
+
+@cindex properties!ChordNamesVoice
+
+@table @samp
+  @item @code{chordInversion}@indexcode{chordInversion}  
+    Determines whether LilyPond should look for chord inversions when
+    translating from notes to chord names.  Set to 1 to find
+    inversions.  The default is 0 which does not look for
+    inversions.
+@end table
+
diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
new file mode 100644
index 0000000000..35b5dc0cae
--- /dev/null
+++ b/Documentation/user/tutorial.itely
@@ -0,0 +1,900 @@
+
+@chapter Tutorial
+
+
+@node Tutorial, , , Top
+@menu
+* Introduction::                  Introduction
+* The first tune::                The first tune
+* Lyrics and chords::             Lyrics and chords
+* Piano music::                   Piano music
+* end of tutorial::                       The end
+@end menu
+
+@node Introduction,  , , Tutorial
+@section Introduction
+
+  
+LilyPond prints music from a specification that you, the user, supply.
+You have to give that specification using a @emph{language}.  This
+document is a gentle introduction to that language, which is called
+Mudela, an acronym of Music Definition Language.
+
+This tutorial will demonstrate how to use Mudela by presenting
+examples of input along with resulting output.  We will use English
+terms for notation.  In case you are not familiar with those, you may
+consult the glossary that is distributed with LilyPond.
+
+The examples discussed are included in the distribution, in the
+subdirectory @file{input/tutorial/}.  It is recommended that you
+experiment with writing Mudela input yourself, to get a feel for
+how LilyPond behaves.
+
+@node The first tune,  , , Tutorial
+@section The first tune
+
+
+To demonstrate what LilyPond input looks like, we start off with a
+full fledged, yet simple example. It is a convoluted version
+of the famous menuet in J. S. Bach's @emph{Klavierbuechlein}.
+
+@mudela[verbatim]
+% lines preceded by a percent are comments.
+\include "paper16.ly"
+\score {
+    \notes                        
+    \relative c'' \sequential{                
+            \time 3/4;                
+            \key g;
+
+        \repeat "volta" 2 {
+            d4 g,8 a b c d4 g, g |
+            e'4 c8 d e fis g4 g, g |
+            c4 d8()c b a( )b4 c8 b a g |
+            a4 [b8 a] [g fis] g2.  |
+        }
+
+        b'4 g8 a b g
+        a4 d,8 e fis d |
+        g4 e8 fis g d cis4 b8 cis a4 |
+        a8-. b-. cis-. d-. e-. fis-.
+        g4 fis e |
+        fis a,  r8 cis8
+        d2.-\fermata
+        \bar "|.";
+    }
+    \paper {
+       % standard settings are too wide for a book
+       linewidth = 14.0 \cm;
+   }
+}
+@end mudela
+
+Enter it (or copy it, the filename is @file{menuet.ly}), compile it
+with LilyPond and view the output.  Details of this procedure may vary
+from system to system.  To create the output, one would issue the
+command `@code{ly2dvi menuet}'.  @file{ly2dvi} is a program that does
+the job of running LilyPond and TeX, handling of titles and
+adjusting of page margins.
+
+If all goes well, the file @file{menuet.dvi} will be created.
+To view this output, issue the command `@code{xdvi menuet}'.
+
+Now that we are familiar with the procedure of producing output, we
+will analyse the input, line by line.
+@ignore
+Let's try to redo this
+@example
+
+        % lines preceded by a percent are comments.
+ 
+@end example 
+The percent sign, `@code{%}', introduces a line comment.  If you want to
+make larger comments, you can use block comments. These are delimited
+by `@code{%@{}' and `@code{%@}}'
+@end ignore
+@multitable @columnfractions .60 .39
+@item
+@noindent
+@c @example  urg: no tt font
+@c @exdent % lines preceded by a percent are comments.
+@exdent @code{% lines preceded by a percent are comments.}
+@c @end example
+@tab
+The percent sign, `@code{%}', introduces a line comment.  If you
+want to make larger comments, you can use block comments. These
+are delimited by `@code{%@{}' and `@code{%@}}'
+@end multitable
+@example 
+
+        \input "paper16.ly"
+ 
+@end example 
+By default, LilyPond will use definitions for a 20
+point@footnote{A point is the standard measure of length for
+printing.  One point is 1/72.27 inch.} high staff.  We want smaller
+output (16 point staff height), so we must import the settings for
+that size, which is done.@example 
+
+        \score @{
+ 
+@end example 
+  A mudela file combines music with directions for outputting that
+music.  The music is combined with the output directions by putting
+them into a @code{\score} block.
+@example 
+
+        \notes                
+ 
+@end example 
+ This makes LilyPond ready for accepting notes.
+@example 
+
+        \relative c''
+ 
+@end example 
+ As we will see, pitches are combinations of octave, note name and
+chromatic alteration.  In this scheme, the octave is indicated by
+using raised quotes (`@code{'}') and ``lowered'' quotes (commas:
+`@code{,}').  The central C is denoted by @code{c'}.  The C one octave
+higher is @code{c''}.  One and two octaves below the central C is
+denoted by @code{c} and @code{c,} respectively.
+
+For pitches in a long piece you might have to type many quotes.  To
+remedy this, LilyPond has a ``relative'' octave entry mode.  In this
+mode, octaves of notes without quotes are chosen such that a note is
+as close as possible (graphically, on the staff) to the the preceding
+note.  If you add a high-quote an extra octave is added.  The lowered
+quote (a comma) will subtract an extra octave.  Because the first note
+has no predecessor, you have to give the (absolute) pitch of the note
+to start with.@example 
+
+        \sequential @{
+ 
+@end example 
+  What follows is sequential music, i.e.,
+notes that are to be played and printed after each other.@example 
+
+        \time 3/4;
+ 
+@end example 
+  This command changes the time signature of the current piece: a 3/4
+sign is printed.  This command is also used to generate bar lines in
+the right spots.@example 
+
+        \key g;
+ 
+@end example 
+ This command changes the current key to G-major.  Although this
+command comes after the @code{\time} command, in the output, the key
+signature comes before the time signature: LilyPond knows about music
+typesetting conventions. @example 
+
+        \repeat "volta" 2
+ 
+@end example 
+  This command tells LilyPond that the following piece of music must
+be played twice; @code{"volta"} volta brackets should be used for
+alternatives---if there were any.
+@example 
+
+        @{
+ 
+@end example 
+The subject of the repeat is again sequential music.  Since
+@code{\sequential} is such a common construct, a shorthand is provided:
+just leave off @code{\sequential}, and the result is the same. @example 
+
+        d4
+ 
+@end example 
+ This is a note with pitch @code{d} (determined up to octaves).  The
+relative music was started with a @code{c''}, so the real pitch of this
+note is @code{d''}.  The @code{4} designates the duration of the note
+(it is a quarter note). @example 
+
+        a b
+ 
+@end example 
+These are notes with pitch @code{a} and @code{b}.  Because their
+duration is the same as the @code{g}, there is no need to enter the
+duration (You may enter it anyway, eg. @code{a4 b4}) @example 
+
+        d4 g, g |
+ 
+@end example 
+ Three more notes.  The `@code{|}' character is a `barcheck'.  When
+processing the music, LilyPond will verify that barchecks are found at
+the start of a measure.  This can help you track down errors.
+
+ So far, no notes were chromatically altered.  Here is the first one
+that is: @code{fis}. Mudela by default uses Dutch note names, and
+``Fis'' is the Dutch note name for ``F sharp''.  However, there is no
+sharp sign in the output. The program keeps track of key signatures,
+and will only print accidentals if they are needed.
+@example 
+
+        c8 d e fis
+ 
+@end example 
+LilyPond guesses were beams can be added to eighth and shorter notes.
+In this case, a beam over 4 eighths is added.
+@example 
+
+        c4 d8( )c b a( )b4 c8 b a g |
+ 
+@end example 
+  The next line shows how to make a slur:
+the beginning and ending note of the slur is marked with an opening and
+closing parenthesis respectively.  In the line shown above this is
+done for two slurs.  Slur markers (parentheses) are between
+the notes.@example 
+
+        a4 [b8 a] [g fis] 
+ 
+@end example 
+Automatic beaming can be overridden by inserting beam marks
+(brackets).  Brackets are put around notes you want beamed.@example 
+
+        g2.  |
+ 
+@end example 
+A duration with augmentation dot  is notated
+with the duration number followed by a period.@example 
+
+        @}
+ 
+@end example 
+  This ends the sequential music to be repeated.  LilyPond will typeset
+a repeat bar.  @example 
+
+        cis'4 b8 cis a4 |
+ 
+@end example 
+ This line shows that Lily will print an accidental if that is
+needed: the first C sharp will be printed with an accidental, the
+second one without.  @example 
+
+        a8-. b-. cis-. d-. e-. fis-.
+ 
+@end example 
+You can enter articulation signs either in a verbose form using a
+shorthand.  Here we demonstrate the shorthand: it is formed by a dash
+and the the character for the articulation to use, e.g. `@code{-.}' for
+staccato as shown above.  @example 
+
+        fis a, r8 cis8
+ 
+@end example 
+ 
+Rests are denoted by the special notename `@code{r}'.  You can also enter
+an invisible rest by using the special notename `@code{s}'.
+@example 
+
+        d2.-\fermata
+ 
+@end example 
+ All articulations have a verbose form, like @code{\fermata}.  The
+command `@code{\fermata}' is not part of the core of the language (most
+of the other discussed elements are), but it is a shorthand for a more
+complicated description of a fermata.  @code{\fermata} names that
+description and is therefore called an @emph{identifier}. @example 
+
+        @}
+ 
+@end example 
+ 
+Here the music ends.
+@example 
+
+        \paper @{
+                linewidth = 14.0\cm;
+        @}
+ 
+@end example 
+This specifies a conversion from music to notation output.  Most of
+the details of this conversions (font sizes, dimensions, etc.) have
+been taken care of, but  to fit the output  in this document, it has
+to be smaller.  We do this by setting the line width to 14 centimeters
+(approximately 6 inches).
+@example 
+
+        @}
+ 
+@end example 
+The last brace ends the @code{\score} block.
+
+There are two things to note here. The format contains musical
+concepts like pitches and durations, instead of symbols and positions:
+the input format tries to capture the meaning of @emph{music}, and not
+notation.  Therefore Second, the format tries to be @emph{context-free}:
+a note will sound the same regardless of the current time signature,
+the key, etc.
+
+The purpose of LilyPond is explained informally by the term `music
+typesetter'.  This is not a fully correct name: not only does the
+program print musical symbols, it also makes esthetic decisions.  All
+symbols and their placement is @emph{generated} from a high-level musical
+description.  In other words,  LilyPond would be best
+described by `music compiler' or `music to notation compiler'.
+
+@node Lyrics and chords, , , Tutorial
+@section Lyrics and chords
+
+In this section we show how to typeset a song of unknown
+origin.@footnote{The author would welcome information about the origin
+of this song.}.
+
+@example 
+\header @{
+        title = "The river is flowing";
+        composer = "Traditional (?)";
+@}
+\include "paper16.ly"
+melody = \notes \relative c' @{
+        \partial 8;
+        g8 |
+        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+        c4 c8 d [es () d] c4 | d4 es8 d c4.
+        \bar "|.";
+@}
+
+text = \lyrics @{
+        The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+        ri -- ver is flo -- wing down to the sea.
+@}
+
+accompaniment =\chords @{
+        r8
+        c2-3- f-3-.7 d-min es4 c8-min r8
+        c2-min f-min7 g-7^3.5 c-min @}
+
+\score @{
+        \simultaneous @{
+%         \accompaniment
+          \context ChordNames \accompaniment
+
+          \addlyrics
+            \context Staff = mel @{        
+              \property Staff.noAutoBeaming = "1"
+              \property Staff.automaticMelismata = "1"
+              \melody 
+            @}
+            \context Lyrics \text
+        @}
+        \midi  @{ @}
+        \paper @{ linewidth = 10.0\cm; @}
+@} 
+@end example 
+
+
+The result would look this@footnote{The titling and font size shown
+may differ, since the titling in this document is not generated by
+@file{ly2dvi}.}.
+
+@center @strong{The river is flowing}
+@center Traditional 
+
+@mudela[center]
+\header {
+        title = "The river is flowing";
+        composer = "Traditional (?)";
+}
+\include "paper16.ly"
+melody = \notes \relative c' {
+        \partial 8;
+        g8 |
+        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+        c4 c8 d [es () d] c4 | d4 es8 d c4.
+        \bar "|.";
+}
+
+text = \lyrics {
+        The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the
+        ri -- ver is flo -- wing down to the sea.
+}
+
+accompaniment =\chords {
+        r8
+        c2-3- f-3-.7 d-min es4 c8-min r8
+        c2-min f-min7 g-7^3.5 c-min }
+
+\score {
+        \simultaneous {
+%         \accompaniment
+          \context ChordNames \accompaniment
+
+          \addlyrics
+            \context Staff = mel {
+              \property Staff.noAutoBeaming = "1"
+              \property Staff.automaticMelismata = "1"
+              \melody 
+            }
+            \context Lyrics \text
+        }
+        \midi  { }
+        \paper { linewidth = 10.0\cm; }
+}
+@end mudela
+
+Again, we will dissect the file line by line.@example 
+
+        \header @{
+ 
+@end example 
+Information about the music you are about to typeset goes into a
+@code{\header} block.  The information in this block is not used by
+LilyPond, but it is included in the output.  @file{ly2dvi} uses this
+information to print titles above the music.
+@example 
+
+        title = "The river is flowing";
+        composer = "Traditional (?)"; 
+@end example 
+the @code{\header} block contains assignments.  An assignment starts
+with a string.  (which is unquoted, in this case). Then comes the
+equal sign `@code{=}'.  After the equal sign comes the expression you
+want to store.  In this case, you want to put in strings.  The
+information has to be quoted here, because it contains spaces. The
+assignment is finished with a semicolon.@example 
+
+        \include "paper16.ly"
+ 
+@end example 
+Smaller size for inclusion in a book.@example 
+
+        melody = \notes \relative c' @{
+ 
+@end example 
+The structure of the file will be the same as the previous one, a
+@code{\score} block with music in it.  To keep things readable, we will
+give names to the different parts of music, and use the names to
+construct the music within the score block.
+
+@example 
+
+        \partial 8;
+ 
+@end example 
+
+The piece starts with an anacrusis of one eighth.  @example 
+
+        c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g |
+        c4 c8 d [es () d] c4 | d4 es8 d c4.
+        \bar "|.";
+ 
+@end example 
+We use explicit beaming.  Since this is a song,  we will turn automatic
+beams off, and use explicit beaming where needed.@example 
+
+        @}
+ 
+@end example 
+This ends the definition of @code{melody}.  Note that there are no
+semicolons after assignments at top level.@example 
+
+        text = \lyrics @{
+ 
+@end example 
+Another identifier assignment.  This one is for the lyrics. 
+Lyrics are formed by syllables that have duration, and not by
+notes. To make LilyPond parse words as syllables,  switch it  into
+lyrics mode with @code{\lyrics}.  Again, the brace after @code{\lyrics}
+is a shorthand for @code{\sequential @{}. @example 
+
+        The4 ri -- ver is flo- __ wing,  flo -- wing and gro -- wing, the
+        ri- ver is flo- __ wing down to the sea.
+        @}
+ 
+@end example 
+The syllables  themselves are  separated by spaces.  You can get syllable
+extenders by entering `@code{__}', and centered hyphens with
+`@code{-}@code{-}'.  We enter the syllables as if they are all quarter notes
+in length (hence the @code{4}), and use a feature to align the
+syllables to the music (which obviously isn't all quarter notes.)
+@example 
+
+        accompaniment =\chords @{
+ 
+@end example 
+We'll put chords over the music.  There is a special mode (analogous
+to @code{\lyrics} and @code{\notes} mode) where you can give the names
+of the chords you want, instead of the notes comprising the chord.
+@example 
+
+        r8
+ 
+@end example 
+There is no accompaniment during the anacrusis.@example 
+
+        c2-3- f-3-.7
+ 
+@end example 
+A chord is started by  the tonic of the chord. The
+first one lasts a half note.  An unadorned note creates a major
+triad, while a minor triad is wanted.  @code{3-} modifies the third to
+be small. @code{7} modifies (adds) a seventh, which is small by default
+to create the @code{f a c es} chord.  Multiple modifiers must be
+separated by a dot.@example 
+
+        d-min es4 c8-min r8
+ 
+@end example 
+Some modifiers have predefined names, eg. @code{min} is  the same as
+@code{3-}, so @code{d-min} is a minor @code{d} chord.@example 
+
+        c2-min f-min7 g-7^3.5 c-min @}
+ 
+@end example 
+A named modifier @code{min} and a normal modifier @code{7} do not have
+to be separated by a dot.  Tones from a chord are removed with chord
+subtractions.  Subtractions are started with a caret, and they are
+also separated by dots.  In this example, @code{g-7^3.5} produces a
+minor seventh.  The brace ends the sequential music. @example 
+
+        \score @{
+                \simultaneous @{
+ 
+@end example 
+We assemble the music in the @code{\score} block.  Melody, lyrics and
+accompaniment have to sound at the same time, so they should be
+@code{\simultaneous}.@example 
+
+        %\accompaniment
+ 
+@end example 
+Chord mode generates notes grouped in @code{\simultaneous} music.  If
+you remove the comment sign, you can see the chords in normal
+notation: they will be printed as note heads on a separate
+staff. @example 
+
+        \context ChordNames \accompaniment
+ 
+@end example 
+Normally, the notes that you enter are transformed into note heads.
+The note heads alone make no sense, they need surrounding information:
+a key signature, a clef, staff lines, etc.  They need @emph{context}.  In
+LilyPond, these symbols are created by objects called `interpretation
+context'.  Interpretation contexts only exist during a run of
+LilyPond.  Interpretation contexts that are for printing music (as
+opposed to playing music) are called `notation context'.
+
+By default, LilyPond will create a Staff contexts for you.  If you
+would remove the @code{%} sign in the previous line, you can see that
+mechanism in action.
+
+We don't want default contexts here, because we want names, not note
+heads.  An interpretation context can also created upon explicit
+request. The keyword for such a request is @code{\context}.  It takes
+two arguments.  The first is the name of a interpretation context.
+The name is a string, it can be quoted with double quotes).  The
+second argument is the music that should be interpreted in this
+context.  For the previous line, we could have written @code{\context
+Staff \accompaniment}, and get the same effect.@example 
+
+        \addlyrics
+ 
+@end example 
+The lyrics need to be aligned with the melody.  This is done by
+combining both with @code{\addlyrics}.  @code{\addlyrics} takes two
+pieces of music (usually a melody and lyrics, in that order) and
+aligns the syllables of the second piece under the notes of the
+first piece.  If you would reverse the order, the notes would be
+aligned on the lyrics, which is not very useful. (Besides, it looks
+silly.)@example 
+
+        \context Staff = mel @{
+ 
+@end example 
+This is the argument of @code{\addlyrics}.  We instantiate a
+@code{Staff} context explicitly: should you chose to remove comment
+before the ``note heads'' version of the accompaniment, the
+accompaniment will be on a nameless staff.  The melody has to be on a
+different staff as the accompaniment.  This is accomplished by giving
+the melody staff a different name.@example 
+
+        \property Staff.noAutoBeaming = "1"
+ 
+@end example 
+An interpretation context has variables that tune its behaviour.  One
+of the variables is @code{noAutoBeaming}.  If set and non-zero (i.e.,
+true) LilyPond will not try to put automatic beaming on the current
+staff.@example 
+
+        \property Staff.automaticMelismata = "1"
+ 
+@end example 
+Similarly, we  don't want to print a  syllable when there is
+a slur. This sets up the Staff context to signal slurs while
+@code{\addlyrics} is processed. @example 
+
+          \melody
+        @}
+ 
+@end example 
+Finally, we put the melody on the current staff.  Note that the
+@code{\property} directives and @code{\melody} are grouped in sequential
+music,  so the property settings are done before the melody is
+processed.  @example 
+
+        \context Lyrics \text
+ 
+@end example 
+The second argument of @code{\addlyrics} is the text. The text also
+should not land on a Staff, but on a interpretation context for
+syllables, extenders, hyphens etc.  This context is called
+Lyrics.@example 
+
+        @}
+ 
+@end example 
+This ends @code{\simultaneous}.@example 
+
+        \midi  @{ @}
+ 
+@end example 
+This makes the music go to a MIDI file.  MIDI is great for
+checking music you enter.  You listen to the MIDI file: if you hear
+something unexpected, it's probably a typing error.  @code{\midi} is an
+`output definition', a declaration that specifies how to output music
+analogous to @code{\paper @{ @}}.@example 
+
+        \paper @{ linewidth = 10.0\cm; @}
+ 
+@end example 
+We also want notation output.  The linewidth is short so the piece
+will be set in two lines. @example 
+
+        @}
+ 
+@end example 
+End the score block.
+
+@node Piano music, , , Tutorial
+@section Piano music
+
+Our third subject is a piece piano music.  The fragment in the input
+file is a piano reduction of the G major Sinfonia by Giovanni Battista
+Sammartini.  It was composed around 1740. 
+
+@mudela[verbatim]
+
+\include "paper16.ly";
+
+viola = \notes \relative c' \context Voice = viola {
+        <c4-\f g' c>
+        \property Voice.verticalDirection = \down g'8. b,16
+        s1 s2. r4
+        g
+}
+
+oboes = \notes \relative c'' \context Voice = oboe {
+        \stemup s4  g8. b,16 c8 r <e'8.-\p g> <f16 a>
+        \grace <e8( g> <d4 f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> }
+        <
+          { \times 2/3 { a8 g c } \! c2 }
+          \context Voice = oboeTwo {
+                \stemdown
+                \grace {
+                    \property Grace.verticalDirection = \down
+                    [f,16 g] }
+                f8 e e2
+        } >
+        \stemboth
+        \grace <c,8( e> <)b8. d8.-\trill> <c16 e> | 
+        [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r  |
+        [<c16( e>  < )e8. g>] <c8 e,>
+}
+
+hoomPah  = \notes \transpose c' {
+    c8 \translator Staff = top \stemdown 
+    c'8 \translator Staff = bottom \stemup }
+
+hoomPahHoomPah = { [\hoomPah \hoomPah] }
+
+bassvoices = \notes \relative c' {
+        c4 g8. b,16
+        \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
+        \stemdown [c8 c'8] r4
+        <g d'> r4
+        < {\stemup r2 <e4 c'> <c8 g'> }
+          \context Voice = reallyLow  {\stemdown g2 ~ | g4 c8 } >
+}
+
+\score {
+        \context PianoStaff \notes <
+                \context Staff = top < \time 2/2;
+                        \context Voice = viola \viola
+                        \oboes
+                >
+                \context Staff = bottom < \time 2/2; \clef bass;
+                        \bassvoices
+                >
+        >
+        \midi { }
+        \paper {
+          indent = 0.0;
+          linewidth = 15.0 \cm; }
+}
+@end mudela
+
+If it looks like incomprehensible gibberish to you@dots{} Then you are
+right.  The author has doctored this example to have as many quirks in
+one system as possible.@example 
+viola = \notes \relative c'  \context Voice = viola @{ 
+@end example 
+In this example, you can see multiple parts on a staff.  Each part is
+associated with one notation context.  This notation context handles
+stems and dynamics (among others).  The name of this context is
+@code{Voice}.  For each part we have to make sure that there is
+precisely one Voice context@footnote{If @code{\context} would not
+have been specified explicitly, three @code{Voice} contexts would be
+created: one for each note  in the first chord.}.@example 
+<c4-\f g' c> 
+@end example 
+@code{<} and @code{>} are short hands for @code{\simultaneous @{} and
+@code{@}}. So the expression enclosed in @code{<} and @code{>} is a
+chord.  @code{\f} places a forte symbol  under the chord.@example 
+\property Voice.verticalDirection = \down 
+@end example 
+@code{verticalDirection} is a property of the voice context. It
+controls the directions of stems, articulations marks and other
+symbols.
+  If @code{verticalDirection} is set to @code{\down}
+(identifier for the integer -1) the stems go down,
+@code{\up} (identifier for the integer 1) makes the stems go up.@example 
+        g'8. b,16 
+@end example 
+Relative octaves work a little differently with chords.  The starting
+point for the note following a chord is the first note of the chord.  So
+the @code{g} gets an octave up quote: it is a fifth above the starting
+note of the previous chord (the central C).
+
+@example 
+s1 s2. r4 
+@end example 
+@code{s} is a `spacer' rest.  It does not print anything,  but it does
+have the duration of a rest.   @example 
+oboes = \notes \relative c'' \context Voice = oboe @{ 
+@end example 
+Now comes a part for two oboes.  They play homophonically, so we
+print the notes as one voice that makes chords. Again, we insure that
+these notes are indeed processed by precisely one context with
+@code{\context}.@example 
+\stemup s4  g8. b,16 c8 r <e'8.-\p g> <f16 a> 
+@end example 
+@code{\stemup} is an identifier reference.  It is shorthand for
+@code{\property Voice.verticalDirection = \up}.  If possible, you
+should use predefined identifiers like these for setting properties.
+Your input will be less dependent upon the implementation of LilyPond.
+@example 
+\grace <e8( g> < )d4 f> <c2 e> 
+@end example 
+@code{\grace} introduces grace notes.  It takes one argument, in this
+case a chord.  The slur started on the @code{e} of the chord
+will be attached to the next note.@footnote{LilyPond will squirm
+about unended Slurs.  In this case, you can ignore the warning}.
+@example 
+\times 2/3 
+@end example 
+Tuplets are made with the @code{\times} keyword.  It takes two
+arguments: a fraction and a piece of music.  The duration of the
+second argument is multiplied by the first argument.  Triplets make
+notes occupy 2/3 of their notated duration, so in this case the
+fraction is 2/3. @example 
+@{ <d8 \< f> <e g> <f a> @} 
+@end example 
+The piece of music to be `tripletted' is sequential music containing
+three notes.  On the first chord (the @code{d}), a crescendo is started
+with @code{\<}.@example 
+< 
+@end example 
+At this point, the homophonic music splits into two rhythmically
+different parts.  We can't use a sequence of chords to enter this, so
+we make a `chord' of sequences to do it.  We start with the upper
+voice, which continues with upward stems: @example 
+ @{ \times 2/3 @{ a8 g c @} \! c2 @} 
+@end example 
+The crescendo is ended at the half note by the escaped exclamation
+mark `@code{\!}'.  @example 
+\context Voice = oboeTwo @{
+\stemdown 
+@end example 
+We can't share stems with the other voice, so we have to create a new
+@code{Voice} context.  We give it the name @code{oboeTwo} to distinguish
+it from the other context.  Stems go down in this voice. @example 
+\grace @{  
+@end example 
+When a grace section is processed, a @code{Grace} context is
+created. This context acts like a miniature score of its own.  It has
+its own time bookkeeping, and you can make notes, beams, slurs
+etc. Here fiddle with a property and make a beam.  The argument of
+@code{\grace} is sequential music.@example 
+\property Grace.verticalDirection = \down
+[f,16 g] @} 
+@end example 
+Normally, grace notes are always stem up, but in this case, the upper
+voice interferes. We set the stems down here.
+
+As far as relative mode is concerned, the previous note is the
+@code{c'''2} of the upper voice, so we have to go an octave down for
+the @code{f}.
+@example 
+
+  f8 e e2
+@} > 
+@end example 
+This ends the two-part section. @example 
+\stemboth
+\grace <c,8( e> <)b8. d8.-\trill> <c16 e> |  
+@end example 
+@code{\stemboth} ends the forced stem directions. From here, stems are
+positioned as if it were single part music.
+
+The bass has a little hoom-pah melody to demonstrate parts switching
+between staffs.  Since it is repetitive, we use identifiers:@example 
+hoomPah  = \notes \transpose c' @{ 
+@end example 
+Transposing can be done with @code{\transpose}.  It takes two
+arguments; the first specifies what central C should be transposed to.
+The second is the to-be-transposed music.  As you can see, in this
+case, the transposition is a no-op.  Central C is transposed to
+central C.
+
+The purpose of this no-op is circumventing relative mode.  Relative
+mode can not be used in conjunction with transposition, so relative
+mode will leave the contents of @code{\hoomPah} alone.  We can use it
+without having to worry about getting the motive in a wrong
+octave@footnote{@code{hoomPah = \relative @dots{}} would be more
+intuitive to use, but that would not let me plug @code{\transpose}
+:-).}.@example 
+c8 \translator Staff = top \stemdown  
+@end example 
+We assume that the first note will be put in the lower staff.  After
+that note we switch to the upper staff with @code{\translator}.  To be
+precise, this @code{\translator} entry switches the current voice to a
+@code{Staff} named @code{top}. So we have to name the upper staff
+`@code{top}'.  Stem directions are set to avoid interfering with the
+oboe voices.  @example 
+c'8 \translator Staff = bottom \stemup @} 
+@end example 
+Then a note is put on the upper staff, and we switch again.  We have
+to name the lower staff `@code{bottom}'. @example 
+hoomPahHoomPah = @{ [\hoomPah \hoomPah] @} 
+@end example 
+Put two of these fragments in sequence, and beam them.@example 
+bassvoices = \notes \relative c' @{
+c4 g8. b,16
+\hoomPahHoomPah \hoomPahHoomPah \hoomPahHoomPah
+\hoomPahHoomPah 
+@end example 
+Entering the bass part is easy: the hoomPahHoomPah variable is
+referenced four times.@example 
+\context Voice = reallyLow  @{\stemdown g2 ~ | g4 c8 @} > 
+@end example 
+After skipping some lines, we see @code{~}.  This mark makes ties.@example 
+\context PianoStaff 
+@end example 
+For piano music, a special context is needed to get cross staff
+beaming right.  It is called @code{PianoStaff}.@example 
+\context Staff = bottom < \time 2/2; \clef bass; 
+@end example 
+The bottom staff must have a different clef.@example 
+indent = 0.0; 
+@end example 
+To make some more room on the line, the first (in this case the only)
+line is not indented.  The line still looks is very cramped, but that is due
+to the format of this tutorial.
+
+This example shows a lot of features, but the organisation isn't
+perfect.  For example, it would be less confusing to use a chord
+containing sequential music than a sequence of chords for the oboe
+parts.
+
+[TODO: demonstrate Hara-Kiri with scores and  part extraction.]
+
+@node  end of tutorial, , , Tutorial
+@section The end        
+         
+That's all folks.  From here, you can either try fiddling with input
+files, or you can read the reference manual.