X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=0ba8be5d8377497587899420e86b2a402b3c308d;hb=f49e954f4a1c1c388ebe8c0581a20da0238aed25;hp=301f34374dfd7c3f02b2374032648260748d3a3b;hpb=78eb8695d44a5a5775457a14770093299b6d5fa6;p=lilypond.git

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 301f34374d..0ba8be5d83 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -7,11 +7,12 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.55"
 
 @node Changing defaults
 @chapter Changing defaults
 
+@strong{N.B. This Chapter is under heavy development at present.}
 
 The purpose of LilyPond's design is to provide the finest output
 quality as a default.  Nevertheless, it may happen that you need to
@@ -39,6 +40,8 @@ LilyPond.  It is written as a HTML document, which is available
 @uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
 but is also included with the LilyPond documentation package.
 
+@c TODO The following is at variance to what actually follows.  Fix -td
+
 There are four areas where the default settings may be changed:
 
 @itemize
@@ -70,13 +73,13 @@ on entering numbers, lists, strings, and symbols in Scheme.}
 
 
 @menu
-* Interpretation contexts::
-* Explaining the Internals Reference::
-* Modifying properties::
-* Useful concepts and properties::
-* Common properties::
-* Advanced tweaks::
-* Discussion of specific tweaks::
+* Interpretation contexts::     
+* Explaining the Internals Reference::  
+* Modifying properties::        
+* Useful concepts and properties::  
+* Common properties::           
+* Advanced tweaks::             
+* Discussion of specific tweaks::  
 @end menu
 
 
@@ -86,22 +89,23 @@ on entering numbers, lists, strings, and symbols in Scheme.}
 This section describes what contexts are, and how to modify them.
 
 @menu
-* Contexts explained::
-* Creating contexts::
-* Modifying context plug-ins::
-* Changing context default settings::
-* Defining new contexts::
-* Aligning contexts::
+* Contexts explained::          
+* Creating contexts::           
+* Modifying context plug-ins::  
+* Changing context default settings::  
+* Defining new contexts::       
+* Aligning contexts::           
 @end menu
 
 
 @node Contexts explained
 @subsection Contexts explained
 
-@c FIXME Rethink and rewrite
+@ignore
+@c TODO Rethink and rewrite
 
 >> > > - list of contexts: my *danger unmaintainable*
->> > > alarm just went off.  I'm 
+>> > > alarm just went off.  I'm
 
 I knew it would... And leaving out some of them is perfectly fine
 with me.
@@ -114,118 +118,156 @@ unmanageable),
 should be there, and then we could simply list the remaining ones
 without
 further explanation and with links to the IR.
+@end ignore
+
+@c TODO Improve layout, order and consistency of wording -td
+
+@c TODO Add introduction which explains contexts in generality  -td
+
+Contexts are arranged heirarchically:
+
+@menu
+* Score - the master of all contexts::  
+* Top-level contexts - staff containers::  
+* Intermediate-level contexts - staves::  
+* Bottom-level contexts - voices::  
+@end menu
+
+@node Score - the master of all contexts
+@unnumberedsubsubsec Score - the master of all contexts
+
+This is the top level notation context. No other context can
+contain a Score context. By default the Score context handles
+the administration of time signatures and makes sure that items
+such as clefs, time signatures, and key-signatures are aligned
+across staves.
+
+A Score context is instantiated implicitly when a
+@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
+processed, or explicitly when a @code{\new Score} command is
+executed.
+
+@node Top-level contexts - staff containers
+@unnumberedsubsubsec Top-level contexts - staff containers
+
+@strong{@emph{StaffGroup}}
+
+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
+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.
+
+@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
+connected vertically.
+
+@strong{@emph{PianoStaff}}
+
+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.
+
+@strong{@emph{InnerStaffGroup}}
+
+TODO  -td
+
+@strong{@emph{InnerChoirStaff}}
+
+TODO  -td
+
+@node Intermediate-level contexts - staves
+@unnumberedsubsubsec Intermediate-level contexts - staves
+
+@strong{@emph{Staff}}
+
+Handles clefs, bar lines, keys, accidentals. It can contain
+Voice contexts.
+
+@strong{@emph{RhythmicStaff}}
+
+Like 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
+expression out as a guitar tablature, printed on six lines.
+
+@strong{@emph{DrumStaff}}
+
+Handles typesetting for percussion. Can contain DrumVoice
+
+@strong{@emph{VaticanaStaff}}
+
+Same as 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
+a piece in mensural style.
 
