From: gpercival <gpercival>
Date: Thu, 25 Aug 2005 06:28:18 +0000 (+0000)
Subject: Various doc backports, excluding new features in 2.7.
X-Git-Tag: release/2.6.4~15
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=73c63f130c5ce97dc64f6e1081a8b0ae66a64c74;p=lilypond.git

Various doc backports, excluding new features in 2.7.
---

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 674be75b44..8647bbd1c1 100644
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -38,7 +38,6 @@ your scores.
 * Overview of text markup commands::  
 * Font selection::              
 * New dynamic marks::           
-* Other text markup issues::    
 @end menu
 
 
@@ -102,6 +101,10 @@ c1
 \textSpannerDown
 \override TextSpanner #'edge-text = #'("rall " . "")
 c2\startTextSpan b c\stopTextSpan a
+\break
+\textSpannerUp
+\override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 
 @refcommands
@@ -215,9 +218,10 @@ but it can also be used anywhere text is called in lilypond
 
     \set Staff.instrument = \markup{ \column{ Alto solo } }
     c2^\markup{ don't be \flat }
-    b2
+    \override TextSpanner #'edge-text = #(cons (markup #:italic "rit" ) "")
+    b2\startTextSpan
     a2\mark \markup{ \large \bold Fine }
-    r2
+    r2\stopTextSpan
     \bar "||"
   }
   \addlyrics { bar, foo \markup{ \italic bar! } }
@@ -293,6 +297,19 @@ whole.  For example, the @internalsref{RehearsalMark} is horizontally
 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
 effect.
 
