Issue 3926: Add \magnifyMusic; clarify fontSize in docs.

diff --git a/Documentation/changes.tely b/Documentation/changes.tely
index 1041dcd878655ce3b9644f62e7428123ce39e5aa..71320d7ea56c5fecb0540a710c69eb0cbf5a9cf0 100644 (file)
--- a/Documentation/changes.tely
+++ b/Documentation/changes.tely
@@ -60,6 +60,27 @@ which scares away people.
 * only show user-visible changes.
 
 @end ignore
 * only show user-visible changes.
 
 @end ignore

+@item
+A new command @code{\magnifyMusic} has been added, which allows
+the notation size to be changed without changing the staff size,
+while automatically scaling stems, beams, and horizontal spacing.
+
+@lilypond[verbatim,quote]
+\new Staff <<
+  \new Voice \relative {
+    \voiceOne
+    <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
+  }
+  \new Voice \relative {
+    \voiceTwo
+    \magnifyMusic 0.63 {
+      r32 c'' a c a c a c r c a c a c a c
+      r c a c a c a c a c a c a c a c
+    }
+  }
+>>
+@end lilypond
+

 @item
 A new flexible template suitable for a range of choral music, is now
 provided.  This may be used to create simple choral music, with or
 @item
 A new flexible template suitable for a range of choral music, is now
 provided.  This may be used to create simple choral music, with or

diff --git a/Documentation/notation/editorial.itely b/Documentation/notation/editorial.itely
index 630aa6690f568cfeba446583e8791e7f476249bf..34822b3da70912c770cad3c12cf66cfc99052d8b 100644 (file)
--- a/Documentation/notation/editorial.itely
+++ b/Documentation/notation/editorial.itely
@@ -49,62 +49,207 @@ inside the staff.
 
 @funindex fontSize
 @funindex font-size
 
 @funindex fontSize
 @funindex font-size

+@funindex magnification->font-size

 @funindex magstep
 @funindex magstep

-@funindex \huge
-@funindex \large
+@funindex magnifyMusic
+@funindex teeny
+@funindex tiny
+@funindex small
+@funindex normalsize
+@funindex large
+@funindex huge
+@funindex \magnifyMusic
+@funindex \teeny
+@funindex \tiny

 @funindex \normalsize
 @funindex \small
 @funindex \normalsize
 @funindex \small

-@funindex \tiny
-@funindex \teeny
-@funindex huge
-@funindex large
-@funindex normalsize
-@funindex small
-@funindex tiny
-@funindex teeny
+@funindex \large
+@funindex \huge
+
+@warning{@*
+For font sizes of text, see @ref{Selecting font and font size}.@*
+For staff size, see @ref{Setting the staff size}.@*
+For cue notes, see @ref{Formatting cue notes}.@*
+For ossia staves, see @ref{Ossia staves}.}

 
 

-The font size of notation elements may be altered.  It does not
-change the size of variable symbols, such as beams or slurs.
+To change the size of the notation without changing the staff
+size, specify a magnification factor with the @code{\magnifyMusic}
+command:
+
+@c Grieg Piano Concerto (mvt.1 cadenza)
+@lilypond[verbatim,quote]
+\new Staff <<
+  \new Voice \relative {
+    \voiceOne
+    <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
+  }
+  \new Voice \relative {
+    \voiceTwo
+    \magnifyMusic 0.63 {
+      r32 c'' a c a c a c r c a c a c a c
+      r c a c a c a c a c a c a c a c
+    }
+  }
+>>
+@end lilypond

 
 

-@warning{For font sizes of text, see
-@ref{Selecting font and font size}.}
+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 {
+      \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=1]
+% 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=2]
 
 @lilypond[verbatim,quote,relative=2]

