X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=f3ba95a48a7bfbd9744f30295060dede185f082e;hb=315e509f940a8e14ea264f14e119ae7e6dd9f55b;hp=f18d137c792bf9444d17c3f4819423618ca13fdb;hpb=731ea9c09be8beaa160a47a8691ddf111bb9f211;p=lilypond.git

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index f18d137c79..f3ba95a48a 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.61"
+@c \version "2.11.65"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -63,8 +63,8 @@ This section describes what contexts are, and how to modify them.
 * Aligning contexts::
 @end menu
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.
 
@@ -77,7 +77,7 @@ Snippets:
 
 Internals Reference:
 @rinternals{Contexts},
-@rinternals{Engravers and performers}.
+@rinternals{Engravers and Performers}.
 
 
 @node Contexts explained
@@ -108,7 +108,7 @@ further explanation and with links to the IR.
 
 @c TODO Describe propagation of property values -td
 
-Contexts are arranged heirarchically:
+Contexts are arranged hierarchically:
 
 @menu
 * Score - the master of all contexts::
@@ -138,67 +138,55 @@ executed.
 
 Groups staves while adding a bracket on the left side, grouping
 the staves together. The bar lines of the contained staves are
-connected vertically. StaffGroup only consists of a collection
+connected vertically.  @code{StaffGroup} only consists of a collection
 of staves, with a bracket in front and spanning bar lines.
 
 @strong{@emph{ChoirStaff}}
 
-Identical to StaffGroup except that the bar lines of the contained
-staves are not connected vertically.
+Identical to @code{StaffGroup} except that the bar lines of the
+contained staves are not connected vertically.
 
 @strong{@emph{GrandStaff}}
 
-A group of staves, with a brace on the left side, grouping
-the staves together. The bar lines of the contained staves are
+A group of staves, with a brace on the left side, grouping the
+staves together.  The bar lines of the contained staves are
 connected vertically.
 
 @strong{@emph{PianoStaff}}
 
-@c TODO No longer correct?  Check.  -td
-Just like GrandStaff but with a forced distance between the
-staves, so cross staff beaming and slurring can be used.
-
-@ignore
-@strong{@emph{InnerStaffGroup}}
-
-TODO  -td
-
-@strong{@emph{InnerChoirStaff}}
-
-TODO  -td
-
-@end ignore
+Just like @code{GrandStaff}, but with support for instrument names
+to the left of each system.
 
 @node Intermediate-level contexts - staves
 @unnumberedsubsubsec Intermediate-level contexts - staves
 
 @strong{@emph{Staff}}
 
-Handles clefs, bar lines, keys, accidentals. It can contain
-Voice contexts.
+Handles clefs, bar lines, keys, accidentals.  It can contain
+@code{Voice} contexts.
 
 @strong{@emph{RhythmicStaff}}
 
-Like Staff but for printing rhythms. Pitches are ignored;
+Like @code{Staff} but for printing rhythms.  Pitches are ignored;
 the notes are printed on one line.
 
 @strong{@emph{TabStaff}}
 
-Context for generating tablature. By default lays the music
+Context for generating tablature.  By default lays the music
 expression out as a guitar tablature, printed on six lines.
 
 @strong{@emph{DrumStaff}}
 
-Handles typesetting for percussion. Can contain DrumVoice
+Handles typesetting for percussion.  Can contain @code{DrumVoice}
 
 @strong{@emph{VaticanaStaff}}
 
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
 a piece in gregorian style.
 
 @strong{@emph{MensuralStaff}}
 
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
 a piece in mensural style.
 
 @node Bottom-level contexts - voices
@@ -210,24 +198,24 @@ contain other contexts.
 
 @strong{@emph{Voice}}
 
-Corresponds to a voice on a staff. This context handles the
+Corresponds to a voice on a staff.  This context handles the
 conversion of dynamic signs, stems, beams, super- and sub-scripts,
 slurs, ties, and rests.  You have to instantiate this explicitly
 if you require multiple voices on the same staff.
 
 @strong{@emph{VaticanaVoice}}
 
