]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/changing-defaults.itely
Merge branch 'master' of ssh://jeancharlesm@git.sv.gnu.org/srv/git/lilypond
[lilypond.git] / Documentation / user / changing-defaults.itely
index 301f34374dfd7c3f02b2374032648260748d3a3b..719e0fb89858001f83577a77649676040c8846f2 100644 (file)
@@ -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
@@ -98,10 +101,11 @@ This section describes what contexts are, and how to modify them.
 @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}}
 
-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.
+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.
+
+@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
 
@@ -762,10 +803,10 @@ ossia = { f4 f f f }
 
 
 @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
@@ -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)
@@ -1083,11 +1124,11 @@ LP-specific?
 @section Modifying properties
 
 @menu
-* Overview of modifying properties::  
-* The \set command::            
-* The \override command::       
-* \set versus \override::       
-* Objects connected to the input::  
+* Overview of modifying properties::
+* The \set command::
+* The \override command::
+* \set versus \override::
+* Objects connected to the input::
 @end menu
 
 
@@ -1692,7 +1733,6 @@ 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
 
@@ -1703,10 +1743,353 @@ restricted to a sub-set of the spanners.
 * Aligning objects::
 @end menu
 
+@c TODO Add new subsection Shapes of objects
+@c which would include Slur shapes
+@c with a Known issue: can't modify shapes with 'control-points if there are
+@c more than one at the same musical moment
+
 @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 +2127,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 +2143,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 +2175,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 +2252,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
@@ -1884,6 +2325,7 @@ Internals Reference: @rinternals{TextSpanner},
 * Vertical grouping of grobs::
 * Modifying ends of spanners::
 * Modifying stencils::
+* Modifying shapes::
 @end menu
 
 
@@ -1912,6 +2354,11 @@ VerticalAxisGroup.
 
 @c FIXME Write this section
 
+@node Modifying shapes
+@subsection Modifying shapes
+
+@c FIXME Write this section
+@c Discussion of Bezier curves and the control-points property
 
 @node Discussion of specific tweaks
 @section Discussion of specific tweaks