-\huge
-c4.-> d8---3
-\large
-c4.-> d8---3
-\normalsize
-c4.-> d8---3
-\small
-c4.-> d8---3
-\tiny
-c4.-> d8---3
-\teeny
-c4.-> d8---3
+\time 3/4
+d4---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.
+@end lilypond
+
+The @code{fontSize} value is a number indicating the size relative
+to the standard size for the current staff height.  The default
+@code{fontSize} is 0; adding 6 to any @code{fontSize} value
+doubles the printed size of the glyphs, and subtracting 6 halves
+the size.  Each step increases the size by approximately 12%.
+
+The scheme function @code{magnification->font-size} is provided
+for convenience since the logarithmic units of the
+@code{font-size} property are not entirely intuitive.  For
+example, to adjust the musical notation to 75% of the default
+size, use:
+
+@example
+\set fontSize = #(magnification->font-size 0.75)
+@end example
+
+The scheme function @code{magstep} does the opposite: it converts
+a @code{font-size} value into a magnification factor.
+
+The @code{fontSize} property will only affect notational elements
+that are drawn with glyphs, such as noteheads, accidentals,
+scripts, etc.  It will not affect the size of the staff itself,
+nor will it scale stems, beams, or horizontal spacing.  To scale
+stems, beams, and horizontal spacing along with the notation size
+(without changing the staff size), use the @code{\magnifyMusic}
+command discussed above.  To scale everything, including the staff
+size, see @ref{Setting the staff size}.
+
+Whenever the @code{fontSize} @i{context property} is set, its
+value is added to the value of the @code{font-size} @i{grob
+property} for individual layout objects, before any glyphs are
+printed.  This can cause confusion when setting individual
+@code{font-size} properties while @code{fontSize} is already set:
+
+@lilypond[verbatim,quote,relative=2]
+% the default font-size for NoteHead is 0
+% the default font-size for Fingering is -5
+c4-3
+
+\set fontSize = -3
+% the effective font size for NoteHead is now -3
+% the effective font size for Fingering is now -8
+c4-3
+
+\override Fingering.font-size = 0
+% the effective font size for Fingering is now -3
+c4-3

 @end lilypond
 
 @end lilypond
 

-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.
+The following shorthand commands are also available:
+
+@multitable @columnfractions .2 .4 .4
+@item @b{Command} @tab @b{Equivalent to} @tab @b{Relative size}
+@item @code{\teeny}      @tab @code{\set fontSize = -3} @tab 71%
+@item @code{\tiny}       @tab @code{\set fontSize = -2} @tab 79%
+@item @code{\small}      @tab @code{\set fontSize = -1} @tab 89%
+@item @code{\normalsize} @tab @code{\set fontSize = 0} @tab 100%
+@item @code{\large}      @tab @code{\set fontSize = 1} @tab 112%
+@item @code{\huge}       @tab @code{\set fontSize = 2} @tab 126%
+@end multitable

 
 @lilypond[verbatim,quote,relative=2]
 
 @lilypond[verbatim,quote,relative=2]

-\set fontSize = #3
+\teeny

 c4.-> d8---3
 c4.-> d8---3

-\override NoteHead.font-size = #-4
+\tiny

 c4.-> d8---3
 c4.-> d8---3

-\override Script.font-size = #2
+\small

 c4.-> d8---3
 c4.-> d8---3

-\override Stem.font-size = #-5
+\normalsize
+c4.-> d8---3
+\large
+c4.-> d8---3
+\huge

 c4.-> d8---3
 @end lilypond
 
 c4.-> d8---3
 @end lilypond
 

+

 @cindex standard font size (notation)
 @cindex font size (notation), standard
 
 @cindex standard font size (notation)
 @cindex font size (notation), standard
 


@@ -113,15 +258,12 @@ c4.-> d8---3
 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for
 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for

