X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ffundamental.itely;h=ae7b467c252a861736933112b024366d80629244;hb=32c862967d559ab512cd96e3321a2c8dabe724ca;hp=811b1dc49360beb33ead9c29f56053401676828c;hpb=e1a149d0cc60b02e86209387958f4028567dd366;p=lilypond.git

diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 811b1dc493..ae7b467c25 100644
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.14.0"
 
 @node Fundamental concepts
 @chapter Fundamental concepts
@@ -191,7 +191,7 @@ You may code multiple @code{\score} blocks.  Each will be
 treated as a separate score, but they will be all combined into
 a single output file.  A @code{\book} command is not necessary
 -- one will be implicitly created.  However, if you would like
-separate output files from one @code{.ly} file then the
+separate output files from one @file{.ly} file then the
 @code{\book} command should be used to separate the different
 sections: each @code{\book} block will produce a
 separate output file.
@@ -520,8 +520,8 @@ So, for example, a phrasing slur can start before a manually
 inserted beam and end before the end of the beam -- not very
 musical, perhaps, but possible:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
- { g8\( a b[ c b\) a] g4 }
+@lilypond[quote,verbatim,ragged-right,relative=2]
+g8\( a b[ c b\) a] g4
 @end lilypond
 
 In general, different kinds of brackets, bracket-like constructs,
@@ -531,13 +531,11 @@ a slur extending into a tuplet (line 2), a beam and a slur
 extending into a tuplet, a tie crossing two tuplets, and a
 phrasing slur extending out of a tuplet (lines 3 and 4).
 