-Same as Voice, except that it is designed for typesetting a piece
-in gregorian style.
+Same as @code{Voice}, except that it is designed for typesetting
+a piece in gregorian style.
 
 @strong{@emph{MensuralVoice}}
 
-Same as Voice, with modifications for typesetting a piece in
+Same as @code{Voice}, with modifications for typesetting a piece in
 mensural style.
 
 @strong{@emph{Lyrics}}
 
-Corresponds to a voice with lyrics. Handles the printing of a
+Corresponds to a voice with lyrics.  Handles the printing of a
 single line of lyrics.
 
 @strong{@emph{DrumVoice}}
@@ -236,13 +224,13 @@ The voice context used in a percussion staff.
 
 @strong{@emph{FiguredBass}}
 
-The context in which BassFigure objects are created from
+The context in which @code{BassFigure} objects are created from
 input entered in @code{\figuremode} mode.
 
 @strong{@emph{TabVoice}}
 
-The voice context used within a TabStaff context.  Usually left to
-be created implicitly.
+The voice context used within a @code{TabStaff} context.  Usually
+left to be created implicitly.
 
 @strong{@emph{ChordNames}}
 
@@ -540,51 +528,38 @@ with ordering dependencies.
 @node Changing context default settings
 @subsection Changing context default settings
 
-The adjustments of the previous subsections (
-@ref{The set command}, @ref{Modifying context plug-ins}, and
-@ref{Overview of modifying properties}) can also be entered
-separately from the music in the @code{\layout} block,
-
-@example
-\layout @{
-  @dots{}
-  \context @{
-    \Staff
-
-    \set fontSize = #-2
-    \override Stem #'thickness = #4.0
-    \remove "Time_signature_engraver"
-  @}
-@}
-@end example
-
-The @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
+The context settings which are to be used by default in
+@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
+in a @code{\layout} block, as illustrated in the following example.
+The @code{\layout} block should be placed within the @code{\score}
+block to which it is to apply, but outside any music.
 
-The statements
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-affect all staves in the score.  Other contexts can be modified
-analogously.
-
-The @code{\set} keyword is optional within the @code{\layout} block, so
-
-@example
-\context @{
-  @dots{}
-  fontSize = #-2
-@}
-@end example
+Note that the @code{\set} command itself and the context must be
+omitted when the context default values are specified in this way:
 
-@noindent
-will also work.
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    a4^"Really small, thicker stems, no time signature" a a a
+    a a a a
+  }
+  \layout {
+    \context {
+      \Staff
+      fontSize = #-4
+      \override Stem #'thickness = #4.0
+      \remove "Time_signature_engraver"
+    }
+  }
+}
+@end lilypond
 
+In this example, the @code{\Staff} command specifies that the
+subsequent specifications are to be applied to all staves within
+this score block.
 
+Modifications can be made to the @code{Score} context or all
+@code{Voice} contexts in a similar way.
 
 @knownissues
 
@@ -782,8 +757,8 @@ in ossia,
 @c TODO Better example needed.  Ref LM, and expand on it.
 
 @cindex ossia
-@findex alignAboveContext
-@findex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
 
 @lilypond[quote,ragged-right]
 ossia = { f4 f f f }
@@ -798,16 +773,63 @@ ossia = { f4 f f f }
 }
 @end lilypond
 
+@cindex nested contexts
+@cindex contexts, nested
+
+@funindex \accepts
+@funindex \denies
+
+Contexts like @code{PianoStaff} can contain other contexts
+nested within them.  Contexts which are acceptable for nesting
+are defined by the @qq{accepts} list of a context.  Contexts
+which are not in this list are placed below the outer context
+in the printed score.
+For example, the @code{PianoStaff} context is defined by default
+to accept @code{Staff} and @code{FiguredBass} contexts within
+it, but not (for example) a @code{Lyrics} context.  So in the
+following structure the lyrics are placed below the piano staff
+rather than between the two staves:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff
+<<
+  \new Staff { e4 d c2 }
+  \addlyrics { Three blind mice }
+  \new Staff {
+    \clef "bass"
+    { c,1 }
+  }
+>>
+@end lilypond
+
+The @qq{accepts} list of a context can be modified to include
+additional nested contexts, so if we wanted the lyrics to appear
+between the two staves we could use:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff \with { \accepts Lyrics }
+<<
+  \new Staff { e4 d c2 }
+  \addlyrics { Three blind mice }
+  \new Staff {
+    \clef "bass"
+    { c,1 }
+  }
+>>
+@end lilypond
+
+The opposite of @code{\accepts} is @code{\denies}; this removes a
+context from the @qq{accepts} list.
 
 @node Explaining the Internals Reference
 @section Explaining the Internals Reference
 
 
 @menu