+In addition, vertical placement is performed after creating the
+text markup object.  If you wish to move an entire piece of markup,
+you need to use the #'padding property or create an "anchor" point
+inside the markup (generally with @code{\hspace #0}).
+
+@lilypond[quote,verbatim,fragment,relative=1]
+\fatText
+c'4^\markup{ \raise #5 "not raised" }
+\once \override TextScript #'padding = #3
+c'4^\markup{ raised }
+c'4^\markup{ \hspace #0 \raise #1.5 raised }
+@end lilypond
+
 
 @seealso
 
@@ -490,22 +507,6 @@ boxf = \markup{ \bracket { \dynamic f } }
 @end lilypond
 
 
-@node Other text markup issues
-@subsection Other text markup issues
-
-To use a normal font within a title, you must define it manually
-
-@example
-#(def-markup-command (normal-font layout props arg) (markup?)
-  "Switch to normal text font"
-  (interpret-markup layout (cons '((font-series . 'medium) (font-shape . 'upright)) props) arg))
-
-\header@{
-  title = \markup@{ ABCD \normal-font ABCD @}
-@}
-@end example
-
-
 
 @node Preparing parts
 @section Preparing parts
@@ -529,13 +530,15 @@ individual parts.
 @subsection Multi measure rests
 
 @cindex multi measure rests
+@cindex full measure rests
 @cindex Rests, multi measure
+@cindex Rests, full measure
 @cindex whole rests for a full measure
 @cindex @code{R}
 
-Multi-measure rests are entered using `@code{R}'.  It is specifically
-meant for full bar rests and for entering parts: the rest can expand
-to fill a score with rests, or it can be printed as a single
+Rests for one full measure (or many bars) are entered using `@code{R}'.  It
+is specifically meant for full bar rests and for entering parts: the rest
+can expand to fill a score with rests, or it can be printed as a single
 multi-measure rest.  This expansion is controlled by the property
 @code{Score.skipBars}.  If this is set to true, empty measures will not
 be expanded, and the appropriate number is added automatically
@@ -589,6 +592,16 @@ R2.*10^\markup { \italic "ad lib." }
 R2.^\fermataMarkup
 @end lilypond
 
+Warning!  This text is created by @code{MultiMeasureRestText}, not
+@code{TextScript}.
+
+@lilypond[quote,raggedright,verbatim,fragment]
+\override TextScript #'padding = #5
+R1^"low"
+\override MultiMeasureRestText #'padding = #5
+R1^"high"
+@end lilypond
+
 If you want to have text on the left end of a multi-measure rest,
 attach the text to a zero-length skip note, i.e.,
 
@@ -706,7 +719,12 @@ c1 \mark \default
 @end lilypond
 
 @noindent
-(The letter@tie{}`I' is skipped in accordance with engraving traditions.)
+The letter@tie{}`I' is skipped in accordance with engraving traditions.
+If you wish to include the letter `I', then use
+
+@example
+\set Score.markFormatter = #format-mark-alphabet
+@end example
 
 The mark is incremented automatically if you use @code{\mark
 \default}, but you can also use an integer argument to set the mark
@@ -841,6 +859,24 @@ names, for example
 c''1
 @end lilypond
 
+If you wish to center the instrument names, you must center all of them
+
+@lilypond[quote,verbatim,raggedright]
+{ <<
+\new Staff {
+  \set Staff.instrument = \markup {
+    \center-align { "Clarinetti"
+      \line { "in B" \smaller \flat } } }
+  c''1
+}
+\new Staff {
+  \set Staff.instrument = \markup{ \center-align { Vibraphone }}
+  c''1
+}
+>>
+}
+@end lilypond
+
 For longer instrument names, it may be useful to increase the
 @code{indent} setting in the @code{\layout} block.
 
@@ -853,8 +889,10 @@ Program reference: @internalsref{InstrumentName}.
 When you put a name on a grand staff or piano staff, the width of the
 brace is not taken into account. The following property setting can be
 used to move the instrument names to the left, in such situations.
+
 @example
-\override Score.InstrumentName #'space-alist = #'((left-edge extra-space . 2.0))@end example
+\override Score.InstrumentName #'space-alist = #'((left-edge extra-space . 2.0))
+@end example
 
 
 @node Instrument transpositions
@@ -1356,7 +1394,7 @@ Cue notes have smaller font sizes.
  when the original part takes over again, this should be marked with
  the name of the original instrument.
 
- @c really?  Are you sure about that last point?  I'll check after 3.0 -gp
+@c really?  Are you sure about that last point?  I'll check after 3.0 -gp
 
 @c Yes, this is good practice.  Otherwise, the start of the original
 @c part can only be seen from the font size.  This is not good enough
@@ -1366,7 +1404,7 @@ Cue notes have smaller font sizes.
 @c -hwn
 
 
- any other changes introduced by the cued part should also be
+Any other changes introduced by the cued part should also be
 undone.  For example, if the cued instrument plays in a different clef,
 the original clef should be stated once again.
 
@@ -1778,7 +1816,7 @@ teaching tools in addition to great musical scores.
 * Balloon help::                
 * Blank music sheet::           
 * Hidden notes::                
-* Shaped note heads ::          
+* Shape note heads ::           
 * Easy Notation note heads::    
 * Analysis brackets::           
 * Coloring objects::            
@@ -1880,14 +1918,14 @@ as possible.
 @end lilypond
 
 
-@node Shaped note heads 
-@subsection Shaped note heads 
+@node Shape note heads 
+@subsection Shape note heads 
 
-In shaped note head notation, the shape of the note head corresponds
+In shape note head notation, the shape of the note head corresponds
 to the harmonic function of a note in the scale.  This notation was
 popular in the 19th century American song books.
 
-Shaped note heads can be produced by setting @code{\aikenHeads} or
+Shape note heads can be produced by setting @code{\aikenHeads} or
 @code{\sacredHarpHeads}, depending on the style desired.
 
 @lilypond[verbatim,relative=1,fragment]
@@ -1905,7 +1943,7 @@ scale is determined by  the @code{\key} command
 @findex \aikenHeads
 @findex \sacredHarpHeads
 
-Shaped note heads are implemented through the @code{shapeNoteStyles}
+Shape note heads are implemented through the @code{shapeNoteStyles}
 property.  Its value is a vector of symbols.  The k-th element indicates
 the style to use for the k-th step of the scale.  Arbitrary
 combinations are possible, eg.,
diff --git a/Documentation/user/basic-notation.itely b/Documentation/user/basic-notation.itely
index 7ab1949fe2..7d7ec8c02e 100644
--- a/Documentation/user/basic-notation.itely
+++ b/Documentation/user/basic-notation.itely
@@ -163,10 +163,11 @@ print them manually.  A reminder accidental
 can be forced by adding an exclamation mark @code{!}
 after the pitch.  A cautionary accidental
 (i.e., an accidental within parentheses) can be obtained by adding the
-question mark `@code{?}' after the pitch.
+question mark `@code{?}' after the pitch.  These extra accidentals
+can be used to produce natural signs, too.
 
 @lilypond[quote,raggedright,fragment,verbatim]
-cis' cis' cis'! cis'?
+cis' cis' cis'! cis'? c c? c! c
 @end lilypond
 
 
@@ -231,7 +232,8 @@ r1 r2 r4 r8
 @end lilypond
 
 Whole bar rests, centered in middle of the bar,
-must be done with multi-measure rests.  They are discussed in
+must be done with multi-measure rests.  They can be used for a
+single bar as well as many bars, and are discussed in
 @ref{Multi measure rests}.
 
 
@@ -1177,6 +1179,9 @@ connected between different staves of a StaffGroup
 >>
 @end lilypond
 
+
+@commonprop
+
 @cindex @code{whichBar}
 @cindex @code{repeatCommands}
 @cindex @code{defaultBarType}
@@ -1423,11 +1428,13 @@ lines.
 
 Ties are sometimes used to write out arpeggios.  In this case, two tied
 notes need not be consecutive.  This can be achieved by setting the
-@code{tieWaitForNote} property to true.  For example,
+@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,raggedright]
 \set tieWaitForNote = ##t
-\grace { c16[~ e~ g]~ } <c, e g>4   
+\grace { c16[~ e~ g]~ } <c, e g>2   
+\repeat "tremolo" 8 { c32~ c'~ } <c c,>1
 @end lilypond
 
 
diff --git a/Documentation/user/examples.itely b/Documentation/user/examples.itely
index df4ed86b4e..bb1a37749d 100644
--- a/Documentation/user/examples.itely
+++ b/Documentation/user/examples.itely
@@ -1317,78 +1317,6 @@ chant = \relative c' {
 }
 @end lilypond
 
-@subsection Bagpipe music
-
-Here is an example of bagpipe music.  It demonstrates a big strength of
-LilyPond, compared to graphical score editors: in LilyPond, you can
-very easily reuse small segments of music without writing them out
-completely.  This template defines a large number of small segments
-(@code{taor}, @code{grip}, @code{thrd}, etc), which can be reused easily.
-
-@c TODO - replace Bagpipe template with Andrew McNabb's work?
-@c  http://www.mcnabbs.org/andrew/linux/lilypond-ghb/
-
-@lilypond[quote,verbatim]
-taor = { \grace { g32[ d' g e'] } }
-grip = { \grace { g32[ b g ]    } }
-thrd = { \grace { g32[ d' c']   } }
-birl = { \grace { g32[ a g]     } }
-gstd = { \grace { g'32[ d' g]   } }
-fgg  = { \grace { f32[ g'32]    } }
-dblb = { \grace { g'32[ b d']   } }
-dblc = { \grace { g'32[ c' d']  } }
-dble = { \grace { g'32[ e' f']  } }
-dblf = { \grace { g'32[ f' g']  } }
-dblg = { \grace { g'32[ f']     } }
-dbla = { \grace { a'32[ g']     } }
-lgg  = { \grace { g32  } }
-lag  = { \grace { a32  } }
-cg   = { \grace { c'32 } }
-eg   = { \grace { e'32 } }
-gg   = { \grace { g'32 } }
-dg   = { \grace { d'32 } }
-hag  = { \grace { a'32 } }
-gefg = { \grace { g'32[ e' f']  } }
-efg  = { \grace { e'32[ f']     } }
-gdcg = { \grace { g'32[ d' c']  } }
-gcdg = { \grace { g'32[ c' d']  } }
-
-\transpose a a' {
-  #(add-grace-property 'Voice 'Stem 'length 6)
-  \time 6/8 \partial 4
-  \tieUp
-  \slurUp
-
-  f'4 |
-  \gg f'4 e'8 \thrd d'4. |
-  \eg a4.(a4) d'8 |
-  \gg d'4 f'8 \dble e'4. ( | \noBreak
-  e'8) d'4 \gg d'4 e'8 |
-
-  \break
-  \time 9/8
-  \dblf f'2.( f'4) d'8 |
-  \time 6/8
-  \dblg g'4 a'8 \gg a'4. |
-  \thrd d'4.( d'4) \eg a8 |
-  \time 9/8
-  \dble e'4 \lag e'8 \gg e'16[ d'8. e'8] \gg f'4 g'8 |
-
-  \break
-  \time 6/8
-  \gg f'4 e'8 \thrd d'4. |
-  \eg a4.( a4) d'8 |
-  \dblg g'4 a'8 \gg a'4. |
-  \thrd d'4.( d'4) f'8 |
-
-  \break
-  \dblg g'4 e'8( e'8) \dblf f'8.[ e'16] |
-  \thrd d'4.( d'4) \cg d'8 |
-  \gg c'4 e'8 \thrd d'4.( |
-  d'4.) \gdcg d'4.
-}
-@end lilypond
-
 
 @node Lilypond-book templates
 @section Lilypond-book templates
diff --git a/Documentation/user/global.itely b/Documentation/user/global.itely
index 0c94a89850..4fa1102ee3 100644
--- a/Documentation/user/global.itely
+++ b/Documentation/user/global.itely
@@ -469,6 +469,18 @@ will be much more useful than changing @code{minimumVerticalExtent}.
 @}
 @end example
 
+If you simply want to tell LilyPond ``fit as much as possible onto
+these pages, then expand to fill any available space on the pages,''
+then use the following
+
+@example
+\paper @{
+  betweensystempadding = #1
+  raggedbottom=##f
+  raggedlastbottom=##f
+@}
+@end example
+
 
 @seealso
 
@@ -759,7 +771,7 @@ piece in several movements), use @code{breakbefore} in the header.
 @cindex bibliographic information
 @cindex titles
 @cindex composer
-@cindex Music engraiving by LilyPond
+@cindex Music engraving by LilyPond
 
 A document may contain multiple pieces of music and texts.  Examples
 of these are an etude book, or an orchestral part with multiple
diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index c20b3bf9d1..12093f1472 100644
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -16,6 +16,7 @@ This chapter explains how to use notation for specific instruments.
 * Vocal music::                 
 * Rhythmic music::              
 * Guitar::                      
+* Bagpipe::                     
 * Ancient notation::            
 * Other instrument specific notation::  
 @end menu
@@ -40,8 +41,7 @@ handle this cross-staffing behavior.  In this section we discuss the
 * Cross staff stems::           
 @end menu
 
-@
-refbugs
+@refbugs
 
 Dynamics are not centered, but workarounds do exist.  See the
 ``piano centered dynamics'' template in @ref{Piano templates}.
@@ -321,6 +321,13 @@ This example also shows that the chord printing routines do not try to
 be intelligent.  The last chord (@code{f bes d}) is not interpreted as
 an inversion.
 
+Note that the duration of chords must be specified outside the
+@code{<>}.
+
+@example
+<c e g>2
+@end example
+
 
 @node Chords mode
 @subsection Chords mode
@@ -778,21 +785,17 @@ property commands
 
 Any @code{_} character that appears in an unquoted word is converted
 to a space.  This provides a mechanism for introducing spaces into words
-without using quotes.  Quoted words can also be used in Lyrics mode to
-specify words that cannot be written with the above rules.  The
-following example incorporates double quotes
+without using quotes.
 
-@example
-\lyricmode @{ He said: "\"Let" my peo ple "go\"" @}
-@end example
+To enter lyrics with characters from non-English languages, or with
+non-ascii characters (such as the heart symbol or slanted quotes),
+simply insert the characters directly into the input file and save
+it with utf-8 encoding.  See @ref{Text encoding} for more info.
 
-This example is slightly academic, since it gives better looking
-results using single quotes, @code{``} and @code{''}
 @example
-\lyricmode @{ He said: ``Let my peo ple go'' @}
+\lyricmode @{ He said: “Let my peo ple go”. @}
 @end example
 
-
 The full definition of a word start in Lyrics mode is somewhat more
 complex.
 
@@ -838,15 +841,15 @@ the @code{LyricHyphen} grob.
 
 @lilypond[quote,verbatim,raggedright]
 \score {
-<<
+ <<
   \new Staff \relative c'' {
     \time 1/4 c16 c c c c16 c c c c16 c c c
-  } % closes notes
+  }
   \lyricmode { \new Lyrics
     \with {
-    \override SeparationItem #'padding = #0.0
+      \override SeparationItem #'padding = #0.0
       % Otherwise lyrics are so far apart that hyphens don't disappear
-    } % closes with
+    } 
     {
       An -- ti -- cons -- ti --
       tu -- tion -- nel -- le --
@@ -854,17 +857,17 @@ the @code{LyricHyphen} grob.
       \override LyricHyphen  #'spacing-procedure =
         #Hyphen_spanner::set_spacing_rods
       men -- taire -- ment. ouf~!
-    } % closes lyrics
-  } %closes lyricmode
->>
-\layout   {
+    }
+  }
+ >>
+ \layout   {
   indent = 0.0 \cm
   linewidth = 3.4 \cm
   \context {
     \Staff \remove "Time_signature_engraver"
-  } % closes context
-} % closes layout
-} % closes score
+  }
+ }
+}
 @end lilypond
 
 @seealso
@@ -1033,11 +1036,13 @@ inserted by hand.
 @node Flexibility in alignment
 @subsection Flexibility in alignment
 
-
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with
 @code{\lyricsto}.
 
+@subsubsection Lyrics to multiple notes of a melisma 
+
+
 One possibility is that the text has a melisma in one stanza, but
 multiple syllables in another one.  One solution is to make the faster
 voice ignore the melisma.  This is done by setting
@@ -1085,6 +1090,11 @@ For example,
 }
 @end lilypond
 
+
+@subsection Switching the melody associated with a lyrics line
+
+
+
 More complex variations in text underlay are possible.  It is possible
 to switch the melody for a line of lyrics during the text.  This is
 done by setting the @code{associatedVoice} property.  In the example
@@ -1847,6 +1857,102 @@ pitch.  It is notated with cross noteheads; this is
 demonstrated in @ref{Special noteheads}.
 
 
+@node Bagpipe
+@section Bagpipe
+
+@cindex Bagpipe
+
+@menu
+* Bagpipe definitions::         
+* Bagpipe example::             
+@end menu
+
+
+@node Bagpipe definitions
+@subsection Bagpipe definitions
+
+LilyPond contains special definitions for music for the Scottish
+highland bagpipe; to use them, add
+
+@example
+\include "bagpipe.ly"
+@end example
+
+@noindent
+at the top of your input file.  This lets you add the special gracenotes
+common to bagpipe music with short commands.  For example, you could
+write @code{\taor} instead of
+
+@example
+\grace @{ \small G32[ d G e] @}
+@end example
+
+@code{bagpipe.ly} also contains pitch definitions for the bagpipe
+notes in the appropiate octaves, so you do not need to worry about
+@code{\relative} or @code{\transpose}.
+
+@lilypond[raggedright,verbatim,quote,notime]
+\include "bagpipe.ly"
+{ \grg G4 \grg a \grg b \grg c \grg d \grg e \grg f \grA g A }
+@end lilypond
+
+Bagpipe music nominally uses the key of D Major (even though that 
+isn't really true). However, since that is the only key that can be used, 
+the key signature is normally not written out. To set this up correctly, 
+always start your music with @code{\hideKeySignature}. If you for some 
+reason want to show the key signature, you can use @code{\showKeySignature}
+instead.
+
+Some modern music use cross fingering on c and f to flatten those notes.
+This can be indicated by @code{cflat} or @code{fflat}. Similarly, the
+piobaireachd high g can be written @code{gflat} when it occurs in light 
+music.
+
+
+@node Bagpipe example
+@subsection Bagpipe example
+
+This is what the well known tune Amazing Grace looks like in bagpipe
+notation.
+
+@lilypond[verbatim,quote]
+\include "bagpipe.ly"
+\layout {
+  indent = 0.0\cm
+  \context { \Score \remove "Bar_number_engraver" }
+}
+
+\header {
+  title = "Amazing Grace"
+  meter = "Hymn"
+  arranger = "Trad. arr."
+}
+
+{
+  \hideKeySignature
+  \time 3/4
+  \grg \partial 4 a8. d16 
+  \slurd d2 \grg f8[ e32 d16.]
+  \grg f2 \grg f8 e
+  \thrwd d2 \grg b4
+  \grG a2 \grg a8. d16
+  \slurd d2 \grg f8[ e32 d16.]
+  \grg f2 \grg e8. f16
+  \dblA A2 \grg A4
+  \grg A2 f8. A16
+  \grg A2 \hdblf f8[ e32 d16.]
+  \grg f2 \grg f8 e
+  \thrwd d2 \grg b4
+  \grG a2 \grg a8. d16
+  \slurd d2 \grg f8[ e32 d16.]
+  \grg f2 e4
+  \thrwd d2.
+  \slurd d2
+  \bar "|."
+}
+@end lilypond
+
+
 @node Ancient notation
 @section Ancient notation
 
diff --git a/Documentation/user/invoking.itely b/Documentation/user/invoking.itely
index 7e8780ffc0..19c25c36f4 100644
--- a/Documentation/user/invoking.itely
+++ b/Documentation/user/invoking.itely
@@ -270,57 +270,6 @@ Show the warranty with which GNU LilyPond comes. (It comes with
 
 @section Environment variables
 
-@ignore
-For processing both the @TeX{} and the PostScript output, the
-appropriate environment variables must be set.  The following scripts
-do this:
-
-@itemize @bullet
-@item @file{buildscripts/@/out/@/lilypond@/-profile}
-(for SH shells)
-@item @file{buildscripts/@/out/@/lilypond@/-login} (for C-shells)
-@end itemize
-
-They should normally be sourced as part of the login process.  If these
-scripts are not run from the system wide login process, then you must
-run them yourself.
-
-@cindex installing LilyPond
-
-If you use sh, bash, or a similar shell, then add the following to
-your @file{.profile}:
-@example
-. @var{/the/path/to/}lilypond-profile
-@end example
-
-If you use csh, tcsh or a similar shell, then add the following to
-your @file{~/.login}:
-@example
-source @var{/the/path/to/}lilypond-login
-@end example
-
-Of course, in both cases, you should substitute the proper location of
-either script.
-
-These scripts set the following variables:
-@table @code
-@item TEXMF
-To make sure that @TeX{} and lilypond find data files (among
-others @file{.tex}, @file{.mf}, and @file{.tfm}),
-you have to set @code{TEXMF} to point to the lilypond data
-file tree.  A typical setting would be
-@example
-@{/usr/share/lilypond/2.4.0,@{!!/usr/share/texmf@}@}
-@end example
-
-@end table
-
-@cindex PostScript
-@cindex TEXMF
-@cindex printing postscript
-
-@end ignore
-
 
 @cindex LANG
 @cindex LILYPONDPREFIX
@@ -496,7 +445,7 @@ specified.
 
 @ignore
 Copy and paste from CVS, last updated
-May 26, 2005
+Aug 18, 2005
 
 http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
 @end ignore
@@ -544,6 +493,8 @@ here for reference.
  \markup{ \center-align <{ ... }> } should be converted to:
  \markup{ \center-align {\line { ... }} }
  but now, \line is missing.
+2.4->2.6
+ Special LaTeX characters such as $~$ in text are not converted to UTF8.
 
 @end verbatim
 
@@ -687,6 +638,9 @@ This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is
 defined in the init file @file{scm/@/lily@/.scm}.
 
+The @code{\score} must begin with music, and may contain only
+one music block.
+
 @item
 A @code{\book} block logically combines multiple movements
 (i.e., multiple @code{\score} blocks) in one document.  A number of
@@ -774,7 +728,32 @@ file, use
 \include "otherfile.ly"
 @end example
 
-For example, you may write separate files for each instrument part and
-create a ``full score'' file which brings together the individual
-instrument files.
+The line @code{\include "file.ly"} is equivalent to pasting the contents
+of file.ly into the current file at the place where you have the
+\include.  For example, for a large project you might write separate files
+for each instrument part and create a ``full score'' file which brings
+together the individual instrument files.
+
+The initialization of LilyPond is done in a number of files that are
+included by default when you start the program, normally transparent to the
+user.  Run lilypond --verbose to see a list of paths and files that Lily
+finds.
+
+Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
+VERSION is in the form ``2.6.1'') are on the path and available to
+@code{\include}.  Files in the
+current working directory are available to \include, but a file of the same
+name in LilyPond's installation takes precedence.  Files are
+available to \include from directories in the search path specified as an
+option when invoking @code{lilypond --include=DIR} which adds DIR to the search
+path.
+
+The @code{\include} statement can use full path information, but with the Unix
+convention @code{"/"} rather than the DOS/Windows @code{"\"}.  For example,
+if @file{stuff.ly} is located one directory higher than the current working
+directory, use
+
+@example
+\include "../stuff.ly"
+@end example
 
diff --git a/Documentation/user/lilypond-book.itely b/Documentation/user/lilypond-book.itely
index 6f5b91c9b2..fe4f30d468 100644
--- a/Documentation/user/lilypond-book.itely
+++ b/Documentation/user/lilypond-book.itely
@@ -469,7 +469,8 @@ guess a default for @code{lilypond} environments which don't use the
 @code{raggedright} option.
 
 @item notime
-Do not print the time signature.
+Do not print the time signature, and turns off the timing (key signature,
+bar lines) in the score.
 
 @item fragment
 Make @command{lilypond-book} add some boilerplate code so that you can
diff --git a/Documentation/user/lilypond.tely b/Documentation/user/lilypond.tely
index 88a92c9d0e..9c82158440 100644
--- a/Documentation/user/lilypond.tely
+++ b/Documentation/user/lilypond.tely
@@ -10,7 +10,7 @@
 
 @ignore
 (I think)
-Current version of the manual: 2.5.18
+Current version of the manual: 2.6.0
 Please update this whenever you run convert-ly on the docs.
 
 convert-ly --from=... --to=... --no-version *.itely
diff --git a/Documentation/user/music-glossary.tely b/Documentation/user/music-glossary.tely
index ce6c7f763d..8b35aa9fa8 100644
--- a/Documentation/user/music-glossary.tely
+++ b/Documentation/user/music-glossary.tely
@@ -371,6 +371,7 @@ Languages in this order.
 * tempo indication::            
 * tenor::                       
 * tenth::                       
+* tenuto::                      
 * third::                       
 * thirty-second note::          
 * thirty-second rest::          
@@ -1443,7 +1444,7 @@ of the 20th century
 \score {
   {
 %   \override Staff.Custos #'neutral-position = #4
-    \override Staff.Custos #'neutral-direction = #-1
+    \override Staff.Custos #'neutral-direction = #down
     \override Staff.Custos #'style = #'hufnagel
     c'1 \break
     <d' a' f''>1
@@ -4534,6 +4535,21 @@ FI: desimi.
 
 @aref{note value}.
 
+@node tenuto
+@section tenuto
+
+ES: tenuto,
+I: tenuto,
+F: tenue, tenuto,
+D: gehalten, tenuo,
+NL: tenuto,
+DK: tenuto,
+S: tenuto,
+FI: viiva, tenuto.
+
+An indication that a particular note should be held for the whole
+length, although this can vary depending on the composer and era.
+
 @node third
 @section third
 
diff --git a/Documentation/user/programming-interface.itely b/Documentation/user/programming-interface.itely
index b536c9ae06..29455293e7 100644
--- a/Documentation/user/programming-interface.itely
+++ b/Documentation/user/programming-interface.itely
@@ -467,10 +467,9 @@ is this table:
 @quotation
 @multitable @columnfractions .3 .3
 @item @b{LilyPond} @tab @b{Scheme}
-@item @b{LilyPond} @tab @b{Scheme}
-@item @code{\markup @{ ... @}} @tab @code{( markup ... )}
+@item @code{\markup markup1 @}} @tab @code{(markup markup1)}
 @item @code{\markup @{ markup1 markup2 ... @}} @tab 
-        @code{(markup #:line ( markup1 markup2 ... ))}
+        @code{(markup markup1 markup2 ... )}
 @item @code{\command} @tab @code{#:command}
 @item @code{\variable} @tab @code{variable}
 @item @code{\center-align @{ ... @}} @tab @code{#:center-align ( ... )}
@@ -614,15 +613,15 @@ defined @code{\smallcaps} command:
   "Print the character name in small caps, translated to the left and
   top.  Syntax: \\character #\"name\""
   (interpret-markup layout props 
-   (markup "" #:translate (cons -3 1) #:smallcaps name)))
+   (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
 @end example
 
 There is one complication that needs explanation: texts above and below
 the staff are moved vertically to be at a certain distance (the
 @code{padding} property) from the staff and the notes.  To make sure
 that this mechanism does not annihilate the vertical effect of our
-@code{#:translate}, we add an empty string (@code{""}) before the
-translated text.  Now the @code{""} will be put above the notes, and the
+@code{#:translate}, we add an empty string (@code{#:hspace 0}) before the
+translated text.  Now the @code{#:hspace 0} will be put above the notes, and the
 @code{name} is moved in relation to that empty string.  The net effect is
 that the text is moved to the upper left.
 
@@ -651,7 +650,7 @@ The final result is as follows:
   "Print the character name in small caps, translated to the left and
   top.  Syntax: \\character #\"name\""
   (interpret-markup layout props 
-   (markup "" #:translate (cons -3 1) #:smallcaps name)))
+   (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
 
 {
   c''^\markup \character #"Cleopatra" c'' c'' c''
diff --git a/Documentation/user/putting.itely b/Documentation/user/putting.itely
index 4b9682f371..bfdc88e558 100644
--- a/Documentation/user/putting.itely
+++ b/Documentation/user/putting.itely
@@ -272,8 +272,10 @@ e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 
 That looks better, but it isn't quite big enough.  After experimenting
-with a few values, I think 2.3 is the best number.  I leave this as an
-exercise for the reader.
+with a few values, we think 2.3 is the best number in this case.  However,
+this number is merely the result of experimentation and my personal
+taste in notation.  Try the above example with 2.3... but also try higher
+(and lower) numbers.  Which do you think looks the best?
 
 @cindex extra-offset
 
@@ -291,7 +293,7 @@ e4^\markup{ \italic ritenuto } g b e
 
 With @code{extra-offset}, the first number controls the horizontal
 movement (left is negative); the second number controls the vertial
-movement (up is positive).  After a bit of experimenting, I decided
+movement (up is positive).  After a bit of experimenting, we decided
 that these values look good
 
 @lilypond[quote,fragment,raggedright,verbatim,relative=2]
@@ -299,6 +301,11 @@ that these values look good
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 
+@noindent
+Again, these numbers are simply the result of a few experiments and
+looking at the output.  You might prefer the text to be slightly higher,
+or to the left, or whatever.  Try it and look at the result!
+
 
 @seealso