-@lilypond[quote,verbatim,fragment,ragged-right]
-{
-  r16[ g \times 2/3 { r16 e'8] }
-  g16( a \times 2/3 { b16 d) e' }
-  g8[( a \times 2/3 { b8 d') e'~] } |
-  \times 4/5 { e'32\( a b d' e' } a'4.\)
-}
+@lilypond[quote,verbatim,ragged-right,relative=1]
+r16[ g \times 2/3 { r16 e'8] }
+g,16( a \times 2/3 { b16 d) e }
+g,8[( a \times 2/3 { b8 d) e~] } |
+\times 4/5 { e32\( a, b d e } a4.\)
 @end lilypond
 
 
@@ -589,7 +587,7 @@ A single voice can contain many notes in a chord, of course,
 so when exactly are multiple voices needed?  Look first at
 this example of four chords:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
+@lilypond[quote,verbatim,ragged-right,relative=1]
 \key g \major
 <d g>4 <d fis> <d a'> <d g>
 @end lilypond
@@ -624,7 +622,7 @@ of polyphony.
 Here's how we split the chords above into two voices and add both
 the passing note and a slur:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+@lilypond[quote,verbatim,ragged-right,relative=2]
 \key g \major
 %    Voice "1"               Voice "2"
 << { g4 fis8( g) a4 g } \\ { d4 d d d }  >>
@@ -634,7 +632,7 @@ Notice how the stems of the second voice now point down.
 
 Here's another simple example:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+@lilypond[quote,verbatim,ragged-right,relative=2]
 \key d \minor
 %    Voice "1"             Voice "2"
 << { r4 g g4. a8 }    \\ { d,2 d4 g }       >> |
@@ -648,7 +646,7 @@ can help the legibility of the code, but if there are many
 notes in each bar it may be better to split out each voice
 separately, like this:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+@lilypond[quote,verbatim,ragged-right,relative=2]
 \key d \minor
 << {
   % Voice "1"
@@ -677,7 +675,7 @@ The Voice contexts bear the names @code{"1"}, @code{"2"}, etc.
 In each of these contexts, the vertical direction of slurs,
 stems, ties, dynamics etc., is set appropriately.
 
-@lilypond[quote,verbatim,fragment]
+@lilypond[quote,verbatim]
 \new Staff \relative c' {
   % Main voice
   c16 d e f
@@ -869,7 +867,7 @@ shall see, this encounters some difficulties.  We begin as
 we have learnt, using the @code{<< \\  >>} construct to
 enter the music of the first bar in three voices:
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 \new Staff \relative c'' {
   \key aes \major
   <<
@@ -892,7 +890,7 @@ of music.  We can correct this by skipping voice three
 and placing the music in voice four.  This is done by simply
 adding another pair of @code{\\}.
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 \new Staff \relative c'' {
   \key aes \major
   <<  % Voice one
@@ -919,8 +917,8 @@ usually works well, but in this example the notes of the lowest voice
 are clearly not well placed by default.  LilyPond provides several ways
 to adjust the horizontal placing of notes.  We are not quite ready yet
 to see how to correct this, so we shall leave this problem until a
-later section --- see the @code{force-hshift} property in @ref{Fixing
-overlapping notation}.
+later section --- see the @code{force-hshift} property in
+@ref{Fixing overlapping notation}.
 
 
 @seealso
@@ -945,7 +943,7 @@ Notation Reference: @ruser{Multiple voices}.
 
 Voice contexts can also be created manually
 inside a @code{<< >>} block to create polyphonic music, using
-@code{\voiceOne} ... @code{\voiceFour} to indicate the required
+@code{\voiceOne} @dots{} @code{\voiceFour} to indicate the required
 directions of stems, slurs, etc.  In longer scores this method
 is clearer, as it permits the voices to be separated and to be
 given more descriptive names.
@@ -1192,7 +1190,7 @@ explicitly link
 the lyrics to the notes with @code{\lyricsto@{@}}, using the
 name assigned to the Voice.
 
-@lilypond[quote,verbatim,fragment]
+@lilypond[quote,verbatim]
 <<
   \new Voice = "one" {
     \relative c'' {
@@ -1366,7 +1364,7 @@ appear explicitly in the input file must be added to the
 output.  For example, compare the input and output of the
 following example:
 
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
 cis4 cis2. | a4 a2. |
 @end lilypond
 
@@ -1460,16 +1458,11 @@ where @var{type} is a context name (like @code{Staff} or
 @code{Voice}).  This command creates a new context, and starts
 interpreting the @var{music-expression} within that context.
 
-(Note that a @code{\new Score} command is not normally required,
-as the essential top-level @code{Score} context is created
-automatically when the music expression within the @code{\score}
-block is interpreted.  The only reason for creating a @code{Score}
-context explicitly using @code{\new Score} is to introduce a
-@code{\with} block in which one or more score-wide default values
-of context properties may be specified.  Information on using
-@code{\with} blocks can be found under the heading
-@qq{Setting context properties with @code{\\with} } in
-@ref{Modifying context properties}.)
+@warning{@bs{}@code{new Score} should not be used as the essential
+top-level @code{Score} context is created automatically when the music
+expression within the @bs{}@code{score} block is interpreted.  Score-wide
+default values of context properties can be changed within the
+@bs{}@code{layout} block.  See @ref{Modifying context properties}}
 
 You have seen many practical examples which created new
 @code{Staff} and @code{Voice} contexts in earlier sections, but
@@ -1812,7 +1805,7 @@ font size, which affects the size of the note heads (among
 other things) several times.  The change is from the default
 value, not the most recently set value.
 
-@lilypond[quote,verbatim,ragged-right,relative=1,fragment]
+@lilypond[quote,verbatim,ragged-right,relative=1]
 c4 d
 % make note heads smaller
 \set fontSize = #-4
@@ -1870,27 +1863,6 @@ like this:
 >>
 @end lilypond
 
-Or, if the property override is to be applied to all staves
-within the score, it may be appended to an explicit
-@code{\new Score} command, like this:
-
-@lilypond[quote,verbatim,ragged-right]
-\score {
-  \new Score \with { extraNatural = ##f } <<
-    \new Staff {
-      \relative c'' {
-        gis4 ges aes ais
-      }
-    }
-    \new Staff {
-      \relative c'' {
-        gis4 ges aes ais
-      }
-    }
-  >>
-}
-@end lilypond
-
 Properties set in this way may still be changed dynamically using
 @code{\set} and returned to the default value set in the
 @code{\with} block with @code{\unset}.
@@ -1935,6 +1907,31 @@ throughout the @code{\score} or @code{\book} block in which the
 }
 @end lilypond
 
+If the property override is to be applied to all staves
+within the score:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \relative c'' {
+        gis4 ges aes ais
+      }
+    }
+    \new Staff {
+      \relative c'' {
+        gis4 ges aes ais
+      }
+    }
+  >>
+  \layout {
+    \context {
+      \Score extraNatural = ##f
+    }
+  }
+}
+@end lilypond
+
 @noindent
 Context properties set in this way may be overridden for particular
 instances of contexts by statements in a @code{\with} block, and by
@@ -2108,11 +2105,16 @@ for all contexts of a particular type by including the
 @code{\set} command in a @code{\context} block in the
 same way.
 
-
 @seealso
 Notation Reference: @ruser{Modifying context plug-ins},
 @ruser{Changing context default settings}.
 
+@knownissues
+The @code{Stem_engraver} and @code{Beam_engraver} attach their
+objects to note heads.  If the @code{Note_heads_engraver} is removed
+no note heads are produced and therefore no stems or beams are created
+either.
+
 
 @node Extending the templates
 @section Extending the templates
@@ -2429,8 +2431,8 @@ lower = \relative c, {
 @end lilypond
 
 None of the templates provides this layout exactly.  The nearest is
-@q{SATB vocal score and automatic piano reduction} -- see @ref{Vocal
-ensembles} -- but we need to change the layout and add a piano
+@q{SATB vocal score and automatic piano reduction} -- see
+@ref{Vocal ensembles} -- but we need to change the layout and add a piano
 accompaniment which is not derived automatically from the vocal parts.
 The variables holding the music and words for the vocal parts are
 fine, but we shall need to add variables for the piano reduction.
@@ -2838,19 +2840,19 @@ the pedal staff should behave similarly.
 @cindex grobs
 
 Stretchability of staves can be controlled with the
-@code{next-staff-spacing} property of the @code{VerticalAxisGroup}
-@q{graphical object} (commonly called @q{grob}s within the lilypond
-documentation) -- don't worry about the details right now; this is
-fully explained later.  For the curious, have a look at
-@ruser{Overview of modifying properties}.  Currently, it is not
-possible to modify the @code{stretchability} sub-property only, we
-thus have to copy the other sub-properties also.  Again, for the
-curious, you can find the default values in file
-@file{scm/@/define-grobs@/.scm} by looking up the definition of the
-@code{VerticalAxisGroup} grob.  The value for @code{stretchability}
-is taken from the definition of the @code{PianoStaff} context (in
-file @file{ly/@/engraver-init@/.ly}) so that the values are
-identical.
+@code{staff-staff-spacing} property of the
+@code{VerticalAxisGroup} @q{graphical object} (commonly called
+@q{grob}s within the lilypond documentation) -- don't worry about
+the details right now; this is fully explained later.  For the
+curious, have a look at @ruser{Overview of modifying properties}.
+In this case, we want to modify the @code{stretchability}
+sub-property only. Again, for the curious, you can find the
+default values for the staff-staff-spacing property
+in file @file{scm/define-grobs.scm} by looking up the definition
+of the @code{VerticalAxisGroup} grob.  The value for
+@code{stretchability} is taken from the definition of the
+@code{PianoStaff} context (in file @file{ly/engraver-init.ly})
+so that the values are identical.
 
 @example
 \score @{
@@ -2870,10 +2872,7 @@ identical.
       >>  % end ManualOne Staff context
       \new Staff = "ManualTwo" \with @{
         \override VerticalAxisGroup
-          #'next-staff-spacing = #'((space . 9)
-                                    (minimum-distance . 8)
-                                    (padding . 1)
-                                    (stretchability . 5))
+          #'staff-staff-spacing  #'stretchability = 5
       @} <<
         \keyTime
         \clef "bass"
@@ -2937,10 +2936,7 @@ PedalOrganMusic = \relative c {
       >>  % end ManualOne Staff context
       \new Staff = "ManualTwo" \with {
         \override VerticalAxisGroup
-          #'next-staff-spacing = #'((space . 9)
-                                    (minimum-distance . 8)
-                                    (padding . 1)
-                                    (stretchability . 5))
+          #'staff-staff-spacing #'stretchability = 5
       } <<
         \keyTime
         \clef "bass"
@@ -2960,6 +2956,9 @@ PedalOrganMusic = \relative c {
 }  % end Score context
 @end lilypond
 
+@seealso
+Music Glossary:
+@rglos{system}.
 
 @node Saving typing with variables and functions
 @subsection Saving typing with variables and functions
@@ -3082,7 +3081,7 @@ LilyPond input syntax changes (see
 you have a single definition (such as @code{\dolce}) for all your
 input files (see @ref{Style sheets}), then if the syntax changes, you
 only need to update your single @code{\dolce} definition,
-instead of making changes throughout every @code{.ly} file.
+instead of making changes throughout every @file{.ly} file.
 
 
 @node Scores and parts