-* Navigating the program reference::  
-* Layout interfaces::           
-* Determining the grob property::  
-* Naming conventions::          
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
 @end menu
 
 @node Navigating the program reference
@@ -1233,12 +1255,11 @@ properties.  To tweak those, use commands of the form
 such as
 
 @example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
 
 @seealso
-
 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
 @rinternals{PropertySet}, @rinternals{Backend}, and
 @rinternals{All layout objects}.
@@ -1400,7 +1421,7 @@ Some tweakable options are called @q{subproperties} and reside inside
 properties.  To tweak those, use commands in the form
 
 @example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
 @cindex internal documentation
@@ -1535,14 +1556,15 @@ including any automatically inserted elements, may be examined,
 see @ref{Displaying music expressions}.  This may be helpful in
 determining what may be modified by a @code{\tweak} command.
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 
 Notation Reference:
 @ref{Displaying music expressions}.
 
+
 @knownissues
 
 @cindex tweaks in a variable
@@ -1617,6 +1639,7 @@ property (modified with @code{\set}) was created.
 * Input modes::
 * Direction and placement::
 * Distances and measurements::
+* Staff symbol properties::
 * Spanners::
 * Visibility of objects::
 * Line styles::
@@ -1746,17 +1769,18 @@ up or down based on the stem direction (like slurs or accents).
 
 @c TODO Add table showing these
 
-@strong{Context layout}
-
-Contexts are positioned in a system from top to bottom in the
-order in which they are encountered.  Note, however, that a
-context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.
+@strong{Context layout order}
 
-@c TODO Add example ?
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered.  Note, however, that
+a context will be created implicitly if a command is encountered
+when there is no suitable context available to contain it.  When
+contexts are nested, the outer context will exclude inner contexts
+which are not included in its @qq{accepts} list; excluded contexts
+will be repositioned below the outer context.
 
-The default order in which contexts are laid out can be changed,
-see @ref{Aligning contexts}
+The default order in which contexts are laid out and the
+@qq{accepts} list can be changed, see @ref{Aligning contexts}.
 
 @strong{Articulation direction indicators}
 
@@ -1862,8 +1886,8 @@ convert from a font size change to the equivalent change in
 @code{staff-space}.  For an explanation and an example of its use,
 see @rlearning{Length and thickness of objects}.
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Length and thickness of objects}.
 
@@ -1872,6 +1896,46 @@ Notation Reference:
 @ref{Setting the staff size}.
 
 