-@w{@code{font-size = #0}}) depends on the standard staff height.
+@w{@code{font-size = 0}}) depends on the standard staff height.

 For a 20pt staff, a 10pt font is selected.
 
 For a 20pt staff, a 10pt font is selected.
 

-The @code{font-size} property can only be set on layout objects
-that use fonts.  These are the ones supporting the
-@code{font-interface} layout interface.
-

 
 @predefined
 
 @predefined

+@code{\magnifyMusic},

 @code{\teeny},
 @code{\tiny},
 @code{\small},
 @code{\teeny},
 @code{\tiny},
 @code{\small},


@@ -131,6 +273,16 @@ that use fonts.  These are the ones supporting the
 @endpredefined
 
 @seealso
 @endpredefined
 
 @seealso

+Notation Reference:
+@ref{Selecting font and font size},
+@ref{Setting the staff size},
+@ref{Formatting cue notes},
+@ref{Ossia staves}.
+
+Installed Files:
+@file{ly/music-functions-init.ly},
+@file{ly/property-init.ly}.
+

 Snippets:
 @rlsr{Editorial annotations}.
 
 Snippets:
 @rlsr{Editorial annotations}.
 

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 1ce8ec5c13ff101c66e1bc020b4e73e61d324f0e..3ee12b679876fdc986ccaabbbb78690b2d7cd06a 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -21,30 +21,6 @@ Negative numbers are allowed:
 > and prints page number -1 on the second page, for example.
 
 
 > and prints page number -1 on the second page, for example.
 
 

-In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
-states:
-
-"@code{layout-set-staff-size} does not change the distance between
-the
-staff lines."
-
-Could we add a sentence:
-"Use instead the pair               fontSize = #@var{N}
-            \override StaffSymbol.staff-space = #(magstep
-@var{N})
-inside the Staff context to change the size of the font and the
-distance between
-staff lines accordingly."
-
-Actually I found, that the @internalsref{StaffSymbol} at line 481
-sends to an incomplete
-documentation.  The property staff-space is not explained here.  I
-thought Y-extent might be of
-help, but it is in turn explained by x-space which again is
-missing from the list.  Who has the
-knowledge to fix this?
-
-

 Clarify
 http://code.google.com/p/lilypond/issues/detail?id=68
 
 Clarify
 http://code.google.com/p/lilypond/issues/detail?id=68
 


@@ -1267,92 +1243,109 @@ Snippets:
 @cindex font size, setting
 @cindex staff size, setting
 @funindex layout file
 @cindex font size, setting
 @cindex staff size, setting
 @funindex layout file

+@funindex magnification->font-size
+@funindex magstep
+@funindex set-global-staff-size
+@funindex layout-set-staff-size

 
 

-The default @strong{staff size} is set to 20 points.
-This may be changed in two ways:
+The default @strong{staff size} is 20 points, which corresponds to
+a staff height of 7.03mm (one point is equal to 100/7227 of an
+inch, or 2540/7227 mm).  The staff size may be changed in three
+ways:

 
 

-To set the staff size globally for all scores in a file (or
-in a @code{book} block, to be precise), use @code{set-global-staff-size}.
+@enumerate
+
+@item
+To set the staff size globally for all scores in a file (or in a
+@code{\book} block, to be precise), use
+@code{set-global-staff-size}:

 
 @example
 #(set-global-staff-size 14)
 @end example
 
 @noindent
 
 @example
 #(set-global-staff-size 14)
 @end example
 
 @noindent

-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+The above example sets the global default staff size to 14pt
+(4.92mm) and scales all fonts accordingly.
+
+@item
+To set the staff size for a single score within a book, use
+@code{layout-set-staff-size} inside that score's @code{\layout}
+block:

 
 

-To set the staff size individually for each score, use

 @example
 @example

-\score@{
+\score @{

   @dots{}
   \layout @{
   @dots{}
   \layout @{

-    #(layout-set-staff-size 15)
+    #(layout-set-staff-size 14)

   @}
 @}
 @end example
 
   @}
 @}
 @end example
 

