From fa71711ed7c75abc8a30dfb898f58c47e07133a1 Mon Sep 17 00:00:00 2001
From: John Mandereau <john.mandereau@gmail.com>
Date: Fri, 5 Jan 2007 22:56:13 +0100
Subject: [PATCH] Backport user manual improvements from master branch

---
 Documentation/user/advanced-notation.itely    |  60 ++++-
 Documentation/user/basic-notation.itely       |  39 +++-
 Documentation/user/changing-defaults.itely    |  29 ++-
 Documentation/user/cheatsheet.itely           |  10 +-
 Documentation/user/instrument-notation.itely  |  24 +-
 Documentation/user/introduction.itely         |  60 ++++-
 Documentation/user/lilypond-book.itely        |  14 +-
 Documentation/user/music-glossary.tely        |   1 -
 Documentation/user/non-music.itely            | 117 ++++++----
 .../user/programming-interface.itely          |  32 ++-
 Documentation/user/putting.itely              |   3 +
 Documentation/user/spacing.itely              |  34 ++-
 Documentation/user/templates.itely            | 114 +++++++++
 Documentation/user/tutorial.itely             | 217 ++++++++++--------
 Documentation/user/tweaks.itely               |  16 ++
 Documentation/user/working.itely              |   3 +
 16 files changed, 580 insertions(+), 193 deletions(-)

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index bdcbfee6fb..553eff96d9 100644
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -309,9 +309,8 @@ but it can also be used anywhere text is called in lilypond
 }
 @end lilypond
 
-Text can also be placed on its own, away from any @code{\score}
-block.  This is primarily used in a @code{\book} (see
-@ref{Multiple scores in a book}).
+A @code{\markup} command can also be placed on its own, away from any
+@code{\score} block, see @ref{Multiple scores in a book}.
 
 @lilypond[quote,ragged-right,verbatim]
 \markup{ Here is some text. }
@@ -849,6 +848,20 @@ You may use @code{format-mark-barnumbers}, @code{format-mark-box-barnumbers},
 and @code{format-mark-circle-barnumbers} to get bar numbers instead of
 incremented numbers or letters.
 
+Other styles of rehearsal mark can be specified manually
+
+@example
+\mark "A1"
+@end example
+
+@noindent
+@code{Score.markFormatter} does not affect marks specified in this manner.
+However, it is possible to apply a @code{\markup} to the string.
+
+@example
+\mark \markup@{ \box A1 @}
+@end example
+
 @cindex segno
 @cindex coda
 @cindex D.S al Fine
@@ -894,6 +907,8 @@ appears at that point in the music.
 
 @seealso
 
+This manual: @ref{Text marks}.
+
 Program reference: @internalsref{RehearsalMark}.
 
 Init files: @file{scm/@/translation@/-functions@/.scm} contains the
@@ -1058,6 +1073,19 @@ be added to that context.
 More information about adding and removing engravers can
 be found in @ref{Modifying context plug-ins}.
 
+Instrument names may be changed in the middle of a piece,
+
+@lilypond[quote,fragment,verbatim,ragged-right]
+\set Staff.instrumentName = "First"
+\set Staff.shortInstrumentName = "one"
+c1 c c c \break
+c1 c c c \break
+\set Staff.instrumentName = "Second"
+\set Staff.shortInstrumentName = "two"
+c1 c c c \break
+c1 c c c \break
+@end lilypond
+
 
 @seealso
 
@@ -1141,9 +1169,9 @@ the staff.  They are created by invoking the function
 }
 @end lilypond
 
-The @code{set-octavation} function also takes -1 (for 8va bassa) and 2
-(for 15ma) as arguments.  Internally the function sets the properties
-@code{ottavation} (e.g., to @code{"8va"}) and
+The @code{set-octavation} function also takes -1 (for 8va bassa), 2@tie{}(for 15ma),
+and -2 (for 15ma bassa) as arguments.  Internally the function sets the properties
+@code{ottavation} (e.g., to @code{"8va"} or @code{"8vb"}) and
 @code{centralCPosition}.  For overriding the text of the bracket, set
 @code{ottavation} after invoking @code{set-octavation}, i.e.,
 
@@ -1405,7 +1433,7 @@ or @code{\RemoveEmptyRhythmicStaffContext}.
 
 Another application is making ossia sections, i.e., alternative
 melodies on a separate piece of staff, with help of a Frenched