+@node Staff symbol properties
+@subsection Staff symbol properties
+
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+
+@c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
+@c      Need to think of uses for these properties.  Eg 'line-positions
+@c      is used in a snippet to thicken centre line.
+@c      If retained, add @ref to here in 1.6.2  -td
+
+The vertical position of staff lines and the number of staff lines
+can be defined at the same time.  As the following example shows,
+note positions are not influenced by the staff line positions.
+
+@warning{The @code{'line-positions} property overrides the
+@code{'line-count} property.  The number of staff lines is
+implicitly defined by the number of elements in the list of values
+for @code{'line-positions}.}
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+The width of a staff can be modified.  The units are staff
+spaces.  The spacing of objects inside the staff is not affected by
+this setting.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+
 @node Spanners
 @subsection Spanners
 
@@ -2038,8 +2102,8 @@ the @code{\override} command is quite simple:
 
 @lilypond[relative=2,quote,verbatim]
 e2 \glissando b
-\once \override Glissando #'bound-details #'left #'Y = #3
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details left Y) = #3
+\once \override Glissando #'(bound-details right Y) = #-2
 e2 \glissando b
 @end lilypond
 
@@ -2058,7 +2122,7 @@ sub-lists of @code{bound-details}.  For example:
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 \override Glissando #'breakable = ##t
-\override Glissando #'bound-details #'right-broken #'Y = #-3
+\override Glissando #'(bound-details right-broken Y) = #-3
 c1 \glissando \break
 f1
 @end lilypond
@@ -2098,7 +2162,7 @@ This is a markup that is evaluated to yield the stencil.  It is used
 to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
+\override TextSpanner #'(bound-details left text)
    = \markup { \small \bold Slower }
 c2\startTextSpan b c a\stopTextSpan
 @end lilypond
@@ -2112,15 +2176,15 @@ or @code{stencil-offset} will move the symbol at the edge vertically
 relative to the end point of the line:
 
 @lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details
-  #'left #'stencil-align-dir-y = #-2
-\override TextSpanner #'bound-details
-  #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details
-  #'left #'text = #"ggg"
-\override TextSpanner #'bound-details
-  #'right #'text = #"hhh"
+\override TextSpanner
+  #'(bound-details left stencil-align-dir-y) = #-2
+\override TextSpanner
+  #'(bound-details right stencil-align-dir-y) = #UP
+
+\override TextSpanner
+  #'(bound-details left text) = #"ggg"
+\override TextSpanner
+  #'(bound-details right text) = #"hhh"
 c4^\startTextSpan c c c \stopTextSpan
 @end lilypond
 
@@ -2159,9 +2223,7 @@ When using @code{\endSpanners} it is not necessary to close
 hairpins with @code{\!}.
 
 
-
 @seealso
-
 Internals Reference: @rinternals{TextSpanner},
 @rinternals{Glissando}, @rinternals{VoiceFollower},
 @rinternals{TrillSpanner},
@@ -2188,11 +2250,11 @@ certain layout objects.  These are covered under Special
 considerations.
 
 @menu
-* Removing the stencil::        
-* Making objects transparent::  
-* Painting objects white::      
-* Using break-visibility::      
-* Special considerations::      
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
 @end menu
 
 
@@ -2310,29 +2372,25 @@ object is printed at the end of, within the body of, or at the
 beginning of a line.  Or to be more precise, before a line break,
 where there is no line break, or after a line break.
 
-Alternatively, seven of the eight combinations may be specified
+Alternatively, these eight combinations may be specified
 by pre-defined functions, defined in @file{scm/output-lib.scm},
 where the last three columns indicate whether the layout objects
 will be visible in the positions shown at the head of the columns:
 
-@multitable @columnfractions .40 .15 .1 .1 .1
-@c TODO check these more carefully
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 
-@item @code{all-invisible}           @tab @code{'#(#f #f #f)} @ @ @tab no     @tab no       @tab no
+@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
 @item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
+@item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
 @item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab yes    @tab no       @tab no
-@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
-@c The center-visible function is not defined
-@c @item @code{center-visible}       @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
 @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
-@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
 @item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab yes    @tab no       @tab yes
+@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
+@item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab no     @tab no       @tab no
 @end multitable
 
-The @code{center-visible} function is not pre-defined.
-
 The default settings of @code{break-visibility} depend on the
 layout object.  The following table shows all the layout objects
 of interest which are affected by @code{break-visibility} and the
@@ -2548,7 +2606,7 @@ override these:
 @c FIXME Complete
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details right Y) = #-2
 e2 \glissando f
 @end lilypond
 
@@ -2637,8 +2695,8 @@ appearance of the printed score.
 * Modifying shapes::
 @end menu
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Tweaking output},
 @rlearning{Other sources of information}.
@@ -2657,6 +2715,7 @@ Snippets:
 Internals Reference:
 @rinternals{All layout objects}.
 
+
 @node Aligning objects
 @subsection Aligning objects
 
@@ -3003,8 +3062,8 @@ Any of the glyphs in the feta Font can be supplied to the
 
 @c TODO Add inserting Postscript or ref to later
 
-@seealso
 
+@seealso
 Notation Reference:
 @ref{Graphic notation inside markup},
 @ref{Formatting text},