-Internally, this sets the @code{fontSize} property. This in turn
-causes the @code{font-size} property to be set in all layout
-objects. The value of @code{font-size} is a number indicating the
-size relative to the standard size for the current staff height.
-Each step up is an increase of approximately 12% of the font size.
-Six steps is exactly a factor of two. The Scheme function
-@code{magstep} converts a @code{font-size} number to a scaling
-factor. The @code{font-size} property can also be set directly,
-so that only certain layout objects are affected.
-
-@lilypond[verbatim,quote,relative=2]
-\set fontSize = #3
-c4.-> d8---3
-\override NoteHead #'font-size = #-4
-c4.-> d8---3
-\override Script #'font-size = #2
-c4.-> d8---3
-\override Stem #'font-size = #-5
-c4.-> d8---3
+The @code{\override} in the example above is a bug workaround.
+See the @qq{Known issues and warnings} at the end of this section.
+
+If a normal sized note head is merged with a smaller one, the size
+of the smaller note may need to be reset (with
+@w{@samp{\once@tie{}\normalsize}}) so that the stems and
+accidentals align properly:
+
+@c Chopin Prelude op.28 no.8
+@lilypond[verbatim,quote]
+\new Staff <<
+ \key fis \minor
+ \mergeDifferentlyDottedOn
+ \new Voice \relative {
+ \voiceOne
+ \magnifyMusic 0.63 {
+ \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
+ \once \normalsize cis'32( cis' gis b a fis \once \normalsize d d'
+ \once \normalsize cis, cis' gis b a gis \once \normalsize fis fis'
+ \once \normalsize fis, fis' ais, cis b gis \once \normalsize eis eis'
+ \once \normalsize a, a' bis, d cis b \once \normalsize gis gis')
+ }
+ }
+ \new Voice \relative {
+ \voiceTwo
+ cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
+ }
+>>
+@end lilypond
+
+The @code{\magnifyMusic} command is not intended for cue notes,
+grace notes, or ossia staves---there are more appropriate methods
+of entering each of those constructs. Instead, it is useful when
+the notation size changes in a single instrumental part on one
+staff, and where grace notes are not appropriate, such as in
+cadenza-like passages or in cases such as the above examples.
+Setting the @code{\magnifyMusic} value to 0.63 duplicates the
+dimensions of the @code{CueVoice} context.
+
+@warning{The @code{@bs{}magnifyMusic} command should @i{not} be
+used when also resizing the staff. See @ref{Setting the staff
+size}.}
+
+
+@subsubsubheading Resizing individual layout objects
+
+An individual layout object can be resized by using the
+@code{\tweak} or @code{\override} commands to adjust its
+@code{font-size} property:
+
+@lilypond[quote,verbatim]
+\relative {
+ % resize a note head
+ <f' \tweak font-size -4 b e>-5
+ % resize a fingering
+ bes-\tweak font-size 0 -3
+ % resize an accidental
+ \once \override Accidental.font-size = -4 bes!-^
+ % resize an articulation
+ \once \override Script.font-size = 4 bes!-^
+}
+@end lilypond
+
+The default @code{font-size} value for each layout object is
+listed in the Internals Reference. The @code{font-size} property
+can only be set for layout objects that support the
+@code{font-interface} layout interface. If @code{font-size} is
+not specified in the object's @q{Standard@tie{}settings} list, its
+value is 0. See @rinternals{All layout objects}.
+
+
+@subsubsubheading Understanding the @code{fontSize} property
+
+The @code{fontSize} context property adjusts the relative size of
+all glyph-based notational elements in a context:
+
+@lilypond[verbatim,quote]
+\relative {
+ \time 3/4
+ d''4---5 c8( b a g) |
+ \set fontSize = -6
+ e'4-- c!8-4( b a g) |
+ \set fontSize = 0
+ fis4---3 e8( d) fis4 |
+ g2.
+}