-staff.  See @inputfileref{input/@/test,ossia@/.ly} for an example.
+staff.  
 
 
 @node Quoting other voices
@@ -1691,7 +1719,7 @@ created with a markup text.  This markup text is inserted in the
 tsMarkup =\markup {
   \override #'(baseline-skip . 2) \number {
     \column { "2" "4" }
-    \lower #1 "+"
+    \vcenter "+"
     \bracket \column { "5" "8" }
   }
 }
@@ -2114,6 +2142,7 @@ teaching tools in addition to great musical scores.
 * Analysis brackets::           
 * Coloring objects::            
 * Parentheses::                 
+* Grid lines::                  
 @end menu
 
 @node Balloon help
@@ -2161,6 +2190,7 @@ removing @code{Bar_number_engraver}.
 
 
 @lilypond[quote,verbatim]
+\layout{ indent = #0 }
 emptymusic = {
   \repeat unfold 2 % Change this for more lines.
   { s1\break }
@@ -2168,9 +2198,13 @@ emptymusic = {
 }
 \new Score \with {
   \override TimeSignature #'transparent = ##t
+% un-comment this line if desired
+%  \override Clef #'transparent = ##t
   defaultBarType = #""
   \remove Bar_number_engraver
 } <<
+
+% modify these to get the staves you want
   \new Staff \emptymusic
   \new TabStaff \emptymusic
 >>
@@ -2255,7 +2289,7 @@ used in music for beginners
 The command @code{\setEasyHeads} overrides settings for the
 @internalsref{NoteHead} object.  To make the letters readable, it has
 to be printed in a large font size.  To print with a larger font, see
-@ref{Setting global staff size}.
+@ref{Setting the staff size}.
 
 @refcommands
 
@@ -2402,3 +2436,11 @@ This only functions inside chords, even for single notes
 @end example
 
 
+@node Grid lines
+@subsection Grid lines
+
+Vertical lines can be drawn between staves synchronized with
+the notes.
+
+Examples: @inputfileref{input/@/regression,grid@/-lines@/.ly}.
+
diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely
index 676ee7fed9..dddc793973 100644
--- a/Documentation/user/basic-notation.itely
+++ b/Documentation/user/basic-notation.itely
@@ -1147,6 +1147,10 @@ Similarly, you can merge half note heads with eighth notes, by setting
 c8 c4. } \\ { c2 c2 } >>
 @end lilypond
 
+@noindent
+@code{merge-differently-headed} and @code{merge-differently-dotted}
+only apply to opposing stem directions (ie. Voice 1 & 2).
+
 LilyPond also vertically shifts rests that are opposite of a stem,
 for example
 
@@ -1753,6 +1757,24 @@ in every context, and that type is determined by the property
 @internalsref{systemStartDelimiter}.
 
 
+@commonprop
+
+System start delimiters may be deeply nested,
+
+@lilypond[quote,ragged-right,verbatim]
+\new StaffGroup 
+\relative <<
+  \set StaffGroup.systemStartDelimiterHierarchy
+    = #'(SystemStartSquare (SystemStartBracket a (SystemStartSquare b)) d)
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+  \new Staff { c1 }
+>>
+@end lilypond
+
+
 @node Staff symbol
 @subsection Staff symbol
 
@@ -1782,8 +1804,7 @@ b b
 @end lilypond
 
 In combination with Frenched staves, this may be used to typeset ossia
-sections. An example is in @inputfileref{input/@/test@/,ossia.ly},
-shown here
+sections. An example is shown here
 
 @cindex ossia
 
@@ -1950,13 +1971,25 @@ notes need not be consecutive.  This can be achieved by setting the
 @code{tieWaitForNote} property to true. The same feature is also useful,
 for example, to tie a tremolo to a chord. For example,
 
-@lilypond[fragment,verbatim,relative=1,ragged-right]
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
 \set tieWaitForNote = ##t
 \grace { c16[~ e~ g]~ } <c, e g>2
 \repeat "tremolo" 8 { c32~ c'~ } <c c,>1
 e8~ c~ a~ f~ <e' c a f>2
 @end lilypond
 
+Ties may be engraved manually by changing the @code{tie-configuration}
+property.  The first number indicates the distance from the center
+of the staff in staff-spaces, and the second number indicates the
+direction (1=up, -1=down).
+
+@lilypond[fragment,verbatim,relative=1,ragged-right,quote]
+<c e g>2~ <c e g> |
+\override TieColumn #'tie-configuration =
+  #'((0.0 . 1) (-2.0 . 1) (-4.0 . 1))
+<c e g>~ <c e g> |
+@end lilypond
+
 
 @refcommands
 
diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 8e4810dcf0..f54ccc8762 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -436,6 +436,7 @@ This section describes what contexts are, and how to modify them.
 * Layout tunings within contexts::  
 * Changing context default settings::  
 * Defining new contexts::       
+* Aligning contexts::           
 @end menu
 
 
@@ -634,8 +635,8 @@ To have it interpreted at the @context{Score} or @context{Staff} level use
 these forms
 
 @example
-\context \applyOutput #'Score #@var{function}
-\context \applyOutput #'Staff #@var{function}
+\applyOutput #'Score #@var{function}
+\applyOutput #'Staff #@var{function}
 @end example
 
 @end itemize
@@ -1214,6 +1215,30 @@ Then the output at the start of this subsection can be entered as
 @end example
 
 
+@node Aligning contexts
+@subsection Aligning contexts
+
+New contexts may be aligned above or below exisiting contexts.  This
+could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+in ossia,
+
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
+
+@lilypond[quote,ragged-right]
+ossia = { f4 f f f }
+\score{
+  \relative c' \new Staff = "main" {
+    c4 c c c
+    <<
+      \new Staff \with {alignAboveContext=main} \ossia
+      { d8 f d f d f d f }
+    >>
+  }
+}
+@end lilypond
+
 
 
 @node The \override command
diff --git a/Documentation/user/cheatsheet.itely b/Documentation/user/cheatsheet.itely
index c09b9d9d11..6b7dd5ae3f 100644
--- a/Documentation/user/cheatsheet.itely
+++ b/Documentation/user/cheatsheet.itely
@@ -178,14 +178,14 @@ c\mf c\sfz
 @end lilypond
 
 
-@item @code{a\< a \!a}
+@item @code{a\< a a\!}
 @tab crescendo
 @tab
 @lilypond[fragment,relative=2]
 \set Score.timing = ##f
 \override Staff.TimeSignature #'break-visibility = #all-invisible
 \set Staff.autoBeaming = ##f
-a\< a \!a
+a\< a a\!
 @end lilypond
 
 @item @code{a\> a a\!}
@@ -234,12 +234,12 @@ f8 c2 d e
 @item @code{\lyricmode @{ twinkle @}}
 @tab entering lyrics
 @tab
+twinkle
 
 
 @item @code{\new Lyrics}
 @tab printing lyrics
 @tab
-twinkle
 @lilypond[fragment]
 \new Lyrics \lyricmode { twinkle }
 @end lilypond
@@ -249,7 +249,7 @@ twinkle
 @tab
 @lilypond[fragment,relative=2]
 <<
-   { g'4 g }
+   { g'1 g }
   \new Lyrics \lyricsto "" { twin -- kle }
 >> 
 @end lilypond
@@ -268,7 +268,7 @@ twinkle
 \chords { c:dim f:maj7 }
 @end lilypond
 
-@item @code{<<@{e f@} \\@{c d@}>>}
+@item @code{<<@{e f@} \\ @{c d@}>>}
 @tab polyphony
 @tab
 @lilypond[fragment,relative=2]
diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index f4c6043af3..adfe4ef9de 100644
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -155,7 +155,7 @@ usually the setup for a score will start with a setup of the staves,
 and the @context{Voice} is inserted afterwards
 
 @example
-\new Staff = down
+\context Staff = down
   \new Voice @{ @dots{} \change Staff = up @dots{} @}
 @end example
 
@@ -1294,25 +1294,16 @@ It is also possible to define melismata entirely in the lyrics. This
 can be done by entering @code{_} for every note that is part of the
 melisma.
 
-@lilypond[relative=1,verbatim,fragment]
+@lilypond[relative=1,verbatim,fragment,quote]
 { \set melismaBusyProperties = #'()
   c d( e) f f( e) e e  }
 \addlyrics
  { Ky -- _ _ ri __ _ _ _  e }
 @end lilypond
 
-In this case, you can also have ties and slurs in the melody, if you
+In this case, you can also have ties and slurs in the melody if you
 set @code{melismaBusyProperties}, as is done in the example above.
 
-@lilypond[relative=1,verbatim,fragment,quote]
-{
- \set melismaBusyProperties = #'()
-  c d( e) f f( e) e e
-}
-\addlyrics
- { Ky -- _ _ ri __ _ _ _  e }
-@end lilypond
-
 
 @node Lyrics independent of notes
 @subsubsection Lyrics independent of notes
@@ -4555,6 +4546,15 @@ automatically.
 @end lilypond
 
 
+@refbugs
+
+When using figured bass above the staff with extender lines and
+@code{implicitBassFigures} the lines may become swapped around.
+Maintaining order consistently will be impossible when multiple figures
+have overlapping extender lines.  To avoid this problem, plese
+use @code{stacking-dir} on @code{BassFigureAlignment}.
+
+
 @seealso
 
 Program reference: @internalsref{NewBassFigure},
diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index b15ecfeb1c..caf6d1715c 100644
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -60,11 +60,11 @@ one.  It is rounded, and its weight harmonizes with the thickness of
 our staff lines, which are also much thicker than lines in the
 computer edition.
 
-@multitable @columnfractions .05 .3 .3 .3 .05
+@multitable @columnfractions .125 .25 .25 .25 .125
 @item @tab
 @ifnotinfo
 @iftex
-@image{henle-flat-gray,,8cm}
+@image{henle-flat-gray,,4cm}
 @end iftex
 @ifnottex
 @image{henle-flat-gray,,,png}
@@ -72,7 +72,7 @@ computer edition.
 
 @tab
 @iftex
-@image{baer-flat-gray,,8.4cm}
+@image{baer-flat-gray,,4cm}
 @end iftex
 @ifnottex
 @image{baer-flat-gray,,,png}
@@ -80,7 +80,7 @@ computer edition.
 
 @tab
 @iftex
-@image{lily-flat-bw,,8cm}
+@image{lily-flat-bw,,4cm}
 @end iftex
 @ifnottex
 @image{lily-flat-bw,,,png}
@@ -508,6 +508,7 @@ and the @code{Stem_engraver} adds stems.
 }
 @end lilypond
 
+@noindent
 The @code{Stem_engraver} is notified of any note head coming along.
 Every time one (or more, for a chord) note head is seen, a stem
 object is created and connected to the note head.  By adding
@@ -700,15 +701,20 @@ The
 gives a gentle introduction to typesetting music.  First time
 users should start here.
 
+@item
+@emph{@ref{Putting it all together}}
+explains some general concepts about the lilypond file format.  If
+you are not certain where to place a command, read this chapter!
+
 @item
 @emph{@ref{Working on LilyPond projects}}
-demonstrates practical uses of LilyPond.
+discusses practical uses of LilyPond and how to avoid some common
+problems.
 
 @item
-@emph{@ref{Running LilyPond}}
-shows how to run LilyPond and its helper
-programs.  In addition, this section explains how to upgrade input
-files from previous versions of LilyPond.
+@emph{@ref{Tweaking output}}
+shows how to change the default engraving that LilyPond
+produces.
 
 @item
 @emph{@ref{Basic notation}}
@@ -741,6 +747,16 @@ and how to select which MIDI instruments to use.
 discusses issues which affect the global output, such as selecting
 paper size or specifying page breaks.
 
+@item
+@emph{@ref{Interfaces for programmers}}
+explains how to create music functions.
+
+@item
+@emph{@ref{Running LilyPond}}
+shows how to run LilyPond and its helper
+programs.  In addition, this section explains how to upgrade input
+files from previous versions of LilyPond.
+
 @item
 @emph{@ref{LilyPond-book}} explains the details behind creating
 documents with in-line music examples, like this manual.
@@ -759,11 +775,37 @@ The
 contains a set of useful reference books for those who wish to know
 more on notation and engraving.
 
+@item
+The
+@emph{@ref{Scheme tutorial}}
+presents a short introduction to scheme, the programming
+language that music functions use.
+
+@item
+@emph{@ref{Notation manual tables}}
+are a set of tables showing the chord names, MIDI instruments,
+a list of color names, and the Feta font.
+
 @item
 @emph{@ref{Example templates}}
 provides templates of LilyPond pieces.  Just cut and paste a
 template into a file, add notes, and you're done!
 
+@item
+The
+@emph{@ref{Cheat sheet}}
+is a handy reference of the most common LilyPond commands.
+
+@item
+The
+@emph{@ref{LilyPond command index}}
+is an index of all LilyPond @code{\commands}.
+
+@item
+The
+@emph{@ref{LilyPond index}}
+is a complete index.
+
 @end itemize
 
 
diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 45aa7d4f7f..bc15506b73 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -42,11 +42,12 @@ This procedure may be applied to La@TeX{}, HTML, Texinfo or DocBook documents.
 * Integrating LaTeX and music::  
 * Integrating Texinfo and music::  
 * Integrating HTML and music::  
-* Integrating DocBook and music::
+* Integrating DocBook and music::  
 * Music fragment options::      
 * Invoking lilypond-book::      
 * Filename extensions::         
 * Many quotes of a large score::  
+* Inserting LilyPond output into OpenOffice.org::  
 * Inserting LilyPond output into other programs::  
 @end menu
 
@@ -847,12 +848,23 @@ output format based on the input filename's extension.
 @end multitable
 @end quotation
 
+
 @node Many quotes of a large score
 @section Many quotes of a large score
 
 If you need to quote many fragments of a large score, you can also use
 the clip systems feature, see @ref{Extracting fragments of notation}.
 
+
+@node Inserting LilyPond output into OpenOffice.org
+@section Inserting LilyPond output into OpenOffice.org
+
+@cindex OpenOffice.org
+
+LilyPond notation can be added to OpenOffice.org with
+@uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
+
+
 @node Inserting LilyPond output into other programs
 @section Inserting LilyPond output into other programs
 
diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely
index 55e07d2b2a..24f83d3697 100644
--- a/Documentation/user/music-glossary.tely
+++ b/Documentation/user/music-glossary.tely
@@ -3271,7 +3271,6 @@ subject.
 \score{
 \relative c'' {
   \override Score.TimeSignature #'break-visibility = #all-invisible
-  %\override Score.TextScript #'font-style = #'large
   \time 4/4
   \key g \major
   \partial 8 g16\startGroup fis |
diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index c29fcfe82e..522ddef67f 100644
--- a/Documentation/user/non-music.itely
+++ b/Documentation/user/non-music.itely
@@ -104,23 +104,29 @@ and texts are entered with a @code{\markup} block,
 
 @funindex \book
 
-The movements and texts are combined together in a @code{\book} block,
-like
+All the movements and texts which appear in the same @code{.ly} file 
+will normally be typeset in the form of a single output file. 
 
 @example
-\book @{
-  \score @{
-    @var{..}
-  @}
-  \markup @{
-    @var{..}
-  @}
-  \score @{
-    @var{..}
-  @}
+\score @{
+  @var{..}
+@}
+\markup @{
+  @var{..}
+@}
+\score @{
+  @var{..}
 @}
 @end example
 
+However, if you want multiple output files from the same @code{.ly}
+file, then you can add multiple @code{\book} blocks, where each such
+@code{\book} block will result in a separate output. If you do not
+specify any @code{\book} block in the file, LilyPond will implicitly
+treat the full file as a single @code{\book} block, see @ref{File
+structure}. One important exception is within lilypond-book documents,
+where you explicitly have to add a @code{\book} block, otherwise only
+the first @code{\score} or @code{\markup} will appear in the output.
 
 The header for each piece of music can be put inside the @code{\score}
 block.  The @code{piece} name from the header will be printed before
@@ -129,25 +135,23 @@ each movement.  The title for the entire book can be put inside the
 the top of the file is inserted.
 
 @example
-\book @{
-  \header @{
-    title = "Eight miniatures"
-    composer = "Igor Stravinsky"
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Romanze" @}
-  @}
-  \markup @{
-     ..text of second verse..
-  @}
-  \markup @{
-     ..text of third verse..
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Menuetto" @}
-  @}
+\header @{
+  title = "Eight miniatures"
+  composer = "Igor Stravinsky"
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Romanze" @}
+@}
+\markup @{
+   ..text of second verse..
+@}
+\markup @{
+   ..text of third verse..
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Menuetto" @}
 @}
 @end example
 
@@ -227,8 +231,13 @@ contain only one music expression.
 @item
 A @code{\book} block logically combines multiple movements
 (i.e., multiple @code{\score} blocks) in one document.  If there are
-a number of @code{\scores}, a single output file will be created
-in which all movements are concatenated.
+a number of @code{\scores}, one output file will be created for
+each @code{\book} block, in which all corresponding movements are
+concatenated. The only reason to explicitly specify @code{\book} blocks
+in a @code{.ly} file is if you wish multiple output files from a single
+input file. One exception is within lilypond-book documents, where you
+explicitly have to add a @code{\book} block if you want more than a
+single @code{\score} or @code{\markup} in the same example.
 
 This behavior can be changed by setting the variable
 @code{toplevel-book-handler} at toplevel.  The default handler is
@@ -274,6 +283,9 @@ A markup text, a verse for example
 Markup texts are rendered above, between or below the scores or music
 expressions, wherever they appear.
 
+@cindex variables
+@cindex identifiers
+
 @item
 An identifier, such as
 @example
@@ -475,8 +487,8 @@ some pieces include a lot more information.
 @node Creating titles
 @subsection Creating titles
 
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
+Titles are created for each @code{\score} block, and for the full input
+file (or @code{\book} block).
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
@@ -667,14 +679,13 @@ variables in the @code{\paper} block.  The init file
 @table @code
 @funindex bookTitleMarkup
 @item bookTitleMarkup
-  This is the title put over an entire @code{\book} block.  Typically,
-  it has the composer and the title of the piece
+  This is the title added at the top of the entire output document.
+Typically, it has the composer and the title of the piece
 
 @funindex scoreTitleMarkup
 @item scoreTitleMarkup
-  This is the title put over a @code{\score} block within a
-@code{\book}.  Typically, it has the name of the movement (@code{piece}
-field).
+  This is the title put over a @code{\score} block.  Typically, it has
+the name of the movement (@code{piece} field).
 
 @funindex oddHeaderMarkup
 @item oddHeaderMarkup
@@ -692,7 +703,7 @@ field).
 @item oddFooterMarkup
   This is the page footer for odd-numbered pages.
 
-@funindex evenFotterMarkup
+@funindex evenFooterMarkup
 @item evenFooterMarkup
   This is the page footer for even-numbered pages.  If unspecified,
   the odd header is used instead.
@@ -769,15 +780,29 @@ to a score, for example,
 @example
 \score @{
   @var{...music...}
-  \midi @{  @}
+   \midi @{
+     \context @{
+       \Score
+       tempoWholesPerMinute = #(ly:make-moment 72 4)
+       @}
+     @}
 @}
 @end example
 
-FIXME
-
-The tempo is specified using the @code{\tempo} command.  In this
-example the tempo of quarter notes is set to 72 beats per minute.
+The tempo can be specified using the @code{\tempo} command within the 
+actual music, see @ref{Metronome marks}.  An alternative, which does not
+result in a metronome mark in the printed score, is shown in the example
+above. In this example the tempo of quarter notes is set to 72 beats per
+minute. 
+This kind of tempo
+specification can not take dotted note lengths as an argument. In this
+case, break the dotted notes into smaller units. For example, a tempo
+of 90 dotted quarter notes per minute can be specified as 270 eighth
+notes per minute
 
+@example
+tempoWholesPerMinute = #(ly:make-moment 270 8)
+@end example
 
 If there is a @code{\midi} command in a @code{\score}, only MIDI will
 be produced.  When notation is needed too, a @code{\layout} block must
diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index 7bc78c6396..f646f6a965 100644
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -20,7 +20,7 @@ not familiar with Scheme, you may wish to read our
 * Building complicated functions::  
 * Markup programmer interface::  
 * Contexts for programmers::    
-* Scheme procedures as properties::
+* Scheme procedures as properties::  
 @end menu
 
 
@@ -35,6 +35,7 @@ This section discusses how to create music functions within LilyPond.
 * Paired substitution functions::  
 * Mathematics in functions::    
 * Void functions::              
+* Functions without arguments::  
 @end menu
 
 @node Overview of music functions
@@ -245,6 +246,35 @@ noPointAndClick =
 @end example
 
 
+@node Functions without arguments
+@subsection Functions without arguments
+
+In most cases a function without arguments should be written
+with an identifier,
+
+@example
+dolce = \markup@{ \italic \bold dolce @}
+@end example
+
+However, in rare cases it may be useful to create a music function
+without arguments,
+
+@example
+displayBarNum =
+#(define-music-function (parser location) ()
+   (if (eq? #t (ly:get-option display-bar-numbers))
+       #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
+       #@{#@}))
+@end example
+
+To actually display bar numbers where this function is called,
+invoke lilypond with
+
+@example
+lilypond -d display-bar-numbers FILENAME.ly
+@end example
+
+
 @node Programmer interfaces
 @section Programmer interfaces
 
diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely
index 6d197c8c56..7e8f45fb51 100644
--- a/Documentation/user/putting.itely
+++ b/Documentation/user/putting.itely
@@ -291,6 +291,9 @@ Some people put some of those commands outside the
 often placed above the @code{\score}.  That's just
 another shorthand that LilyPond accepts.
 
+@cindex variables
+@cindex indentifiers
+
 Another great shorthand is the ability to define
 variables.  All the templates use this
 
diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 919301aaaf..ac1035d877 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -235,8 +235,8 @@ book and the title of a piece). Default is@tie{}2mm.
 
 @funindex printallheaders
 @item printallheaders
-Setting this to #t will print all headers for each \score in a
-\book.  Normally only the piece and opus \headers are printed.
+Setting this to #t will print all headers for each \score in the
+output.  Normally only the piece and opus \headers are printed.
 
 @funindex systemSeparatorMarkup
 @item systemSeparatorMarkup
@@ -338,19 +338,20 @@ add space between the titles and the first system of the score.
 @section Music layout
 
 @menu
-* Setting global staff size::   
+* Setting the staff size::   
 * Score layout::                
 @end menu
 
 
-@node Setting global staff size
-@subsection Setting global staff size
+@node Setting the staff size
+@subsection Setting the staff size
 
 @cindex font size, setting
 @cindex staff size, setting
 @funindex layout file
 
-To set the global staff size, use @code{set-global-staff-size}.
+To set the staff size globally for all scores in a file (or
+in a @code{book} block, to be precise), use @code{set-global-staff-size}.
 
 @example
 #(set-global-staff-size 14)
@@ -360,6 +361,16 @@ To set the global staff size, use @code{set-global-staff-size}.
 This sets the global default size to 14pt staff height and scales all
 fonts accordingly.
 
+To set the staff size individually for each score, use 
+@example
+\score@{
+  ...
+  \layout@{
+  #(layout-set-staff-size 15)
+  @}
+@}
+@end example
+
 The Feta font provides musical symbols at eight different
 sizes.  Each font is tuned for a different staff size: at a smaller size
 the font becomes heavier, to match the relatively heavier staff lines.
@@ -820,6 +831,11 @@ c16[ c c8]
 @end lilypond
 
 
+The @code{\newSpacingSection} command creates a new
+@internalsref{SpacingSpanner} object, and hence new @code{\override}s
+may be used in that location.
+
+
 @node Changing horizontal spacing
 @subsection Changing horizontal spacing
 
@@ -828,7 +844,9 @@ Horizontal spacing may be altered with the
 we compare the same music; once without altering
 the property, and then altered.  Larger values
 of @code{ly:make-moment} will produce smaller
-music.
+music.  Note that @code{ly:make-moment} constructs
+a duration, so @code{1 4} is a longer duration
+than @code{1 16}.
 
 @lilypond[relative,verbatim,line-width=12\cm]
 \score {
@@ -853,7 +871,7 @@ music.
     \context {
       \Score
       \override SpacingSpanner
-                #'base-shortest-duration = #(ly:make-moment 1 4)
+                #'base-shortest-duration = #(ly:make-moment 1 16)
     }
   }
 }
diff --git a/Documentation/user/templates.itely b/Documentation/user/templates.itely
index 69cd035be5..fca2900d65 100644
--- a/Documentation/user/templates.itely
+++ b/Documentation/user/templates.itely
@@ -731,6 +731,120 @@ bassWords = \lyricmode {
 }
 @end lilypond
 
+@appendixsubsec SATB with aligned contexts
+
+Here all the lyrics lines are placed using @code{alignAboveContext}
+and @code{alignBelowContext}.
+
+@lilypond[quote,verbatim,ragged-right]
+\version "2.10.0"
+global = {
+  \key c \major
+  \time 4/4
+}
+
+sopMusic = \relative c'' {
+  c4 c c8[( b)] c4
+}
+sopWords = \lyricmode {
+  hi hi hi hi
+}
+
+altoMusic = \relative c' {
+  e4 f d e
+}
+altoWords =\lyricmode {
+  ha ha ha ha
+}
+
+tenorMusic = \relative c' {
+  g4 a f g
+}
+tenorWords = \lyricmode {
+  hu hu hu hu
+}
+
+bassMusic = \relative c {
+  c4 c g c
+}
+bassWords = \lyricmode {
+  ho ho ho ho
+}
+
+\score {
+  \new ChoirStaff <<
+     \new Staff = women <<
+        \new Voice =
+          "sopranos" { \voiceOne << \global \sopMusic >> }
+        \new Voice =
+          "altos" { \voiceTwo << \global \altoMusic >> }
+     >>
+     \new Lyrics \with {alignAboveContext=women} \lyricsto sopranos \sopWords
+     \new Lyrics \with {alignBelowContext=women} \lyricsto altos \altoWords
+% we could remove the line about this with the line below, since we want
+% the alto lyrics to be below the alto Voice anyway.
+%    \new Lyrics \lyricsto altos \altoWords
+
+     \new Staff = men <<
+        \clef bass
+        \new Voice =
+          "tenors" { \voiceOne <<\global \tenorMusic >> }
+        \new Voice =
+          "basses" { \voiceTwo <<\global \bassMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=men} \lyricsto tenors \tenorWords
+     \new Lyrics \with {alignBelowContext=men} \lyricsto basses \bassWords
+% again, we could replace the line above this with the line below.
+%    \new Lyrics \lyricsto basses \bassWords
+  >>
+
+  \layout {
+     \context {
+        % a little smaller so lyrics
+        % can be closer to the staff
+        \Staff
+        \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+     }
+  }
+}
+
+
+\score {
+  \new ChoirStaff <<
+     \new Staff = women <<
+        \new Voice =
+          "sopranos" { \voiceOne << \global \sopMusic >> }
+        \new Voice =
+          "altos" { \voiceTwo << \global \altoMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=women} \lyricsto sopranos \sopWords
+     \new Lyrics \lyricsto altos \altoWords
+
+     \new Staff = men <<
+        \clef bass
+        \new Voice =
+          "tenors" { \voiceOne <<\global \tenorMusic >> }
+        \new Voice =
+          "basses" { \voiceTwo <<\global \bassMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=men} \lyricsto tenors \tenorWords
+     \new Lyrics \lyricsto basses \bassWords
+  >>
+
+  \layout {
+     \context {
+        % a little smaller so lyrics
+        % can be closer to the staff
+        \Staff
+        \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+     }
+  }
+} 
+@end lilypond
+
 
 @c bad node name to avoid node name confict
 @node Ancient notation templates
diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 040e8ced67..d4fd147a15 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -20,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
@@ -48,7 +47,7 @@ commands for quick reference.
 
 @menu
 * First steps::                 
-* Running LilyPond for the first time::  
+* Second steps::                
 * More about pitches::          
 * Entering ties::               
 * Automatic and manual beams::  
@@ -79,21 +78,126 @@ 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
+@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.
+
+@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 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
+
+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' 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.
+
+
+@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' 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 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 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...} @}}.
@@ -104,6 +208,11 @@ space, using @code{\paper @{ ragged-right = ##t @}}.
 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
@@ -193,7 +302,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
@@ -218,89 +326,6 @@ see @ref{Time signature}.
 @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
 
@@ -931,10 +956,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.8, use
 
 @example
-\version "2.9.13"
+\version "2.10.8"
 @end example
 
 @noindent
diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely
index a614744c2a..fefdf6569b 100644
--- a/Documentation/user/tweaks.itely
+++ b/Documentation/user/tweaks.itely
@@ -21,6 +21,7 @@ configurable; virtually every fragment of output may be changed.
 * Default files::               
 * Fitting music onto fewer pages::  
 * Advanced tweaks with Scheme::  
+* Avoiding tweaks with slower processing::  
 @end menu
 
 
@@ -493,3 +494,18 @@ pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
 }
 @end lilypond
 
+
+@node Avoiding tweaks with slower processing
+@section Avoiding tweaks with slower processing
+
+LilyPond can perform extra checks while it processes files.  These
+commands will take extra time, but the result may require fewer
+manual tweaks.
+
+@example
+%%  makes sure text scripts and lyrics are within the paper margins
+\override Score.PaperColumn #'keep-inside-line = ##t 
+@end example
+
+
+
diff --git a/Documentation/user/working.itely b/Documentation/user/working.itely
index c27b9deae8..7ca5fa4834 100644
--- a/Documentation/user/working.itely
+++ b/Documentation/user/working.itely
@@ -189,6 +189,9 @@ g4\fthenp c'8. e16
 @node Saving typing with identifiers and functions
 @section Saving typing with identifiers and functions
 
+@cindex variables
+@cindex identifiers
+
 By this point, you've seen this kind of thing:
 
 @lilypond[quote,verbatim,ragged-right]
-- 
2.39.5