From 3b65aea88185c2ce92b1a905e0535d7d4c60d71a Mon Sep 17 00:00:00 2001 From: Mark Polesky Date: Thu, 5 Jun 2014 10:00:17 -0700 Subject: [PATCH] Issue 3926: Add \magnifyMusic; clarify fontSize in docs. --- Documentation/changes.tely | 21 ++ Documentation/notation/editorial.itely | 240 ++++++++++++++---- Documentation/notation/spacing.itely | 167 ++++++------ .../magnifyMusic-stem-beam-spacing.ly | 22 ++ ly/music-functions-init.ly | 25 +- scm/define-grob-properties.scm | 4 +- 6 files changed, 346 insertions(+), 133 deletions(-) create mode 100644 input/regression/magnifyMusic-stem-beam-spacing.ly diff --git a/Documentation/changes.tely b/Documentation/changes.tely index 1041dcd878..71320d7ea5 100644 --- a/Documentation/changes.tely +++ b/Documentation/changes.tely @@ -60,6 +60,27 @@ which scares away people. * 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 + 4 8. 16 8 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 diff --git a/Documentation/notation/editorial.itely b/Documentation/notation/editorial.itely index 630aa6690f..34822b3da7 100644 --- a/Documentation/notation/editorial.itely +++ b/Documentation/notation/editorial.itely @@ -49,62 +49,207 @@ inside the staff. @funindex fontSize @funindex font-size +@funindex magnification->font-size @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 \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 + 4 8. 16 8 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 +-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] -\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 -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] -\set fontSize = #3 +\teeny c4.-> d8---3 -\override NoteHead.font-size = #-4 +\tiny c4.-> d8---3 -\override Script.font-size = #2 +\small c4.-> d8---3 -\override Stem.font-size = #-5 +\normalsize +c4.-> d8---3 +\large +c4.-> d8---3 +\huge c4.-> d8---3 @end lilypond + @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 -@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. -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 +@code{\magnifyMusic}, @code{\teeny}, @code{\tiny}, @code{\small}, @@ -131,6 +273,16 @@ that use fonts. These are the ones supporting the @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}. diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely index 1ce8ec5c13..3ee12b6798 100644 --- 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. -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 @@ -1267,92 +1243,109 @@ Snippets: @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 -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 -\score@{ +\score @{ @dots{} \layout @{ - #(layout-set-staff-size 15) + #(layout-set-staff-size 14) @} @} @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: -@quotation @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 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: diff --git a/input/regression/magnifyMusic-stem-beam-spacing.ly b/input/regression/magnifyMusic-stem-beam-spacing.ly new file mode 100644 index 0000000000..2ca15238a0 --- /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 bdad824fe8..9e5d3c223b 100644 --- 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.")))) +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.") @@ -754,7 +777,7 @@ appropriate tweak applied.") \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}, diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm index de05ace923..6f080aeb2d 100644 --- 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 -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.") -- 2.39.2