-The Master Of All Contexts
-==========================
-
-    * Score
-        This is the top level notation context. No other context
-can
-        contain a Score context. This context handles the
-        administration of time signatures. It also makes sure that
-        items such as clefs, time signatures, and key-signatures
-are
-        aligned across staves.
-        You cannot explicitly instantiate a Score context (since
-it is
-        not contained in any other context). It is instantiated
-        automatically when an output definition (a \score or
-\layout
-        block) is processed. 
-        (it should also be made clear somewhere what the
-difference is between
-        \score and \Score).
-
-Top-level contexts: Staff containers
-====================================
-    * StaffGroup
-        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 of staves, with a bracket in front and spanning
-bar
-        lines.
-    * ChoirStaff
-        Identical to StaffGroup except that the contained staves
-are
-        not connected vertically.
-    * GrandStaff
-        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.
-    * PianoStaff
-        Just like GrandStaff but with a forced distance between
-the
-        staves, so cross staff beaming and slurring can be used.
-    * DrumStaff
-        Handles typesetting for percussion. Can contain DrumVoice
-    * InnerStaffGroup
-    * InnerChoirStaff
-
-Staff-level contexts
-====================
-    * Staff
-        Handles clefs, bar lines, keys, accidentals. It can
-contain
-        Voice contexts.
-    * RhythmicStaff
-        Like Staff but for printing rhythms. Pitches are
-        ignored; the notes are printed on one line.
-    * TabStaff
-        Context for generating tablature. By default lays the
-music
-        expression out as a guitar tablature, printed on six
-lines.
-    * VaticanaStaff
-        Same as Staff, except that it is accommodated for
-        typesetting a piece in gregorian style. 
-    * MensuralStaff
-        Same as Staff, except that it is accommodated for
-        typesetting a piece in mensural style. 
-
-Voice-level (bottom) contexts
-=============================
-What is generated by default here?  The voice-level contexts
-initiate
-certain properties and start engravers. 
-
-    * Voice 
-        Corresponds to a voice on a staff. This context handles
-the
-        conversion of dynamic signs, stems, beams, super- and
-        subscripts, slurs, ties, and rests.
-        You have to instantiate this explicitly if you want to
-have
-        multiple voices on the same staff. 
-        Bottom context.
-    * VaticanaVoice
-        Same as Voice, except that it is accommodated for
-        typesetting a piece in gregorian style.  
-    * MensuralVoice
-        Same as Voice, except that it is accommodated for
-        typesetting a piece in mensural style. 
-    * Lyrics
-        Corresponds to a voice with lyrics. Handles the printing
-of a
-        single line of lyrics.
-        Bottom context.
-    * DrumVoice
-        A voice on a percussion staff.
-    * FiguredBass
-         
-    * ChordNames
-        Typesets chord names.  This context is a `bottom' context;
-it
-        cannot contain other contexts.
+@node Bottom-level contexts - voices
+@unnumberedsubsubsec Bottom-level contexts - voices
+
+Voice-level contexts initialise certain properties and start
+appropriate engravers.  Being bottom-level contexts, they cannot
+contain other contexts.
+
+@strong{@emph{Voice}}
+
+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.
+
+@strong{@emph{MensuralVoice}}
+
+Same as Voice, with modifications for typesetting a piece in
+mensural style.
+
+@strong{@emph{Lyrics}}
+
+Corresponds to a voice with lyrics. Handles the printing of a
+single line of lyrics.
+
+@strong{@emph{DrumVoice}}
+
+The voice context used in a percussion staff.
+
+@strong{@emph{FiguredBass}}
+
+The context in which 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.
+
+@strong{@emph{ChordNames}}
+
+Typesets chord names.
 
 ------------------------------
+
+TODO
+
 Then the following, which I don't know what to do with:
 
-    * TabVoice
     * GregorianTranscriptionVoice
     * GregorianTranscriptionStaff
 
@@ -245,7 +287,6 @@ documented.
 context.
 
 
-
 @node Creating contexts
 @subsection Creating contexts
 
@@ -499,7 +540,7 @@ time signature.
 @subsection Changing context default settings
 
 The adjustments of the previous subsections (
-@ref{The \set command}, @ref{Modifying context plug-ins}, and
+@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,
 
@@ -661,7 +702,7 @@ The notes look like a slash, and have no stem,
 
 All these plug-ins have to cooperate, and this is achieved with a
 special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @rinternals{Engraver_group},
+This should always be @code{Engraver_group}.
 
 @example
 \type "Engraver_group"
@@ -797,9 +838,9 @@ Internals Reference: @rinternals{Fingering}.
 @c  outdated info; probably will delete.
 @ignore
 This fragment points to two parts of the program reference: a page
-on @code{FingerEvent} and one on @code{Fingering}.
+on @code{FingeringEvent} and one on @code{Fingering}.
 
-The page on @code{FingerEvent} describes the properties of the music
+The page on @code{FingeringEvent} describes the properties of the music
 expression for the input @code{-2}.  The page contains many links
 forward.  For example, it says
 
@@ -815,7 +856,7 @@ plug-in, which says
 This engraver creates the following layout objects: @rinternals{Fingering}.
 @end quotation
 
-In other words, once the @code{FingerEvent}s are interpreted, the
+In other words, once the @code{FingeringEvent}s are interpreted, the
 @code{Fingering_engraver} plug-in will process them.
 @end ignore
 
@@ -861,7 +902,7 @@ Music types accepted: @rinternals{fingering-event}
 
 @item @rinternals{fingering-event}:
 Music event type @code{fingering-event} is in Music expressions named
-@rinternals{FingerEvent}
+@rinternals{FingeringEvent}
 @end itemize
 
 This path goes against the flow of information in the program: it
@@ -1059,7 +1100,7 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
 @subsection Naming conventions
 
 Another thing that is needed, is an overview of the various naming
-conventions: 
+conventions:
 
     scheme functions: lowercase-with-hyphens (incl. one-word
 names)
@@ -1084,10 +1125,10 @@ LP-specific?
 
 @menu
 * Overview of modifying properties::  
-* The \set command::            
-* The \override command::       
-* \set versus \override::       
-* Objects connected to the input::  
+* The set command::             
+* The override command::        
+* set versus override::         
+* The tweak command::           
 @end menu
 
 
@@ -1205,7 +1246,7 @@ or crashes, or both.
 
 
 
-@node The \set command
+@node The set command
 @subsection The @code{\set} command
 
 @cindex properties
@@ -1330,7 +1371,7 @@ Translation @expansion{} Tunable context properties.
 
 
 
-@node The \override command
+@node The override command
 @subsection The @code{\override} command
 
 Commands which change output generally look like
@@ -1372,7 +1413,7 @@ We demonstrate how to glean this information from the notation manual
 and the program reference.
 
 
-@node \set versus \override
+@node set versus override
 @subsection @code{\set} vs. @code{\override}
 
 We have seen two methods of changing properties: @code{\set} and
@@ -1423,8 +1464,8 @@ objects.  Since this is a common change, the special
 property (modified with @code{\set}) was created.
 
 
-@node Objects connected to the input
-@subsection Objects connected to the input
+@node The tweak command
+@subsection The @code{\tweak} command
 
 TODO: can't use \tweak in a variable
 
@@ -1477,10 +1518,10 @@ details.
 
 
 @menu
-* Input modes::
-* Direction and placement::
-* Distances and measurements::
-* Spanners::
+* Input modes::                 
+* Direction and placement::     
+* Distances and measurements::  
+* Spanners::                    
 @end menu
 
 @node Input modes
@@ -1692,21 +1733,358 @@ have special properties to control their appearance and behaviour.
 Some of these properties are common to all spanners; others are
 restricted to a sub-set of the spanners.
 
-
 @node Common properties
 @section Common properties
 
 @menu
-* Controlling visibility of objects::
-* Line styles::
-* Rotating objects::
-* Aligning objects::
+* Controlling visibility of objects::  
+* Line styles::                 
+* Rotating objects::            
+* Aligning objects::            
 @end menu
 
 @node Controlling visibility of objects
 @subsection Controlling visibility of objects
 
-@c FIXME Write this section
+@cindex objects, visibility of
+@cindex grobs, visibility of
+@cindex visibility of objects
+
+There are four main ways in which the visibility of layout objects
+can be controlled: their stencil can be removed, they can be made
+transparent, they can be colored white, or their
+@code{break-visibility} property can be overridden.  The first
+three apply to all layout objects; the last to just a few -- the
+@emph{breakable} objects.  The Learning Manual introduces these
+four techniques, see @rlearning{Visibility and color of objects}.
+
+There are also a few other techniques which are specific to
+certain layout objects.  These are covered under Special
+considerations.
+
+@menu
+* Removing the stencil::        
+* Making objects transparent::  
+* Painting objects white::      
+* Using break-visibility::      
+* Special considerations::      
+@end menu
+
+
+@node Removing the stencil
+@unnumberedsubsubsec Removing the stencil
+
+@cindex stencil, removing
+
+Every layout object has a stencil property.  By default this is set
+to the specific function which draws that object.  If this property
+is overridden to @code{#f} no function will be called and the object
+will not be drawn.  The default action can be recovered with
+@code{\revert}.
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\override Score.BarLine #'stencil = ##f
+a a
+\revert Score.BarLine #'stencil
+a a a
+@end lilypond
+
+@node Making objects transparent
+@unnumberedsubsubsec Making objects transparent
+
+@cindex transparent, making objects
+
+Every layout object has a transparent property which by default is
+set to @code{#f}.  If set to @code{#t} the object still occupies
+space but is made invisible.
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \override NoteHead #'transparent = ##t
+a a
+@end lilypond
+
+@node Painting objects white
+@unnumberedsubsubsec Painting objects white
+
+@cindex objects, coloring
+@cindex coloring objects
+@cindex layers
+@cindex printing order
+@cindex overwriting objects
+@cindex objects, overwriting
+@cindex grobs, overwriting
+
+Every layout object has a color property which by default is set
+to @code{black}.  If this is overridden to @code{white} the object
+will be indistinguishable from the white background.  However,
+if the object crosses other objects the color of the crossing
+points will be determined by the order in which they are drawn,
+and this may leave a ghostly image of the white object, as shown
+here:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+a1
+@end lilypond
+
+This may be avoided by changing the order of printing the objects.
+All layout objects have a @code{layer} property which should be set
+to an integer.  Objects with the lowest value of @code{layer} are
+drawn first, then objects with progressively higher values are drawn,
+so objects with higher values overwrite objects with lower values.
+By default most objects are assigned a @code{layer} value of
+@code{1}, although a few objects, including @code{StaffSymbol} and
+@code{BarLine}, are assigned a value of @code{0}.  The order of
+printing objects with the same value of @code{layer} is indeterminate.
+
+In the example above the white clef, with a default @code{layer}
+value of @code{1}, is drawn after the staff lines (default
+@code{layer} value @code{0}), so overwriting them.  To change this,
+the @code{Clef} object must be given in a lower value of
+@code{layer}, say @code{-1}, so that it is drawn earlier:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+\override Staff.Clef #'layer = #-1
+a1
+@end lilypond
+
+@node Using break-visibility
+@unnumberedsubsubsec Using break-visibility
+
+@c TODO Add making other objects breakable
+
+@cindex break-visibility
+
+Most layout objects are printed only once, but some like
+bar lines, clefs, time signatures and key signatures, may need
+to be printed twice when a line break occurs -- once at the end
+of the line and again at the start of the next line.  Such
+objects are called @emph{breakable}, and have a property, the
+@code{break-visibility} property to control their visibility
+at the three positions in which they may appear -- at the
+start of a line, within a line if they are changed, and at the
+end of a line if a change takes place there.
+
+For example, the time signature
+by default will be printed at the start of the first line, but
+nowhere else unless it changes, when it will be printed at the
+point at which the change occurs.  If this change occurs at the
+end of a line the new time signature will be printed at the start
+of the next line and a cautionary time signature will be printed
+at the end of the previous line as well.
+
+This behaviour is controlled by the @code{break-visibility}
+property, which is explained in
+@c Leave this ref on a newline - formats incorrectly otherwise -td
+@rlearning{Visibility and color of objects}.  This property takes
+a vector of three booleans which, in order, determine whether the
+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
+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
+@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{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
+@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
+@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
+default setting of this property:
+
+@multitable @columnfractions .3 .3 .4
+
+@headitem Layout object   @tab Usual context  @tab Default setting
+
+@c omit Ambitus as it appears not to be affected by break-visibility -td
+@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
+@item @code{BarLine}             @tab @code{Score}          @tab calculated
+@item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
+@c omit the following item until it can be explained -td
+@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
+@item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
+@item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
+@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
+@c omit KeyCancellation until it can be explained -td
+@c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
+@item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@c omit LeftEdge until it can be explained -td
+@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
+@item @code{OctavateEight}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
+@item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}
+
+@end multitable
+
+The example below shows the use of the vector form to control the
+visibility of barlines:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+f4 g a b
+f4 g a b
+% Remove bar line at the end of the current line
+\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+Although all three components of the vector used to override
+@code{break-visibility} must be present, not all of them are
+effective with every layout object, and some combinations may
+even give errors.  The following limitations apply:
+
+@itemize @bullet
+@item Bar lines cannot be printed at start of line.
+@item A bar number cannot be printed at the start of the first
+line unless it is set to be different from 1.
+@item Clef -- see below
+@item Double percent repeats are either all printed or all
+suppressed.  Use begin-of line-invisible to print and
+all-invisible to suppress.
+@item Key signature -- see below
+@item OctavateEight -- see below
+@end itemize
+
+@node Special considerations
+@unnumberedsubsubsec Special considerations
+
+@strong{@emph{Visibility following explicit changes}}
+
+@cindex key signature, visibility following explicit change
+@cindex explicitKeySignatureVisibility
+@cindex clef, visibility following explicit change
+@cindex explicitClefVisibility
+
+The @code{break-visibility} property controls the visibility of
+key signatures and changes of clef only at the start of lines,
+i.e. after a break.  It has no effect on the visibility of the
+key signature or clef following an explicit key change or an
+explicit clef change within or at the end of a line.  In the
+following example the key signature following the explicit change
+to B-flat major is still visible, even though @code{all-invisible}
+is set.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+% Try to remove all key signatures
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+The visibility of such explicit key signature and clef changes is
+controlled by the @code{explicitKeySignatureVisibility} and
+@code{explicitClefVisibility} properties.  These are the equivalent
+of the @code{break-visibility} property and both take a vector of
+three booleans or the predefined functions listed above, exactly like
+@code{break-visibility}.  Both are properties of the Staff context,
+not the layout objects themselves, and so they are set using the
+@code{\set} command.  Both are set by default to @code{all-visible}.
+These properties control only the visibility of key signatures and
+clefs resulting from explicit changes and do not affect key
+signatures and clefs at the beginning of lines;
+@code{break-visibility} must still be overridden in the appropriate
+object to remove these.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+@strong{@emph{Visibility of cautionary accidentals}}
+
+To remove the cautionary accidentals printed at an explicit key
+change, set the Staff context property @code{printKeyCancellation}
+to @code{#f}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+With these overrides only the accidentals before the notes remain
+to indicate the change of key.
+
+@c TODO Add visibility of cautionary accidentals before notes
+
+@strong{@emph{Automatic bars}}
+
+@cindex automaticBars
+@cindex bar lines, suppressing
+
+As a special case, the printing of bar lines can also be turned off
+by setting the @code{automaticBars} property in the Score context.
+If set to @code{#f}, bar lines will not be printed automatically;
+they must be explicitly created with a @code{\bar} command.  Unlike
+the @code{\cadenzaOn} predefined command, measures are still counted.
+Bar generation will resume according to that count if this property
+is later set to @code{#t}.  When set to @code{#f}, line breaks can
+occur only at explicit @code{\bar} commands.
+
+@c TODO Add example
+
+@strong{@emph{Octavated clefs}}
+
+@cindex octavated clefs, visibility of
+@cindex visibility of octavated clefs
+@cindex clefs, visibility of octavation
+
+The small octavation symbol on octavated clefs is produced by the
+@code{OctavateEight} layout object.  Its visibility is controlled
+independently from that of the @code{Clef} object, so it is
+necessary to apply any required @code{break-visibility} overrides
+to both the @code{Clef} and the @code{OctavateEight} layout objects
+to fully suppress such clef symbols at the start of each line.
+
+For explicit clef changes, the @code{explicitClefVisibility}
+property controls both the clef symbol and any octavation symbol
+associated with it.
+
+
+@seealso
+Learning Manual:
+@rlearning{Visibility and color of objects}
+
 
 @node Line styles
 @subsection Line styles
@@ -1744,7 +2122,7 @@ d,2 \glissando d'2
 
 The information that determines the end-points is computed
 on-the-fly for every graphic object, but it is possible to
-override these. 
+override these.
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
@@ -1760,14 +2138,14 @@ right end point.  Of course, it is also possible to adjust the
 left side with @code{left} instead of @code{right}.
 
 If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner. 
+position of right attachment point of the spanner.
 
 In case of a line break, the values for the span-points are
 extended with contents of the @code{left-broken} and
 @code{right-broken} sublists, for example
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T 
+\override Glissando #'breakable = ##T
 \override Glissando #'bound-details #'right-broken #'Y = #-3
 c1 \glissando \break
 f1
@@ -1792,7 +2170,7 @@ head it is attached to.
 
 @item X
 This is the absolute coordinate of the end point.  It is usually
-computed on the fly, and there is little use in overriding it. 
+computed on the fly, and there is little use in overriding it.
 
 @item stencil
 Line spanners may have symbols at the beginning or end, which is
@@ -1869,7 +2247,65 @@ Internals Reference: @rinternals{TextSpanner},
 @node Rotating objects
 @subsection Rotating objects
 
-@c FIXME Write this section
+Both layout objects and elements of markup text can be rotated by
+any angle about any point, but the method of doing so differs.
+
+@menu
+* Rotating layout objects::     
+* Rotating markup::             
+@end menu
+
+@node Rotating layout objects
+@unnumberedsubsubsec Rotating layout objects
+
+@cindex rotating objects
+@cindex objects, rotating
+
+All layout objects which support the @code{grob-interface} can be
+rotated by setting their @code{rotation} property.  This takes a
+list of three items: the angle of rotation counter-clockwise,
+and the x and y coordinates of the point relative to the object's
+reference point about which the rotation is to be performed.  The
+angle of rotation is specified in degrees and the coordinates in
+staff-spaces.
+
+The angle of rotation and the coordinates of the rotation point must
+be determined by trial and error.
+
+@cindex hairpins, angled
+@cindex angled hairpins
+
+There are only a few situations where the rotation of layout
+objects is useful; the following example shows one situation where
+they may be:
+
+@lilypond[quote,verbatim,relative=1]
+g4\< e' d' f\!
+\override Hairpin #'rotation = #'(20 -1 0)
+g,,4\< e' d' f\!
+@end lilypond
+
+@node Rotating markup
+@unnumberedsubsubsec Rotating markup
+
+All markup text can be rotated to lie at any angle by prefixing it
+with the @code{\rotate} command.  The command takes two arguments:
+the angle of rotation in degrees counter-clockwise and the text to
+be rotated.  The extents of the text are not rotated: they take
+their values from the extremes of the x and y coordinates of the
+rotated text.  In the following example the
+@code{outside-staff-priority} property for text is set to @code{#f}
+to disable the automatic collision avoidance, which would push some
+of the text too high.
+
+@lilypond[quote,verbatim,relative=1]
+\override TextScript #'outside-staff-priority = ##f
+g4^\markup { \rotate #30 "a G" }
+b^\markup { \rotate #30 "a B" }
+des^\markup { \rotate #30 "a D-Flat" }
+fis^\markup { \rotate #30 "an F-Sharp" }
+@end lilypond
+
 
 @node Aligning objects
 @subsection Aligning objects
@@ -1881,9 +2317,10 @@ Internals Reference: @rinternals{TextSpanner},
 @section Advanced tweaks
 
 @menu
-* Vertical grouping of grobs::
-* Modifying ends of spanners::
-* Modifying stencils::
+* Vertical grouping of grobs::  
+* Modifying ends of spanners::  
+* Modifying stencils::          
+* Modifying shapes::            
 @end menu
 
 
@@ -1906,18 +2343,148 @@ VerticalAxisGroup.
 @subsection Modifying ends of spanners
 
 @c FIXME Write this section
+@c See earlier material in Line styles
 
 @node Modifying stencils
 @subsection Modifying stencils
 
-@c FIXME Write this section
+All layout objects have a @code{stencil} property which is part of
+the @code{grob-interface}.  By default, this property is usually
+set to a function specific to the object that is tailor-made to
+render the symbol which represents it in the output.  For example,
+the standard setting for the @code{stencil} property of the
+@code{MultiMeasureRest} object is @code{ly:multi-measure-rest::print}.
+
+The standard symbol for any object can be replaced by modifying the
+@code{stencil} property to reference a different, specially-written,
+procedure.  This requires a high level of knowledge of the internal
+workings of LilyPond, but there is an easier way which can often
+produce adequate results.
+
+This is to set the @code{stencil} property to the procedure which
+prints text -- @code{ly:text-interface::print} -- and to add a
+@code{text} property to the object which is set to contain the
+markup text which produces the required symbol.  Due to the
+flexibility of markup, much can be achieved -- see in particular
+@ref{Graphic notation inside markup}.
+
+The following example demonstrates this by changing the note head
+symbol to a cross within a circle.
+
+@lilypond[verbatim,quote]
+XinO = {
+  \once \override NoteHead  #'stencil = #ly:text-interface::print
+  \once \override NoteHead #'text = \markup {
+    \combine
+      \halign #-0.7 \draw-circle #0.85 #0.2 ##f
+      \musicglyph #"noteheads.s2cross"
+  }
+}
+\relative c'' {
+  a a \XinO a a
+}
+@end lilypond
+
+Any of the glyphs in the feta Font can be supplied to the
+@code{\musicglyph} markup command -- see @ref{The Feta font}.
+
+@c TODO Add inserting eps files or ref to later
+
+@c TODO Add inserting Postscript or ref to later
+
+@seealso
+
+Notation Reference:
+@ref{Graphic notation inside markup},
+@ref{Formatting text},
+@ref{Text markup commands},
+@ref{The Feta font}.
+
+
+@node Modifying shapes
+@subsection Modifying shapes
+
+@menu
+* Modifying ties and slurs::
+@end menu
+
+@node Modifying ties and slurs
+@unnumberedsubsubsec Modifying ties and slurs
+
+Ties, slurs and phrasing slurs are drawn as third-order Bézier
+curves.  If the shape of the tie or slur which is calculated
+automatically is not optimum, the shape may be modified manually by
+explicitly specifying the four control points required to define
+a third-order Bézier curve.
+
+Third-order or cubic Bézier curves are defined by four control
+points.  The first and fourth control points are precisely the
+starting and ending points of the curve.  The intermediate two
+control points define the shape.  Animations showing how the curve
+is drawn can be found on the web, but the following description
+may be helpful.  The curve starts from the first control point
+heading directly towards the second, gradually bending over to
+head towards the third and continuing to bend over to head towards
+the fourth, arriving there travelling directly from the third
+control point.  The curve is entirely contained in the
+quadrilateral defined by the four control points.
+
+Here is an example of a case where the tie is not optimum, and
+where @code{\tieDown} would not help.
+
+@lilypond[verbatim,quote,relative=1]
+<<
+  { e1 ~ e }
+\\
+  { r4 <g c,> <g c,> <g c,> }
+>>
+@end lilypond
+
+One way of improving this tie is to manually modify its control
+points, as follows.
+
+The coordinates of the Bézier control points are specified in units
+of staff-spaces.  The X@tie{}coordinate is relative to the reference
+point of the note to which the tie or slur is attached, and the
+Y@tie{}coordinate is relative to the staff center line.  The
+coordinates are entered as a list of four pairs of decimal numbers
+(reals).  One approach is to estimate the coordinates of the two
+end points, and then guess the two intermediate points.  The optimum
+values are then found by trial and error.
+
+It is useful to remember that a symmetric curve requires symmetric
+control points, and that Bézier curves have the useful property that
+transformations of the curve such as translation, rotation and
+scaling can be achieved by applying the same transformation to the
+curve's control points.
+
+For the example above the following override gives a satisfactory
+tie:
+
+@lilypond[verbatim,quote,relative=1]
+<<
+  \once \override Tie
+    #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+  { e1 ~ e1 }
+\\
+  { r4 <g c,> <g c,> <g c,>4  }
+>>
+@end lilypond
+
+@knownissues
+
+It is not possible to modify shapes of ties or slurs by changing
+the @code{control-points} property if there are more than one at
+the same musical moment, not even by using the @code{\tweak}
+command.
+
 
 
 @node Discussion of specific tweaks
 @section Discussion of specific tweaks
 
 @menu
-* old Contexts explained::
+* old Contexts explained::      
 @end menu