+@item
+To set the staff size for a single staff within a system, set the
+staff's font-size and staff-space using units relative to the
+score's default staff size.  Using relative units prevents the
+proportion of staff sizes from being altered if the default staff
+size is modified with @code{set-global-staff-size} or
+@code{layout-set-staff-size}.
+
+For example, traditionally engraved chamber music scores with
+piano often used 7mm piano staves while the other staves were up
+to 5/7 as large (if space allowed), or down to 3/5 as large (if
+space was cramped).  To achieve the 5/7 proportion, use:
+
+@example
+\score @{
+  <<
+    \new Staff \with @{
+      fontSize = #(magnification->font-size 5/7)
+      \override StaffSymbol.staff-space = #5/7
+    @} @{ @dots{} @}
+    \new PianoStaff @{ @dots{} @}
+  >>
+@}
+@end example
+
+If you happen to know which @code{fontSize} you wish to use, you
+could use the following form:
+
+@example
+\score @{
+  <<
+    \new Staff \with @{
+      fontSize = -3
+      \override StaffSymbol.staff-space = #(magstep -3)
+    @} @{ @dots{} @}
+    \new PianoStaff @{ @dots{} @}
+  >>
+@}
+@end example
+
+To emulate the look of traditional engraving, it is best to avoid
+reducing the thickness of the staff lines.
+
+@end enumerate
+
+
+@subheading Automatic font weight at different sizes
+

 The Feta font provides musical symbols at eight different
 sizes.  Each font is tuned for a different staff size: at a smaller size
 the font becomes heavier, to match the relatively heavier staff lines.
 The recommended font sizes are listed in the following table:
 
 The Feta font provides musical symbols at eight different
 sizes.  Each font is tuned for a different staff size: at a smaller size
 the font becomes heavier, to match the relatively heavier staff lines.
 The recommended font sizes are listed in the following table:
 

-@quotation

 @multitable @columnfractions .15 .2 .22 .2
 @multitable @columnfractions .15 .2 .22 .2

-
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
-
+@item @b{font name} @tab @b{staff height (pt)} @tab @b{staff height (mm)} @tab @b{use}
+@item feta11 @tab 11.22 @tab 3.9 @tab pocket scores
+@item feta13 @tab 12.60 @tab 4.4 @tab
+@item feta14 @tab 14.14 @tab 5.0 @tab
+@item feta16 @tab 15.87 @tab 5.6 @tab
+@item feta18 @tab 17.82 @tab 6.3 @tab song books
+@item feta20 @tab 20 @tab 7.0 @tab standard parts
+@item feta23 @tab 22.45 @tab 7.9 @tab
+@item feta26 @tab 25.2 @tab 8.9 @tab @c modern rental material?

 @end multitable
 @end multitable

-@end quotation
-
-These fonts are available in any sizes.  The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@rinternals{StaffSymbol}) can be used to tune the size for individual
-staves.  The sizes of individual staves are relative to the global size.

 
 @seealso
 Notation Reference:
 
 @seealso
 Notation Reference:

diff --git a/input/regression/magnifyMusic-stem-beam-spacing.ly b/input/regression/magnifyMusic-stem-beam-spacing.ly
new file mode 100644 (file)
index 0000000..2ca1523
--- /dev/null
+++ b/input/regression/magnifyMusic-stem-beam-spacing.ly
@@ -0,0 +1,22 @@
+\version "2.19.8"
+
+\header {
+  texidoc = "Stem lengths, beam spacing/thickness, and horizontal
+spacing should be scaled along with notation size when using the
+@code{\magnifyMusic} command."
+}
+
+\layout { ragged-right = ##t }
+
+\relative <<
+  { \repeat unfold 7 { g'32[ a b c] } }
+  {
+    \magnifyMusic 0.50 { s8_"50%" }
+    \magnifyMusic 0.63 { s }
+    \magnifyMusic 0.80 { s }
+    \magnifyMusic 1.00 { s_"100%" }
+    \magnifyMusic 1.26 { s }
+    \magnifyMusic 1.59 { s }
+    \magnifyMusic 2.00 { s_"200%" }
+  }
+>>

diff --git a/ly/music-functions-init.ly b/ly/music-functions-init.ly
index bdad824fe81a063f3575897eaedc4e6a6d24dfc7..9e5d3c223b8c32db59a70585bd2bdf7f8478c278 100644 (file)
--- a/ly/music-functions-init.ly
+++ b/ly/music-functions-init.ly
@@ -632,6 +632,29 @@ languageRestore =
       (ly:input-warning location (_ "No other language was defined previously. Ignoring."))))
 
 
       (ly:input-warning location (_ "No other language was defined previously. Ignoring."))))
 
 

+magnifyMusic =
+#(define-music-function (parser location mag mus) (number? ly:music?)
+   (_i "Magnify the notation of @var{mus} without changing the
+staff-size, using @var{mag} as a size factor.  Stems, beams, and
+horizontal spacing are adjusted automatically.")
+   #{
+     \set fontSize = #(magnification->font-size mag)
+     % gives beam-thickness=0.48 when mag=1 (like default),
+     % gives beam-thickness=0.35 when mag=0.63 (like CueVoice)
+     \temporary \override Beam.beam-thickness = #(+ 119/925 (* mag 13/37))
+     \temporary \override Beam.length-fraction = #mag
+     \temporary \override Stem.length-fraction = #mag
+     \temporary \override Stem.thickness = #(* 1.3 (max 1 mag))
+     \temporary \override Score.SpacingSpanner.spacing-increment = #(* 1.2 mag)
+     #mus
+     \set fontSize = 0
+     \revert Beam.beam-thickness
+     \revert Beam.length-fraction
+     \revert Stem.length-fraction
+     \revert Stem.thickness
+     \revert Score.SpacingSpanner.spacing-increment
+   #})
+

 makeClusters =
 #(define-music-function (parser location arg) (ly:music?)
    (_i "Display chords in @var{arg} as clusters.")
 makeClusters =
 #(define-music-function (parser location arg) (ly:music?)
    (_i "Display chords in @var{arg} as clusters.")


@@ -754,7 +777,7 @@ appropriate tweak applied.")
               \override #prop-path = #(offsetter (third prop-path) offsets)
             #}
             (make-music 'Music)))))
               \override #prop-path = #(offsetter (third prop-path) offsets)
             #}
             (make-music 'Music)))))

- 
+

 omit =
 #(define-music-function (parser location item) (symbol-list-or-music?)
    (_i "Set @var{item}'s @samp{stencil} property to @code{#f},
 omit =
 #(define-music-function (parser location item) (symbol-list-or-music?)
    (_i "Set @var{item}'s @samp{stencil} property to @code{#f},

diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index de05ace923e7f933e1c9cc59b6aa3b3797227446..6f080aeb2d5626c7fc3058a8463831055e728ff1 100644 (file)
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -312,7 +312,9 @@ include @code{upright}, @code{italic}, @code{caps}.")
 @q{normal}@tie{}size.  @code{0}@tie{}is style-sheet's normal size,
 @w{@code{-1}} is smaller, @code{+1} is bigger.  Each step of@tie{}1 is
 approximately 12% larger; 6@tie{}steps are exactly a factor@tie{}2
 @q{normal}@tie{}size.  @code{0}@tie{}is style-sheet's normal size,
 @w{@code{-1}} is smaller, @code{+1} is bigger.  Each step of@tie{}1 is
 approximately 12% larger; 6@tie{}steps are exactly a factor@tie{}2

-larger.  Fractional values are allowed.")
+larger.  If the context property @code{fontSize} is set, its value is
+added to this before the glyph is printed.  Fractional values are
+allowed.")

      (footnote ,boolean? "Should this be a footnote or in-note?")
      (footnote-music ,ly:music? "Music creating a footnote.")
      (footnote-text ,markup? "A footnote for the grob.")
      (footnote ,boolean? "Should this be a footnote or in-note?")
      (footnote-music ,ly:music? "Music creating a footnote.")
      (footnote-text ,markup? "A footnote for the grob.")